@webjsdev/cli 0.10.43 → 0.10.45

package/templates/gallery/app/features/auth/dashboard/page.ts

@@ -0,0 +1,18 @@
+import { html } from '@webjsdev/core';
+import { currentUser } from '#modules/auth/queries/current-user.server.ts';
+
+export const metadata = { title: 'Dashboard' };
+
+export default async function Dashboard() {
+  const user = await currentUser();
+  return html`
+    <div class="flex items-center justify-between mb-6">
+      <h1 class="text-2xl font-semibold">Dashboard</h1>
+      <span class="text-xs font-medium rounded-full bg-primary/15 text-primary px-2.5 py-1">Signed in</span>
+    </div>
+    <div class="p-6 rounded-2xl bg-card border border-border">
+      <h2 class="text-lg font-semibold text-foreground m-0 mb-1">Welcome, ${user?.name || user?.email}!</h2>
+      <p class="text-sm text-muted-foreground m-0">This route is gated by middleware.ts. Promote it into your product, or drop the whole auth card with gallery:clear.</p>
+    </div>
+  `;
+}

package/templates/gallery/app/features/auth/dashboard/settings/page.ts

@@ -0,0 +1,21 @@
+import { html } from '@webjsdev/core';
+import { currentUser } from '#modules/auth/queries/current-user.server.ts';
+
+export const metadata = { title: 'Settings' };
+
+export default async function Settings() {
+  const user = await currentUser();
+  return html`
+    <h1 class="text-2xl font-semibold mb-6">Settings</h1>
+    <div class="p-6 rounded-2xl bg-card border border-border">
+      <h2 class="text-lg font-semibold text-foreground m-0 mb-1">Account</h2>
+      <p class="text-sm text-muted-foreground m-0 mb-4">Your basic profile information.</p>
+      <dl class="grid grid-cols-[max-content_1fr] gap-x-6 gap-y-2 text-sm">
+        <dt class="text-muted-foreground">Email</dt>
+        <dd>${user?.email}</dd>
+        <dt class="text-muted-foreground">Name</dt>
+        <dd>${user?.name || 'Not set'}</dd>
+      </dl>
+    </div>
+  `;
+}

package/templates/gallery/app/features/auth/login/page.ts

@@ -0,0 +1,40 @@
+import { html } from '@webjsdev/core';
+
+export const metadata = { title: 'Log in' };
+
+const inputCls = 'w-full bg-background border border-border rounded-xl px-3 py-2 text-[15px] text-foreground outline-none transition-colors focus:border-primary placeholder:text-muted-foreground';
+
+// A failed sign-in 302s back here with ?error=... (createAuth is configured with
+// pages.error: '/features/auth/login' in modules/auth/auth.server.ts). Map the
+// code to a plain message so a bad password gets visible feedback instead of a
+// silent bounce.
+function errorMessage(code: string | undefined): string | null {
+  if (!code) return null;
+  if (code === 'CredentialsSignin') return 'Invalid email or password.';
+  return 'Could not sign you in. Please try again.';
+}
+
+export default function LoginPage({ searchParams }: { searchParams: { error?: string } }) {
+  const error = errorMessage(searchParams.error);
+  return html`
+    <div class="max-w-[420px] mx-auto">
+      <h1 class="text-h2 font-bold mb-2">Sign in</h1>
+      <p class="text-muted-foreground mb-5">Welcome back: log in to continue.</p>
+      ${error ? html`<p role="alert" class="mb-4 text-sm text-destructive">${error}</p>` : ''}
+      <form method="POST" action="/api/auth/signin/credentials" class="grid gap-4 p-5 rounded-2xl bg-card border border-border">
+        <!-- createAuth reads redirectTo from the posted form and 302s there after a successful signin. -->
+        <input type="hidden" name="redirectTo" value="/features/auth/dashboard">
+        <div class="grid gap-1.5">
+          <label for="email" class="text-[13px] font-medium text-muted-foreground">Email</label>
+          <input id="email" name="email" type="email" required class=${inputCls} placeholder="ada@example.com" />
+        </div>
+        <div class="grid gap-1.5">
+          <label for="password" class="text-[13px] font-medium text-muted-foreground">Password</label>
+          <input id="password" name="password" type="password" required class=${inputCls} />
+        </div>
+        <button type="submit" class="justify-self-start 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]">Sign in</button>
+      </form>
+      <p class="text-sm text-muted-foreground mt-4">Don't have an account? <a href="/features/auth/signup" class="text-primary">Sign up</a></p>
+    </div>
+  `;
+}

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

@@ -0,0 +1,33 @@
+// Auth: password login/signup on top of createAuth, a signed session cookie, and
+// a genuinely protected route. This card wires a REAL auth baseline (a users
+// table with a passwordHash, createAuth in modules/auth/auth.server.ts, and the
+// /features/auth/dashboard subtree gated by a middleware.ts), so a fresh app can
+// promote it into a product. gallery:clear removes the whole surface (this card,
+// modules/auth, app/api/auth, the passwordHash column) back to the minimal base.
+//
+// This index page is public and reads the current session with currentUser() so
+// it can show who is signed in. The read is a 'use server' action, so the same
+// line is the real query during SSR and a safe RPC stub on the client.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+import { currentUser } from '#modules/auth/queries/current-user.server.ts';
+
+export const metadata: Metadata = { title: 'Auth (login + protected route) | features' };
+
+export default async function AuthExample() {
+  const user = await currentUser();
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Auth</h1>
+    <p class="text-muted-foreground mb-4">Password login on <code>createAuth</code>, a signed session cookie, and a protected <code>/features/auth/dashboard</code> that redirects anonymous visitors to login.</p>
+
+    ${user
+      ? html`
+        <p class="mb-4">Signed in as <strong>${user.name || user.email}</strong>.</p>
+        <p><a class="text-primary" href="/features/auth/dashboard">Open the protected dashboard</a></p>`
+      : html`
+        <p class="mb-4">You are signed out. <a class="text-primary" href="/features/auth/dashboard">Visiting the dashboard</a> bounces you to login.</p>
+        <p class="flex gap-4"><a class="text-primary" href="/features/auth/login">Log in</a><a class="text-primary" href="/features/auth/signup">Create an account</a></p>`}
+
+    <p class="text-muted-foreground text-sm mt-6">The gate is <code class="font-mono">app/features/auth/dashboard/middleware.ts</code> calling <code class="font-mono">auth(req)</code>; the login form posts to the <code class="font-mono">app/api/auth/[...path]</code> handler; OAuth (GitHub / Google) activates once you set the matching env vars.</p>
+  `;
+}

package/templates/gallery/app/features/auth/signup/page.ts

@@ -0,0 +1,58 @@
+import { html } from '@webjsdev/core';
+import { signup } from '#modules/auth/actions/signup.server.ts';
+
+export const metadata = { title: 'Sign up' };
+
+const inputCls = 'w-full bg-background border border-border rounded-xl px-3 py-2 text-[15px] text-foreground outline-none transition-colors focus:border-primary placeholder:text-muted-foreground';
+
+// Page server action: handles the POST from the form below. With JS disabled this
+// is a plain <form> round-trip; with JS the client router swaps the 422 re-render
+// (errors) or follows the 302 (success) in place. A validation failure returns
+// fieldErrors + values so the page re-renders with messages and the user's typed
+// input preserved.
+export async function action({ formData }: { formData: FormData }) {
+  const name = String(formData.get('name') || '').trim();
+  const email = String(formData.get('email') || '').trim();
+  const password = String(formData.get('password') || '');
+  const values = { name, email };
+  const fieldErrors: Record<string, string> = {};
+  if (!name) fieldErrors.name = 'Name is required';
+  if (!email.includes('@')) fieldErrors.email = 'Enter a valid email';
+  if (password.length < 8) fieldErrors.password = 'At least 8 characters';
+  if (Object.keys(fieldErrors).length) return { success: false, fieldErrors, values, status: 422 };
+  const result = await signup({ name, email, password });
+  // On success signup returns signIn's 302 Response (auto-login -> dashboard); a
+  // page action may return a Response, so pass it straight through.
+  if (result instanceof Response) return result;
+  return { success: false, fieldErrors: { email: result.error }, values, status: result.status };
+}
+
+export default function SignupPage({ actionData }: { actionData?: { fieldErrors?: Record<string, string>; values?: Record<string, string> } }) {
+  const errors = actionData?.fieldErrors || {};
+  const values = actionData?.values || {};
+  return html`
+    <div class="max-w-[420px] mx-auto">
+      <h1 class="text-h2 font-bold mb-2">Create an account</h1>
+      <p class="text-muted-foreground mb-5">Get started with your new workspace.</p>
+      <form method="POST" class="grid gap-4 p-5 rounded-2xl bg-card border border-border">
+        <div class="grid gap-1.5">
+          <label for="name" class="text-[13px] font-medium text-muted-foreground">Name</label>
+          <input id="name" name="name" type="text" value=${values.name || ''} required class=${inputCls} placeholder="Ada Lovelace" />
+          ${errors.name ? html`<p class="m-0 text-[12.5px] text-destructive">${errors.name}</p>` : ''}
+        </div>
+        <div class="grid gap-1.5">
+          <label for="email" class="text-[13px] font-medium text-muted-foreground">Email</label>
+          <input id="email" name="email" type="email" value=${values.email || ''} required class=${inputCls} placeholder="ada@example.com" />
+          ${errors.email ? html`<p class="m-0 text-[12.5px] text-destructive">${errors.email}</p>` : ''}
+        </div>
+        <div class="grid gap-1.5">
+          <label for="password" class="text-[13px] font-medium text-muted-foreground">Password</label>
+          <input id="password" name="password" type="password" minlength="8" required class=${inputCls} />
+          ${errors.password ? html`<p class="m-0 text-[12.5px] text-destructive">${errors.password}</p>` : ''}
+        </div>
+        <button type="submit" class="justify-self-start 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]">Create account</button>
+      </form>
+      <p class="text-sm text-muted-foreground mt-4">Already have an account? <a href="/features/auth/login" class="text-primary">Log in</a></p>
+    </div>
+  `;
+}

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

@@ -0,0 +1,79 @@
+// <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. It is also NOT a layout: a layout (layout.ts) is server-rendered chrome
+// that WRAPS a route subtree via ${children} and re-renders only as part of a
+// navigation, so it answers "what structure wraps these routes". A frame answers
+// "which region updates itself in place", with no navigation at all. Use a layout
+// for shared chrome across routes; use a frame when one region (a filtered list,
+// a paginated table, a tab panel) must refresh on its own without navigating.
+// 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 neither a page nor a
+      layout can express: a layout wraps routes with shared chrome and only
+      re-renders when you navigate, while a frame updates one region in place.
+    </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/layout.ts

@@ -0,0 +1,12 @@
+import { html } from '@webjsdev/core';
+
+// Shared layout for every gallery feature demo under /features/*. It adds a slim
+// "back to the gallery" link above each demo so a card is never a dead end.
+// Nested layouts (like the auth dashboard's sub-nav) render inside ${children}.
+// A non-root layout, so it never writes the document shell (the framework does).
+export default function FeaturesLayout({ children }: { children: unknown }) {
+  return html`
+    <a href="/" class="inline-flex items-center gap-1 text-sm text-muted-foreground hover:text-foreground transition-colors no-underline mb-6">&larr; Gallery</a>
+    ${children}
+  `;
+}

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

@@ -8,6 +8,16 @@ 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 reads the
+      real signed session (from the <a class="text-primary" href="/features/auth">auth card</a>) and
+      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>
+    <p class="text-muted-foreground mb-4 text-sm">Signed out, the greeter returns a real 401. <a class="text-primary" href="/features/auth/login">Sign in</a> first to see it succeed. (This card depends on the auth card; prune both together.)</p>
     <server-greeter></server-greeter>
   `;
 }

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

@@ -0,0 +1,45 @@
+// Stream updates: the <webjs-stream> element + renderStream() (#248). It is the
+// element-level DOM-update grammar (Turbo Streams parity): a self-applying
+// element that clones its <template> and runs ONE native DOM method (append /
+// prepend / before / after / replace / update / remove) against a target id, then
+// removes itself. See modules/stream/components/stream-demo.ts.
+//
+// How it differs from the neighbours:
+//   - The client router swaps a whole page (a navigation to a different URL).
+//   - A <webjs-frame> refreshes one URL-addressable region in place.
+//   - <webjs-stream> is finer still: it mutates individual ELEMENTS by id (add a
+//     row, remove a row, replace one node), with no region redraw and no
+//     component re-render. Reach for it when a signal re-render or a frame swap
+//     would be too coarse (a chat append, an optimistic row removal, a toast).
+//
+// Three delivery paths share this one applier: the client renderStream() below;
+// a content-negotiated <form> response the router applies surgically (JS off
+// degrades to a normal round-trip); and a live channel (a broadcast() / connectWS
+// message applied with renderStream() from a WS handler, see the WebSockets card).
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+import '#modules/stream/components/stream-demo.ts';
+
+export const metadata: Metadata = { title: 'Stream updates (webjs-stream) | features' };
+
+export default function StreamExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Stream updates</h1>
+    <p class="text-muted-foreground mb-4">
+      <code class="font-mono">renderStream()</code> applies a
+      <code class="font-mono">&lt;webjs-stream action="..." target="..."&gt;</code>
+      payload: a surgical, element-level DOM update by id. Each button below mutates
+      the live list in place, and the component never re-renders (contrast a frame,
+      which swaps a whole region, and the client router, which swaps a whole page).
+    </p>
+    <stream-demo></stream-demo>
+    <p class="text-muted-foreground text-sm mt-6">
+      The same grammar arrives over HTTP (a content-negotiated
+      <code class="font-mono">&lt;form&gt;</code> response the router applies
+      surgically, degrading to a full round-trip with JS off) and over a live
+      channel (a <code class="font-mono">broadcast()</code> message applied with
+      <code class="font-mono">renderStream()</code> from a
+      <code class="font-mono">connectWS</code> handler, see the WebSockets card).
+    </p>
+  `;
+}

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

@@ -0,0 +1,31 @@
+// Streaming server-action results (#489). A `'use server'` action that returns
+// an async generator streams its chunks over the one RPC response; the call
+// site consumes them with `for await`, rendering each as it arrives. This is
+// the token-by-token shape (LLM output, a log tail, a DB cursor) over the
+// normal action call site, back-pressured and cancelled on client disconnect.
+// Contrast with a route.ts that hands back a raw HTTP ReadableStream: this rides
+// the typed action mechanism, no hand-written fetch.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+import '#modules/streaming/components/token-stream.ts';
+
+export const metadata: Metadata = { title: 'Streaming actions (for await) | features' };
+
+export default function StreamingExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Streaming actions</h1>
+    <p class="text-muted-foreground mb-4">
+      A <code class="font-mono">'use server'</code> action that returns an
+      <code class="font-mono">async function*</code> streams each
+      <code class="font-mono">yield</code> over the single RPC response. The call
+      site consumes it with <code class="font-mono">for await (const chunk of await streamTokens())</code>,
+      so tokens render as they arrive instead of waiting for the whole result.
+    </p>
+    <p class="text-muted-foreground mb-6 text-sm">
+      Detection is on the return value (no config export), and a streamed result
+      is never cached, ETagged, or seeded. The source generator is cancelled if
+      the client navigates away mid-stream.
+    </p>
+    <token-stream></token-stream>
+  `;
+}

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

@@ -0,0 +1,34 @@
+// Component-level <webjs-suspense> streaming (#471). Page-level Suspense (the
+// async-render demo) streams a region of the PAGE; <webjs-suspense> is the
+// element that wraps one or more COMPONENTS, flushes its .fallback on the first
+// byte, and streams the resolved content in. It is the only way to show a
+// first-paint fallback for a SLOW component, and the deliberate choice when
+// blocking the first byte on that component's data would hurt. Plain async
+// render() blocks SSR so its data is in the first paint with NO fallback (right
+// for fast data); reach for <webjs-suspense> when the data is genuinely slow.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+import '#modules/suspense/components/slow-fact.ts';
+
+export const metadata: Metadata = { title: 'Suspense boundary (<webjs-suspense>) | features' };
+
+export default function SuspenseExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Suspense boundary</h1>
+    <p class="text-muted-foreground mb-4">
+      The slow component below is wrapped in
+      <code class="font-mono">&lt;webjs-suspense&gt;</code>. Its fallback shows on
+      the first byte and the resolved content streams in when the slow await
+      settles. Reload to see the fallback, then the fact stream in.
+    </p>
+    <p class="text-muted-foreground mb-6 text-sm">
+      <code class="font-mono">.fallback</code> is a property hole (unquoted, per
+      invariant 4). Contrast with the
+      <a href="/features/async-render" class="text-primary no-underline font-medium">async render</a>
+      demo, where SSR blocks so the data is in the first paint with no fallback.
+    </p>
+    <webjs-suspense .fallback=${html`<p class="rounded-2xl border border-dashed border-border p-5 text-muted-foreground">loading the fact…</p>`}>
+      <slow-fact></slow-fact>
+    </webjs-suspense>
+  `;
+}

package/templates/gallery/app/features/view-transitions/page.ts

@@ -0,0 +1,41 @@
+// View Transitions: opt in with a <meta name="view-transition" content="same-origin">
+// (declared here via metadata.other, so it scopes to this page, not the whole
+// app). When present, the client router wraps its DOM swap in the native View
+// Transitions API, so a soft navigation cross-fades instead of snapping. Where
+// startViewTransition is unavailable the swap runs synchronously with no flash
+// and no throw, so it degrades cleanly. The <input> below is marked
+// data-webjs-permanent with an id, so the router carries the SAME live node
+// across the swap: type into it, navigate, and your text survives the transition.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+
+export const metadata: Metadata = {
+  title: 'View transitions (soft-nav cross-fade) | features',
+  other: { 'view-transition': 'same-origin' },
+};
+
+export default function ViewTransitionsExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">View transitions</h1>
+    <div class="rounded-2xl bg-primary/10 border border-primary/30 p-6 mb-6">
+      <p class="text-foreground m-0">Page one. Navigate to page two: with the
+        <code class="font-mono">&lt;meta name="view-transition"&gt;</code> opt-in,
+        the swap cross-fades.</p>
+    </div>
+    <label class="block mb-6">
+      <span class="text-muted-foreground text-sm">Type here, then navigate. This input is
+        <code class="font-mono">data-webjs-permanent</code>, so its value survives the swap:</span>
+      <input id="vt-note" data-webjs-permanent type="text" placeholder="type something…"
+        class="mt-2 block w-full max-w-sm rounded-xl border border-border bg-card px-4 py-2 text-foreground" />
+    </label>
+    <div class="flex gap-3 items-center">
+      <a href="/features/view-transitions/second" class="inline-flex items-center px-4 py-2 rounded-xl bg-primary text-primary-foreground font-semibold text-sm no-underline transition-all hover:bg-primary/90 active:scale-[0.97]">Go to page two</a>
+      <a href="/" class="text-muted-foreground no-underline font-medium text-sm hover:text-foreground transition-colors">Home</a>
+    </div>
+    <p class="text-muted-foreground text-sm mt-6">
+      Opt in app-wide instead by putting the meta on the root layout. Keep the
+      transition simple: toggling root attributes mid-nav can cause a one-frame
+      repaint flash on iOS WebKit.
+    </p>
+  `;
+}

package/templates/gallery/app/features/view-transitions/second/page.ts

@@ -0,0 +1,28 @@
+// The soft-navigation target. It carries the same view-transition opt-in so the
+// cross-fade wraps the swap in BOTH directions, and the same
+// data-webjs-permanent input (same id) so the router regrafts the one live node
+// across the swap: the text you typed on page one is still here.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+
+export const metadata: Metadata = {
+  title: 'View transitions: page two | features',
+  other: { 'view-transition': 'same-origin' },
+};
+
+export default function ViewTransitionsSecond() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Page two</h1>
+    <div class="rounded-2xl bg-foreground/5 border border-border p-6 mb-6">
+      <p class="text-foreground m-0">You arrived with a cross-fade, no full
+        reload. The input below is the same node from page one, regrafted across
+        the swap.</p>
+    </div>
+    <label class="block mb-6">
+      <span class="text-muted-foreground text-sm">Its value persisted across the transition:</span>
+      <input id="vt-note" data-webjs-permanent type="text" placeholder="type something…"
+        class="mt-2 block w-full max-w-sm rounded-xl border border-border bg-card px-4 py-2 text-foreground" />
+    </label>
+    <a href="/features/view-transitions" class="text-primary no-underline font-medium">&larr; Back to page one</a>
+  `;
+}

package/templates/gallery/modules/auth/actions/signup.server.ts

@@ -0,0 +1,19 @@
+'use server';
+
+import { db } from '#db/connection.server.ts';
+import { users } from '#db/schema.server.ts';
+import { hash } from '../password.server.ts';
+import { signIn } from '../auth.server.ts';
+
+// Creates the account, then signs the new user in and lands on the dashboard.
+// signIn returns a 302 Response carrying the session cookie; the signup page
+// action returns that Response as-is (a page action may return a Response).
+// signIn lives in the server-only auth module, imported here server-to-server,
+// so it never reaches the browser (the signup page only imports this action's
+// RPC stub).
+export async function signup(input: { name: string; email: string; password: string }) {
+  const exists = await db.query.users.findFirst({ where: { email: input.email }, columns: { id: true } });
+  if (exists) return { success: false as const, error: 'Email already registered', status: 409 };
+  await db.insert(users).values({ name: input.name, email: input.email, passwordHash: await hash(input.password) });
+  return signIn('credentials', { email: input.email, password: input.password }, { redirectTo: '/features/auth/dashboard' });
+}

package/templates/gallery/modules/auth/auth.server.ts

@@ -0,0 +1,53 @@
+// The auth configuration. A server-only utility (a .server.ts with NO
+// 'use server'), so it runs server-side and its browser import is a throw-at-load
+// stub. Pages and route handlers import the pieces they need server-to-server;
+// the client only ever reaches auth through a 'use server' action's RPC stub.
+//
+// createAuth returns { auth, signIn, signOut, handlers }. `handlers` mounts at
+// app/api/auth/[...path]/route.ts (createAuth hardcodes the /api/auth/signin/*
+// and /api/auth/callback/* paths, which is why that route stays at the app root
+// even though the rest of this card lives under app/features/auth/).
+import { createAuth, Credentials, GitHub, Google } from '@webjsdev/server';
+import { db } from '#db/connection.server.ts';
+import { compare } from './password.server.ts';
+
+// AUTH_SECRET signs session tokens. Set a strong value in .env for any real
+// deployment. The dev fallback keeps a fresh scaffold booting, but is NOT safe
+// for production, so we fail fast if it is missing or blank there.
+const trimmedSecret = process.env.AUTH_SECRET?.trim();
+if (process.env.NODE_ENV === 'production' && !trimmedSecret) {
+  throw new Error('AUTH_SECRET must be set in production');
+}
+const authSecret = trimmedSecret || 'dev-insecure-secret-change-me';
+
+export const { auth, signIn, signOut, handlers } = createAuth({
+  providers: [
+    Credentials({
+      async authorize(credentials: { email: string; password: string }) {
+        const user = await db.query.users.findFirst({ where: { email: credentials.email } });
+        if (!user?.passwordHash || !await compare(credentials.password, user.passwordHash)) return null;
+        return { id: String(user.id), name: user.name, email: user.email };
+      },
+    }),
+    // OAuth providers: add GitHub / Google sign-in by setting the matching env
+    // vars. Each preset (GitHub(), Google()) reads AUTH_<PROVIDER>_ID / _SECRET,
+    // so they only activate once configured and a fresh scaffold still boots with
+    // just Credentials.
+    ...(process.env.AUTH_GITHUB_ID ? [GitHub({ clientId: process.env.AUTH_GITHUB_ID, clientSecret: process.env.AUTH_GITHUB_SECRET })] : []),
+    ...(process.env.AUTH_GOOGLE_ID ? [Google({ clientId: process.env.AUTH_GOOGLE_ID, clientSecret: process.env.AUTH_GOOGLE_SECRET })] : []),
+  ],
+  secret: authSecret,
+  // A failed credentials sign-in 302s to `${pages.error}?error=CredentialsSignin`.
+  // Point it at the login page so it reads searchParams.error and shows a message,
+  // instead of the createAuth default (the home page) swallowing the error.
+  pages: { error: '/features/auth/login' },
+});
+
+// Read the signed-in user off a request. auth(req) reads the session cookie
+// (falling back to the ambient request when called with no argument), so this
+// works from a page/layout, a segment middleware, or an action middleware that
+// holds the request (the greet demo's require-auth reads it this way).
+export async function getCurrentUser(req?: Request) {
+  const session = await auth(req);
+  return session?.user ?? null;
+}

package/templates/gallery/modules/auth/password.server.ts

@@ -0,0 +1,20 @@
+// Password hashing with scrypt from node:crypto (built into Node AND Bun, no
+// dependency). A server-only utility: hashes live server-side and never reach
+// the browser. Swap in argon2/bcrypt here if you prefer; the call sites only use
+// hash() and compare().
+import { scrypt, randomBytes, timingSafeEqual } from 'node:crypto';
+import { promisify } from 'node:util';
+
+const scryptAsync = promisify(scrypt);
+
+export async function hash(password: string): Promise<string> {
+  const salt = randomBytes(16).toString('hex');
+  const buf = (await scryptAsync(password, salt, 64)) as Buffer;
+  return salt + ':' + buf.toString('hex');
+}
+
+export async function compare(password: string, stored: string): Promise<boolean> {
+  const [salt, key] = stored.split(':');
+  const buf = (await scryptAsync(password, salt, 64)) as Buffer;
+  return timingSafeEqual(buf, Buffer.from(key, 'hex'));
+}

package/templates/gallery/modules/auth/queries/current-user.server.ts

@@ -0,0 +1,12 @@
+'use server';
+
+import { getCurrentUser } from '../auth.server.ts';
+
+// This read deliberately stays POST-default (no 'method' export). A GET server
+// action (a cacheable, SSR-seeded read) is wrong for a per-session lookup: the
+// result differs per user and changes on sign-in / sign-out, so it must never be
+// browser-cached or shared. Reserve GET + cache + tags for data identical for
+// every visitor.
+export async function currentUser() {
+  return getCurrentUser();
+}

package/templates/gallery/modules/auth/types.ts

@@ -0,0 +1,9 @@
+export interface User {
+  id: number;
+  name: string | null;
+  email: string;
+}
+
+export type ActionResult<T> =
+  | { success: true; data: T }
+  | { success: false; error: string; status: number };

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;
+}