@webjsdev/cli 0.10.44 → 0.10.46

package/templates/gallery/modules/gallery/components/gallery-nav.ts

@@ -0,0 +1,54 @@
+// The gallery's left sidebar: a grouped index of every demo, with the current
+// one highlighted (docs-site style). WHY a component and not plain layout markup:
+// the features layout is PRESERVED across a soft navigation (only the page
+// content swaps), so a server-rendered "active" highlight would go stale. This
+// component listens for the router's `webjs:navigate` event and re-derives the
+// active item from location.pathname, so the highlight follows soft-nav. SSR is
+// still correct: `render()` reads the `current` prop (the pathname the layout
+// passes) for the first paint, and the client takes over from location after.
+import { WebComponent, prop, html, signal } from '@webjsdev/core';
+import { FEATURE_GROUPS } from '#modules/gallery/nav.ts';
+
+// Module-scope so the value survives re-renders; set on the client only (SSR
+// reads the `current` prop instead, so it never touches location during render).
+const activePath = signal('');
+
+export class GalleryNav extends WebComponent({ current: prop(String) }) {
+  #onNav = () => activePath.set(location.pathname);
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.#onNav(); // seed from the real URL on hydrate
+    document.addEventListener('webjs:navigate', this.#onNav); // soft-nav (link + navigate())
+    window.addEventListener('popstate', this.#onNav); // back / forward
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    document.removeEventListener('webjs:navigate', this.#onNav);
+    window.removeEventListener('popstate', this.#onNav);
+  }
+
+  render() {
+    // activePath is '' at SSR (and before hydrate), so fall back to the prop.
+    const active = activePath.get() || this.current;
+    const link = (href: string, title: string) => {
+      // Highlight the demo whose route we are on, INCLUDING its subroutes
+      // (/features/auth/dashboard highlights Auth). The trailing slash keeps
+      // /features/stream from matching /features/streaming.
+      const on = active === href || active.startsWith(href + '/');
+      const cls = 'block px-3 py-1.5 rounded-lg no-underline transition-colors ' +
+        (on ? 'bg-accent text-foreground font-medium' : 'text-muted-foreground hover:bg-accent hover:text-foreground');
+      return html`<a href=${href} aria-current=${on ? 'page' : 'false'} class=${cls}>${title}</a>`;
+    };
+    return html`
+      ${FEATURE_GROUPS.map((g) => html`
+        <div class="mb-5">
+          <div class="px-3 mb-1.5 text-[11px] font-semibold uppercase tracking-wider text-muted-foreground/60">${g.label}</div>
+          <nav class="flex flex-col gap-0.5">${g.items.map((i) => link(i.href, i.title))}</nav>
+        </div>
+      `)}
+    `;
+  }
+}
+GalleryNav.register('gallery-nav');

package/templates/gallery/modules/gallery/nav.ts

@@ -0,0 +1,79 @@
+/**
+ * The gallery's demo index, ONE source of truth for both the home cards and the
+ * left sidebar (so they can never drift). A browser-safe data module (no server
+ * imports, no client globals): the home flattens the groups into its card grid,
+ * and <gallery-nav> renders them grouped. gallery:clear removes this module.
+ */
+export interface NavItem { href: string; title: string; blurb: string; }
+export interface NavGroup { label: string; items: NavItem[]; }
+
+export const FEATURE_GROUPS: NavGroup[] = [
+  {
+    label: 'Routing',
+    items: [
+      { href: '/features/routing', title: 'Routing', blurb: 'A static route plus a dynamic [id] segment that reads params. The file-based router in miniature.' },
+      { href: '/features/boundaries', title: 'Boundaries', blurb: 'The control-flow throws (forbidden / unauthorized / notFound) and the nearest boundary file that catches each.' },
+      { href: '/features/metadata', title: 'Metadata', blurb: 'Static metadata plus generateMetadata(ctx), which reads the request to compute the title and Open Graph tags.' },
+    ],
+  },
+  {
+    label: 'Components',
+    items: [
+      { href: '/features/components', title: 'Components', blurb: 'The WebComponent factory, reactive props, instance signals, and slot projection in light DOM.' },
+      { href: '/features/directives', title: 'Directives', blurb: 'The lit-html directive set: repeat for keyed lists, watch(signal) for a fine-grained node swap.' },
+      { href: '/features/async-render', title: 'Async render', blurb: 'A component that awaits server data in async render(), so the resolved value is in the first paint.' },
+    ],
+  },
+  {
+    label: 'Data & actions',
+    items: [
+      { href: '/features/server-actions', title: 'Server actions', blurb: 'A use-server RPC action next to a server-only .server.ts utility, and why the boundary matters.' },
+      { href: '/features/route-handler', title: 'Route handlers', blurb: 'A server-only route.ts HTTP endpoint returning JSON, the WebJs equivalent of a Next route handler.' },
+      { href: '/features/forms', title: 'Forms', blurb: 'A no-JS progressive-enhancement form posting to the page action, with server-side validation errors.' },
+      { href: '/features/optimistic-ui', title: 'Optimistic UI', blurb: 'The imperative optimistic(signal, value, action) flip: instant update, automatic rollback on failure.' },
+    ],
+  },
+  {
+    label: 'Client & streaming',
+    items: [
+      { 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/view-transitions', title: 'View transitions', blurb: 'The opt-in view-transition meta cross-fades a soft navigation, with a data-webjs-permanent element persisted across the swap.' },
+      { href: '/features/streaming', title: 'Streaming actions', blurb: 'A use-server action that returns an async generator, streamed to the call site token by token with for await.' },
+      { href: '/features/stream', title: 'Stream updates', blurb: 'The <webjs-stream> element: renderStream() applies surgical append / replace / remove DOM updates by target id, no region redraw.' },
+      { href: '/features/suspense', title: 'Suspense boundary', blurb: 'The <webjs-suspense> element: a first-paint fallback for a SLOW component, with the resolved content streamed in.' },
+      { 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.' },
+    ],
+  },
+  {
+    label: 'Real-time',
+    items: [
+      { 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.' },
+    ],
+  },
+  {
+    label: 'Auth & sessions',
+    items: [
+      { href: '/features/auth', title: 'Auth', blurb: 'Password login on createAuth, a signed session cookie, and a real protected route that redirects anonymous visitors to login.' },
+      { href: '/features/sessions', title: 'Sessions', blurb: 'A signed-cookie session applied by a segment middleware, read and written per visitor with getSession() in a route.' },
+    ],
+  },
+  {
+    label: 'Built-ins',
+    items: [
+      { 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/rate-limit', title: 'Rate limiting', blurb: 'The rateLimit() middleware scoped to one endpoint, returning a 429 with Retry-After past the window.' },
+      { href: '/features/file-storage', title: 'File storage', blurb: 'A no-JS multipart upload streamed into the FileStore, then served back through a streaming route.' },
+      { 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).' },
+    ],
+  },
+];
+
+/** The whole example apps (composed features), shown after the single-feature demos. */
+export const EXAMPLES: NavItem[] = [
+  { href: '/examples/todo', title: 'Optimistic todo', blurb: 'A whole app composing several features: the declarative optimistic() list API, progressive-enhancement forms, accessible labels, the modules split, and SQLite.' },
+];
+
+/** Flattened single-feature list (for the home card grid). */
+export const FEATURES: NavItem[] = FEATURE_GROUPS.flatMap((g) => g.items);

package/templates/gallery/modules/optimistic-ui/components/like-button.ts

@@ -9,6 +9,8 @@
 // see the declarative optimistic(host, { source, update }) + .add() form in the
 // /examples/todo app.
 import { WebComponent, signal, optimistic, html } from '@webjsdev/core';
+import { cn } from '#lib/utils/cn.ts';
+import { buttonClass } from '#components/ui/button.ts';
 import { likePost } from '../actions/like-post.server.ts';
 
 export class LikeButton extends WebComponent {
@@ -23,9 +25,25 @@ export class LikeButton extends WebComponent {
 
   render() {
     const liked = this.liked.get();
+    // Build ON the design system, do not re-implement it. The like toggle IS the
+    // button variants: unliked reads as `secondary` (card surface), liked as
+    // `default` (primary fill). So compose buttonClass() for the base + colors +
+    // focus ring + cursor, then override only the genuinely bespoke bits with cn()
+    // (which tailwind-merges): a pill radius over the helper's rounded-xl, and a
+    // border on the liked state. The border is GEOMETRY, not decoration: the
+    // `secondary` variant carries a 1px border and `default` carries none, so under
+    // box-sizing border-box an auto-width inline-flex button would change its outer
+    // size by ~1px each toggle (a small label jitter). Re-adding `border
+    // border-primary` keeps a 1px border in both states so the pill stays put. On
+    // the primary fill that border color matches the fill, so it reads as invisible,
+    // doing only the no-jitter job. Only the heart SVG stays fully custom.
     return html`
       <button @click=${() => this.toggle()} aria-pressed=${liked ? 'true' : 'false'}
-        class="inline-flex items-center gap-2 px-4 py-2 rounded-full font-semibold text-sm border cursor-pointer transition-all active:scale-[0.97] ${liked ? 'bg-primary text-primary-foreground border-primary' : 'bg-card text-foreground border-border hover:border-border-strong'}">
+        class=${cn(
+          buttonClass({ variant: liked ? 'default' : 'secondary' }),
+          'rounded-full',
+          liked && 'border border-primary',
+        )}>
         <svg viewBox="0 0 24 24" class="w-4 h-4 ${liked ? 'fill-current stroke-none' : 'fill-none stroke-current'}" style="stroke-width:2;stroke-linecap:round;stroke-linejoin:round"><path d="M20.8 4.6a5.5 5.5 0 0 0-7.8 0L12 5.7l-1-1.1a5.5 5.5 0 0 0-7.8 7.8l1.1 1L12 21l7.7-7.6 1.1-1a5.5 5.5 0 0 0 0-7.8Z"/></svg>
         ${liked ? 'Liked' : 'Like'}
       </button>

package/templates/gallery/modules/rate-limit/components/rate-probe.ts

@@ -5,6 +5,7 @@
 // import and call instead). The button is the interactivity signal, so this
 // component ships and hydrates.
 import { WebComponent, signal, html } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
 
 interface Probe { n: number; status: number; remaining: string }
 
@@ -32,7 +33,7 @@ export class RateProbe extends WebComponent {
     return html`
       <div class="grid gap-4 max-w-[420px]">
         <button @click=${() => this.ping()}
-          class="w-fit px-3.5 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]">Ping the endpoint</button>
+          class="${buttonClass({ size: 'sm' })} w-fit">Ping the endpoint</button>
         <ul class="grid gap-1.5 list-none m-0 p-0">
           ${this.log.get().map((p) => html`
             <li class="flex items-center justify-between px-3 py-2 rounded-xl bg-card border border-border text-sm">

package/templates/gallery/modules/route-handler/components/rich-data.ts

@@ -6,6 +6,7 @@
 // (it runs in the browser), so it lives in a component; with JS off this button
 // is inert and the page still reads.
 import { WebComponent, signal, html, richFetch } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
 
 interface RichPayload { at: Date; ip: string; requestId: string; cookieCount: number }
 
@@ -22,7 +23,7 @@ export class RichData extends WebComponent {
     return html`
       <div class="flex items-center gap-3 text-[15px]">
         <button @click=${() => this.load()}
-          class="px-3.5 py-1.5 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]">richFetch() the route</button>
+          class=${buttonClass({ size: 'sm' })}>richFetch() the route</button>
         <span class="text-muted-foreground">${this.line.get()}</span>
       </div>
     `;

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

@@ -13,7 +13,7 @@ import { requireAuth, type AuthUser } from '../middleware/require-auth.server.ts
 // (the action never runs) or stashes the caller on the request context.
 export const middleware = [requireAuth];
 
-export async function greet(input: { name: string; signedOut?: boolean }): Promise<ActionResult<{ message: string }>> {
+export async function greet(input: { name: string }): 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
@@ -33,7 +33,7 @@ export async function greet(input: { name: string; signedOut?: boolean }): Promi
   // 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());
+    const message = await lookupGreeting(name, caller.name || caller.email || 'a signed-in user', actionSignal());
     return { success: true, data: { message } };
   } catch (e) {
     if (actionSignal().aborted) return { success: false, error: 'Request cancelled.', status: 499 };

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

@@ -1,15 +1,24 @@
 // Example node test for the documented test helpers (from @webjsdev/server).
 // Run it with node --test (or webjs test after moving it under test/). The
 // handle() harness drives the FULL request pipeline: createRequestHandler({
-// appDir }) builds it, and rawActionRequest() fires a 'use server' action
-// through it (CSRF + the rich serializer included), returning the raw Response.
+// appDir }) builds it, and rawActionRequest() / invokeActionForTest() fire a
+// 'use server' action through it (CSRF + the rich serializer included).
 // buildRouteTable(appDir) parses the file router; matchPage / matchApi resolve a
 // URL against it, params included. See the testing docs.
+//
+// greet is gated by the requireAuth middleware, which reads the REAL signed
+// session off the request (the auth gallery card). So an unauthenticated call is
+// genuinely denied (401), and the success path needs a real session cookie
+// (obtained via a signup + loginAndGetCookies, skipped until the db is migrated).
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { createRequestHandler, buildRouteTable, matchPage, matchApi, rawActionRequest, invokeActionForTest } from '@webjsdev/server';
+import { createRequestHandler, buildRouteTable, matchPage, matchApi, invokeActionForTest } from '@webjsdev/server';
+import { testRequest, loginAndGetCookies } from '@webjsdev/server/testing';
 
 const appDir = process.cwd();
+process.env.AUTH_SECRET ||= 'test-secret-at-least-32-characters-long!!';
+
+const GREET = 'modules/server-actions/actions/greet.server.ts';
 
 test('buildRouteTable + matchPage resolve a dynamic route with its params', async () => {
   const table = await buildRouteTable(appDir);
@@ -24,47 +33,41 @@ test('matchApi resolves the route-handler endpoint', async () => {
   assert.ok(m, 'the route.ts endpoint matches');
 });
 
-test('rawActionRequest fires the greet action through the pipeline', async () => {
+test('an unauthenticated greet is denied by requireAuth before greet runs', async () => {
   const app = await createRequestHandler({ appDir, dev: true });
   if (app.warmup) await app.warmup();
-  const res = await rawActionRequest(
-    app,
-    'modules/server-actions/actions/greet.server.ts',
-    'greet',
-    [{ name: 'Ada' }],
-  );
-  assert.equal(res.status, 200);
+  // No session cookie -> requireAuth short-circuits with a 401 failure envelope
+  // (it reads only the cookie, so this is real without a migrated db).
+  const r = (await invokeActionForTest(
+    app, GREET, 'greet', [{ name: 'Bob' }], { throwOnError: false },
+  )) as { success: boolean; error?: string; status?: number };
+  assert.equal(r.success, false);
+  assert.equal(r.status, 401);
 });
 
-test('the middleware sets the caller on the context and greet reads it via actionContext()', async () => {
+test('an authenticated greet reads the caller off the session via actionContext()', async (t) => {
   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.
+
+  // Real signup through the auth card's page action, then a real login to capture
+  // the signed session cookie. Both hit the users table, so skip until the db is
+  // migrated (run db:generate + db:migrate) rather than fail misleadingly.
+  const email = `greet+${Date.now()}@example.com`;
+  const password = 'password123';
+  const signupRes = await testRequest(app.handle, '/features/auth/signup', {
+    method: 'POST',
+    headers: { 'content-type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({ name: 'Ada', email, password }).toString(),
+  });
+  if (signupRes.status !== 302) { t.skip('app deps/db not ready; run db:generate + db:migrate'); return; }
+  const { cookies } = await loginAndGetCookies(app.handle, { email, password });
+
+  // With the session cookie the middleware sets the caller, and greet reads 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 };
+    app, GREET, 'greet', [{ name: 'Bob' }], { extraCookies: cookies },
+  )) as { success: boolean; data?: { message: string } };
   assert.equal(r.success, true);
-  // The message carries BOTH the input (Bob) and the middleware-set caller (Ada).
+  // The message carries BOTH the input (Bob) and the session 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

@@ -1,18 +1,21 @@
 // Calls the 'use server' action via a normal import (the RPC stub). Never
 // hand-write fetch(); importing the action IS the API.
 import { WebComponent, signal, html } from '@webjsdev/core';
+import { cardClass } from '#components/ui/card.ts';
+import { buttonClass } from '#components/ui/button.ts';
+import { bareInputClass } from '#components/ui/input.ts';
 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, signedOut: this.signedOut.get() });
+    // The action's requireAuth middleware reads the real session off the request.
+    // Signed out, this comes back as a 401 failure envelope ("Sign in to
+    // continue."); sign in at /features/auth/login and the greeting succeeds.
+    const r = await greet({ name });
     // 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'));
@@ -21,16 +24,13 @@ export class Greeter extends WebComponent {
     return html`
       <div class="grid gap-3 max-w-[420px]">
         <form @submit=${(e: SubmitEvent) => this.run(e)}
-          class="flex items-center gap-2 p-2 pl-4 rounded-2xl bg-card border border-border">
+          class="${cardClass()} flex items-center gap-2 p-2 pl-4">
           <input name="name" placeholder="your name" autocomplete="off"
-            class="flex-1 min-w-0 bg-transparent border-0 outline-none text-foreground text-[15px] placeholder:text-muted-foreground py-1.5" />
+            class=${bareInputClass()} />
           <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>
+            class="${buttonClass()} shrink-0">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>
+        <p class="m-0 text-sm text-muted-foreground">The action is gated by requireAuth. <a class="text-primary underline underline-offset-2" href="/features/auth/login">Sign in</a> to greet; signed out returns a real 401.</p>
         ${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

@@ -7,10 +7,16 @@
 // .server.ts with NO 'use server'): the action imports it server-side; it never
 // ships to the browser.
 import type { ActionResult } from '@webjsdev/server';
+// This demo depends on the auth gallery card (modules/auth): getCurrentUser
+// reads the real signed session. If you prune the auth card, prune this
+// server-actions card too (or swap this for your own session read); gallery:clear
+// removes both together.
+import { getCurrentUser } from '#modules/auth/auth.server.ts';
 
 export interface AuthUser {
   id: string;
-  name: string;
+  name?: string | null;
+  email?: string;
 }
 
 // The context object the framework passes each middleware. `context` is the
@@ -24,17 +30,16 @@ interface ActionMiddlewareCtx {
 }
 
 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' };
+  // A REAL guard reads the signed session off the request, because auth belongs
+  // to the request, not the payload. The RPC POST is same-origin, so the auth
+  // cookie rides along and getCurrentUser(ctx.request) reads it (this uses the
+  // auth gallery card's createAuth config; sign in at /features/auth/login).
+  const user = (await getCurrentUser(ctx.request)) as AuthUser | null;
 
   // 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).
+  // status inside the envelope, and a denied call is served no-store (never
+  // cached). An anonymous caller is genuinely denied here.
   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

package/templates/gallery/modules/stream/components/stream-demo.ts

@@ -0,0 +1,81 @@
+// <webjs-stream> is the element-level DOM-update grammar (#248): a self-applying
+// element that clones its <template> and runs one native DOM method against a
+// target (by id), then removes itself. `renderStream(htmlString)` from
+// @webjsdev/core applies such a payload on the client. It is WebJs's take on
+// Turbo Streams: surgical append / prepend / replace / update / remove, without
+// redrawing a whole region.
+//
+// This demo drives it from the client with buttons. The list below is seeded
+// ONCE in render(); every button mutates the LIVE DOM via renderStream() and the
+// component never re-renders (the row counter is a plain field, deliberately not
+// a signal, so reading it never re-runs render() and wipes the surgical updates).
+// That is the whole point: out-of-band updates that a signal re-render or a frame
+// region-swap would clobber.
+import { WebComponent, html, renderStream } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
+
+// Build a <webjs-stream> payload string. It is a plain string (NOT an html``
+// template), so interpolating the row markup here is fine. `remove` needs no
+// <template>; every other action wraps its content in one.
+function streamPayload(action: string, target: string, inner = '') {
+  const body = action === 'remove' ? '' : `<template>${inner}</template>`;
+  return `<webjs-stream action="${action}" target="${target}">${body}</webjs-stream>`;
+}
+
+const rowCls = 'flex items-center gap-2 px-3 py-2 rounded-xl bg-card border border-border text-[15px] text-foreground';
+const row = (id: string, label: string) => `<li id="${id}" class="${rowCls}">${label}</li>`;
+
+export class StreamDemo extends WebComponent {
+  // A plain instance field, NOT a signal: incremented to mint unique row ids.
+  // It is never read inside render(), so appending a row does not re-render the
+  // component and blow away the streamed-in rows.
+  #n = 2;
+
+  // NOTE the method names: NOT append() / prepend(). Those are native
+  // ParentNode methods, and WebJs instruments them on every light-DOM host for
+  // the slot API (#1021), so a component method of the same name is shadowed and
+  // never runs. Name your handlers something else (see muscle-memory-gotchas).
+  appendRow() {
+    this.#n++;
+    renderStream(streamPayload('append', 'stream-list', row(`row-${this.#n}`, `Row ${this.#n} (appended)`)));
+  }
+  prependRow() {
+    this.#n++;
+    renderStream(streamPayload('prepend', 'stream-list', row(`row-${this.#n}`, `Row ${this.#n} (prepended)`)));
+  }
+  replaceFirst() {
+    // `replace` swaps the target element itself. The replacement keeps id row-1,
+    // so the button stays repeatable.
+    renderStream(streamPayload('replace', 'row-1', row('row-1', 'Row 1 (replaced)')));
+  }
+  removeSecond() {
+    // `remove` deletes the target and needs no <template>.
+    renderStream(streamPayload('remove', 'row-2'));
+  }
+  reset() {
+    // `update` replaces the target's children, restoring the seed list.
+    renderStream(streamPayload('update', 'stream-list', row('row-1', 'Row 1') + row('row-2', 'Row 2')));
+  }
+
+  render() {
+    const btn = buttonClass({ variant: 'secondary', size: 'xs' });
+    return html`
+      <div class="grid gap-4 max-w-[460px]">
+        <div class="flex flex-wrap gap-2">
+          <button class=${btn} @click=${() => this.appendRow()}>Append</button>
+          <button class=${btn} @click=${() => this.prependRow()}>Prepend</button>
+          <button class=${btn} @click=${() => this.replaceFirst()}>Replace Row 1</button>
+          <button class=${btn} @click=${() => this.removeSecond()}>Remove Row 2</button>
+          <button class=${btn} @click=${() => this.reset()}>Reset</button>
+        </div>
+        <!-- The target list. renderStream() mutates it by id; this markup renders
+             once and is never re-rendered by the component. -->
+        <ul id="stream-list" class="grid gap-2 m-0 p-0 list-none">
+          <li id="row-1" class="flex items-center gap-2 px-3 py-2 rounded-xl bg-card border border-border text-[15px] text-foreground">Row 1</li>
+          <li id="row-2" class="flex items-center gap-2 px-3 py-2 rounded-xl bg-card border border-border text-[15px] text-foreground">Row 2</li>
+        </ul>
+      </div>
+    `;
+  }
+}
+StreamDemo.register('stream-demo');

package/templates/gallery/modules/streaming/actions/stream-tokens.server.ts

@@ -0,0 +1,17 @@
+'use server';
+// A STREAMING server action (#489). Detection is purely on the RETURN VALUE, no
+// config export: an action that returns a ReadableStream / async iterable /
+// async generator streams its chunks over the single RPC response instead of
+// buffering. Each `yield` is rich-serialized and flushed as it is produced, so
+// the call site sees tokens arrive live. Back-pressure is respected and the
+// generator is cancelled if the client disconnects. A streamed result is never
+// cached / ETagged / seeded. One function per file, like every action.
+export async function* streamTokens(prompt: string): AsyncGenerator<string> {
+  const words = `Streaming ${prompt} one token at a time, straight from the server.`.split(' ');
+  for (const word of words) {
+    // A deliberate per-token delay so the streaming is visible; a real action
+    // would yield as its upstream (an LLM, a DB cursor, a log tail) produces.
+    await new Promise((r) => setTimeout(r, 140));
+    yield word + ' ';
+  }
+}

package/templates/gallery/modules/streaming/components/token-stream.ts

@@ -0,0 +1,53 @@
+// Consumes a streaming action at the call site with `for await`. The import of
+// a `'use server'` action is rewritten to an RPC stub, so `await streamTokens()`
+// resolves to an async iterable whose chunks arrive as the server yields them.
+// We append each chunk to an instance signal, so the text builds up live as it
+// streams (the built-in SignalWatcher re-renders on each `.set`). With JS off
+// the button is inert and the empty output renders (streaming is inherently a
+// JS behaviour), so nothing here breaks the no-JS first paint.
+import { WebComponent, signal, html } from '@webjsdev/core';
+import { cardClass } from '#components/ui/card.ts';
+import { buttonClass } from '#components/ui/button.ts';
+import { streamTokens } from '../actions/stream-tokens.server.ts';
+
+export class TokenStream extends WebComponent {
+  // Plain instance signals (not reactive props), so a class field is fine here.
+  private output = signal('');
+  private busy = signal(false);
+
+  private async run() {
+    this.output.set('');
+    this.busy.set(true);
+    try {
+      // `await streamTokens(...)` gives the async iterable; `for await` pulls
+      // each token as it arrives instead of waiting for the whole response.
+      for await (const chunk of await streamTokens('webjs')) {
+        this.output.set(this.output.get() + chunk);
+      }
+    } finally {
+      this.busy.set(false);
+    }
+  }
+
+  render() {
+    const busy = this.busy.get();
+    const output = this.output.get();
+    // Only reserve the output area once streaming starts (or has produced text),
+    // so an idle demo has no empty box below the button.
+    return html`
+      <div class="${cardClass()} p-5">
+        <button
+          @click=${() => this.run()}
+          ?disabled=${busy}
+          class=${buttonClass()}
+        >
+          ${busy ? 'streaming…' : 'Stream tokens'}
+        </button>
+        ${busy || output
+          ? html`<pre class="mt-4 whitespace-pre-wrap font-mono text-sm text-foreground">${output}</pre>`
+          : ''}
+      </div>
+    `;
+  }
+}
+TokenStream.register('token-stream');

package/templates/gallery/modules/suspense/components/slow-fact.ts

@@ -0,0 +1,20 @@
+// A bare async-render component whose server data is deliberately SLOW. On its
+// own, async render() BLOCKS the SSR first byte (the resolved value lands in the
+// first paint with no fallback, which is what the async-render demo shows). That
+// is the right default for fast data. Here the data is slow, so the page wraps
+// it in a <webjs-suspense> boundary that flushes its fallback on the first byte
+// and STREAMS this content in when the await settles (progressively on soft
+// navigation too). Same component either way; the boundary is what changes the
+// SSR behaviour from block to stream.
+import { WebComponent, html } from '@webjsdev/core';
+import { cardClass } from '#components/ui/card.ts';
+
+export class SlowFact extends WebComponent {
+  async render() {
+    await new Promise((r) => setTimeout(r, 900));
+    return html`<p class="${cardClass()} p-5 text-foreground">
+      The answer, after a slow lookup, is <strong>42</strong>.
+    </p>`;
+  }
+}
+SlowFact.register('slow-fact');