@webjsdev/cli 0.10.44 → 0.10.46

package/templates/.agents/skills/webjs/references/routing-and-pages.md

@@ -4,8 +4,8 @@
 
 - Pages, layouts, and where the HTML shell comes from
 - Dynamic (`[param]`), catch-all (`[...rest]`), and optional catch-all (`[[...rest]]`) segments, route groups, private folders
-- `route.ts` HTTP handlers and `middleware.ts`
-- `metadata` and `generateMetadata` (folded in here)
+- `route.ts` HTTP handlers and `middleware.ts`, the route-handler toolkit (`json` / `readBody` / `clientIp` / the no-arg accessors), and calling one from the client with `richFetch`
+- `metadata` and `generateMetadata` (folded in here), including image metadata routes that return a `Response`
 - Control-flow throws: `notFound()`, `redirect()`, `forbidden()`, `unauthorized()`
 - The no-JS page `action` write path
 - Boundaries: `error.ts`, `loading.ts`, `not-found.ts`, `forbidden.ts`, `unauthorized.ts`, and the two root-only ones
@@ -78,6 +78,18 @@ export async function GET() {
 
 **NEVER throw `redirect()` / `notFound()` / `forbidden()` inside a `route.ts` handler** (an uncaught throw is a generic 500). Return a real response instead: `return Response.redirect(url, 303)` for a redirect, `return new Response('Not Found', { status: 404 })` for a 404. A `route.ts` is also NOT covered by the action CSRF check, so authenticate every mutating endpoint, validate, and rate-limit. Export `WS(ws, req, { params })` from the same file for a WebSocket endpoint.
 
+**The route-handler toolkit** (from `@webjsdev/server`). Two accessors take the request explicitly: `readBody(req)` decodes a rich request body (the inverse of `json()`, round-tripping `Date` / `Map` / `Set` / `BigInt` / `Blob`), and `clientIp(req)` reads the caller IP. To respond with rich types, `json(value)` serializes with the same wire (so a `Date` survives), versus a plain object return that auto-JSONs. The context accessors take NO argument because they read the in-flight request from context: `headers()`, `cookies()`, `requestId()`, `cspNonce()`.
+
+```ts
+import { json, readBody, clientIp } from '@webjsdev/server';
+export async function POST(req: Request) {
+  const body = await readBody(req);            // rich types decoded
+  return json({ at: new Date(), ip: clientIp(req) });  // Date survives the wire
+}
+```
+
+**Calling your own `route.ts` from the client:** use `richFetch<T>(url, opts?)` from `@webjsdev/core`, a drop-in `fetch` that sends `Accept: application/vnd.webjs+json`, encodes a plain-object `body` with the rich wire, and decodes the `json()` response (so `data.at` is a real `Date`). This is the ONE legitimate hand-fetch (importing a `'use server'` action is the way to call the server otherwise, never a hand-written `fetch` to an action).
+
 ## Middleware (`middleware.ts`)
 
 Optional root-level plus per-segment. The default export is `async (req, next) => Response`. Return a Response to short-circuit, or call `next()` and post-process. Per-segment middleware applies to its subtree, outermost to innermost.
@@ -156,3 +168,14 @@ How the result is read (server side): a success PRG-redirects with `303` (to a s
 - Root-only (in `app/` exactly): `global-error.ts` is the app-wide catch-all after nested `error` boundaries are exhausted and renders its OWN `<!doctype><html><body>` (returned verbatim, so keep it static HTML with no components or hydration). `global-not-found.ts` renders for an unmatched-anywhere URL when no `not-found` matches.
 
 Metadata routes (`sitemap.ts`, `robots.ts`, `manifest.ts`, `icon.ts`, `apple-icon.ts`, `opengraph-image.ts`, `twitter-image.ts`) live at app root or static segments and default-export a possibly-async function; `sitemap()` / `sitemapIndex()` from `@webjsdev/server` serialize spec-valid XML.
+
+The IMAGE metadata routes (`icon`, `apple-icon`, `opengraph-image`, `twitter-image`) default-export a function returning a `Response` with an explicit `content-type`, so an inline SVG needs no asset file (buildless). Then point `metadata` at the route via `openGraph.images` / `twitter.images` / `icons` (or drop a static file in `public/` instead).
+
+```ts
+// app/opengraph-image.ts  (OG is 1200x630; apple-icon 180x180)
+export default function OgImage() {
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630">...</svg>`;
+  return new Response(svg, { headers: { 'content-type': 'image/svg+xml' } });
+}
+// app/page.ts  ->  export const metadata = { openGraph: { images: ['/opengraph-image'] } };
+```

package/templates/.agents/skills/webjs/references/runtime.md

@@ -46,7 +46,7 @@ The 103 Early Hints gap costs only a small first-load latency edge where an edge
 webjs create my-app --runtime bun
 ```
 
-`--runtime` is orthogonal to `--template`, so it re-flavors any of full-stack, saas, or api. A Bun scaffold emits a `bun.lock`, a pure `oven/bun:1` Dockerfile plus a bun-install CI, and bun-command agent docs. The test, db, and check tooling still runs on Node.
+`--runtime` is orthogonal to `--template`, so it re-flavors either full-stack or api. A Bun scaffold emits a `bun.lock`, a pure `oven/bun:1` Dockerfile plus a bun-install CI, and bun-command agent docs. The test, db, and check tooling still runs on Node.
 
 ## Running on Bun
 

package/templates/.agents/skills/webjs/references/service-worker.md

@@ -11,7 +11,7 @@ Read this when you want an offline experience or an asset cache in a WebJs app,
 
 ## What ships and why it is safe
 
-WebJs's UI scaffolds (full-stack and saas, not the api template) ship a hand-authored service worker at `public/sw.js` and an offline fallback at `public/offline.html`. Both ship **dormant**: they do nothing until the app registers the worker, and the worker only ever registers from JavaScript. So with JS off no worker exists, and pages, links, and forms behave exactly as before. It is opt-in and adds an offline experience plus an asset cache without changing the no-JS baseline.
+WebJs's UI scaffold (full-stack, not the api template) ships a hand-authored service worker at `public/sw.js` and an offline fallback at `public/offline.html`. Both ship **dormant**: they do nothing until the app registers the worker, and the worker only ever registers from JavaScript. So with JS off no worker exists, and pages, links, and forms behave exactly as before. It is opt-in and adds an offline experience plus an asset cache without changing the no-JS baseline.
 
 This is a thin, hand-readable worker built directly on the native Service Worker and Cache Storage APIs. There is no Workbox, no precache framework, and no bundler step, matching WebJs's no-build, close-to-web-standards posture. The file is yours to edit, not a framework internal.
 

package/templates/.agents/skills/webjs/references/styling.md

@@ -8,6 +8,7 @@
 - Design tokens: `:root` / `@theme` in the root layout
 - Light-DOM host `display: block` behaviour (and shadow hosts via `:host`)
 - When to use `static styles` (shadow DOM)
+- Accessible native controls (label association, `aria-pressed`, `aria-label`)
 - `position: fixed`, not `sticky`, for a pinned header (the iOS WebKit flicker)
 - Even-grid / no-reflow layout tips
 
@@ -67,9 +68,77 @@ export default function Post({ params }) {
 
 Avoid `@apply`: it hides which utilities a class uses and creates a second source of truth. A JS helper keeps the bundle visible at the definition site, composes with conditional classes and active states, and runs at SSR time.
 
-## Design tokens
+### A design system for repeated PRIMITIVES: class helpers built on `@webjsdev/ui`
 
-The default stack is a static compiled Tailwind stylesheet (`css:build` compiles `public/input.css` to the linked `public/tailwind.css`, so it works with JS off) plus `@theme` design tokens (palette, fonts, fluid type, motion durations) declared once in the root layout. Consume them as utility classes (`text-foreground`, `bg-card`, `font-serif`, `duration-fast`). If you wire your own theme switch, drive BOTH signals on `<html>` (the `data-theme` attribute for the app palette blocks AND the `.dark` class for the `@webjsdev/ui` kit), or half the UI renders stale tokens. Verify dark mode in a real browser, light mode passing proves nothing about dark.
+An `html`-fragment helper is right for a repeated CHUNK of markup (the rubric above). For a repeated UI PRIMITIVE (button, input, card, badge) that needs variants and sizes, use a class helper instead: a function that returns a Tailwind class STRING you spread onto a native element. That is exactly what `@webjsdev/ui` ships (`buttonClass({ variant, size })`, `cardClass()`, `inputClass()`, `badgeClass({ variant })`), and it is what the scaffold gallery uses in `components/ui/`. To style a ONE-OFF that a variant does not cover (a circular icon button, a pill), compose the helper and override the bespoke bits with `cn()`: `cn(buttonClass({ variant: 'secondary', size: 'none' }), 'w-9 h-9 rounded-full')`. `cn` resolves Tailwind conflicts so a later class wins, including a shorthand over the axis it subsumes (`p-0` beats an earlier `px-4 py-2`), so an override just works. For an icon button prefer `size: 'none'` (it states "I supply my own box" by dropping the helper's padding + radius) over layering a `p-0` on top of the default size.
+
+```ts
+// components/ui/button.ts  (webjs ui add button, themed to your app)
+import { cn } from '#lib/utils/cn.ts';
+const BASE = 'inline-flex cursor-pointer items-center justify-center ...';
+const VARIANTS = { default: 'bg-primary text-primary-foreground ...', secondary: '...' } as const;
+const SIZES = { default: 'px-4 py-2 rounded-xl', sm: '...' } as const;
+export function buttonClass(o: { variant?: keyof typeof VARIANTS; size?: keyof typeof SIZES } = {}) {
+  return cn(BASE, VARIANTS[o.variant ?? 'default'], SIZES[o.size ?? 'default']);
+}
+```
+
+```ts
+// a page or component
+import { buttonClass } from '#components/ui/button.ts';
+html`<button class=${buttonClass({ variant: 'secondary', size: 'sm' })} @click=${...}>Reset</button>`;
+```
+
+Why a class helper (not a `<ui-button>` wrapper): it adds NO indirection, so the element stays native (`@click`, `?disabled`, form submission, focus, a11y all just work) and the markup stays readable, while every button shares one source of truth (so no button can forget `cursor-pointer` or drift). Put the affordance every variant needs (like `cursor-pointer`) on the shared BASE.
+
+**Own and theme your copy.** `webjs ui add <name>` copies the primitive INTO your `components/ui/`, so you own it. Theme it to YOUR app: change the class values so the helper produces YOUR look, rather than bending your app to the kit's defaults. Keep only the parts you use (the gallery's `cardClass` is surface-only, since its panels vary their own padding and layout). Reserve `lib/utils/ui.ts` `html`-fragment helpers for repeated markup chunks; reserve `components/ui/*` class helpers for themed primitives with variants.
+
+## Accessible native controls
+
+A cleared, growing app hand-authors its own controls, so accessibility is your job (the `@webjsdev/ui` primitives carry their own, but a raw `<button>` / `<input>` does not). Three habits keep hand-authored interactive markup accessible on BOTH the JS and no-JS paths:
+
+- **Associate a label with its control.** `<label for="email">` paired with `<input id="email">` (or wrap the control in the `<label>`), so a click on the label focuses the field and a screen reader announces it.
+- **State a toggle's pressed state.** A button that toggles carries `aria-pressed=${on}` so assistive tech announces on/off, not just "button".
+- **Name an icon-only button.** A button whose only content is an icon has no accessible name, so give it `aria-label="Delete task"`.
+
+Native `<button>` / `<a>` / `<input>` already have correct focus + keyboard behaviour, which is the main reason to prefer them (and the `buttonClass()` / `inputClass()` class helpers) over a custom `<div role>` element.
+
+## Design tokens and theming
+
+The default stack is a static compiled Tailwind stylesheet (`css:build` compiles `public/input.css` to the linked `public/tailwind.css`, so it works with JS off) plus `@theme` design tokens declared once in the root layout. You consume them as utility classes (`bg-background`, `text-foreground`, `bg-card`, `border-border`, `font-serif`).
+
+**Two halves.** (1) `public/input.css` MAPS token names into Tailwind with `@theme inline` (`--color-background: var(--background)`), so `bg-background` resolves to `var(--background)`. That is infrastructure; leave it. (2) The root layout (`app/layout.ts`) DEFINES the values as plain CSS custom properties in a `<style>` block. That is your palette; make it your own. A freshly cleared app (after `npm run gallery:clear`) ships only the OS system-colour base (`Canvas` / `CanvasText`) with NO tokens, so building this palette is your first styling step.
+
+**Light and dark, defined once (DRY).** Write each colour token ONE time with the native CSS `light-dark(LIGHT, DARK)` function and let `color-scheme` pick the side. The default `color-scheme: light dark` follows the OS; a `[data-theme]` attribute forces one. No duplicated light/dark blocks:
+
+```html
+<style>
+  :root {
+    --font-sans: ui-sans-serif, system-ui, sans-serif;
+    color-scheme: light dark;                        /* follow the OS by default */
+    --background:       light-dark(#ffffff, #1e2226);
+    --foreground:       light-dark(#191c20, #dee2e6);
+    --card:             light-dark(#f7f8fa, #313539);
+    --muted-foreground: light-dark(#565c64, #94989c);
+    --border:           light-dark(#e2e5e9, #3d434b);
+    --primary:          light-dark(#1e2226, #dee2e6);
+    /* a derived token tracks BOTH themes for free via var(--primary) */
+    --primary-tint: color-mix(in srgb, var(--primary) 22%, transparent);
+  }
+  :root[data-theme='light'] { color-scheme: light; }  /* the toggle forces a scheme */
+  :root[data-theme='dark']  { color-scheme: dark; }
+</style>
+```
+
+`light-dark()` is a native CSS function (CSS Color 5, Baseline 2024), not a library, so nothing to import. A single-theme app drops the `[data-theme]` rules and gives each token one colour.
+
+**A manual theme toggle** writes `data-theme` on `<html>` (`light` / `dark`, or removes it for "follow the OS"). If you use `@webjsdev/ui` components, ALSO keep the `.dark` class in sync (the ui kit keys its own tokens off `.dark`), and apply the saved choice in a tiny inline `<script>` in the layout head so there is no first-paint flash. Verify dark mode in a real browser. Light mode passing proves nothing about dark.
+
+**Edge cases.** `light-dark()` is COLOUR-only. A colour needed in just one theme sets the unused side to a no-op (`light-dark(#fff, transparent)`). A derived token that references a `light-dark()` one (like `--primary-tint` above) tracks both themes automatically. A NON-colour token that must differ per theme (a shadow's geometry, a gradient, a size, an image) cannot use `light-dark()`; give it a `:root[data-theme='dark']` override plus an `@media (prefers-color-scheme: dark) { :root:not([data-theme]) { ... } }` rule for the OS default.
+
+**The ui class helpers build on these tokens.** `buttonClass()` / `cardClass()` / `inputClass()` / `badgeClass()` emit Tailwind utilities that reference the same tokens (`bg-primary`, `border-border`), so theming the tokens re-skins every helper at once.
+
+**Focus rings.** The design system applies ONE themed, keyboard-only focus ring globally in the theme CSS: `@layer base { * { @apply border-border outline-ring/50 } }` themes the outline COLOUR to `--ring/50`, and a `:focus-visible { outline: 2px solid color-mix(in oklab, var(--color-ring) 50%, transparent); outline-offset: 2px }` forces a SOLID outline. That second rule matters: `outline-ring/50` alone leaves `outline-style: auto`, so the browser draws its OWN focus ring (which can look thick and white and ignore the colour). So every focusable element (button, link, input) shares one `--ring`-coloured ring with no per-element styling (a native `<button>` renders it a touch wider than a link, a Chromium form-control quirk, but the colour is the same). Do NOT re-add a focus style on a light-DOM element (`buttonClass` deliberately carries none), and NEVER remove it (`outline: none` with no replacement fails WCAG 2.4.7). `:focus-visible` already limits the ring to keyboard / programmatic focus, not a mouse click. A SHADOW-DOM component is the ONE exception: a document rule cannot cross the shadow boundary, so it styles its own focus in `static styles`, matching the global ring EXACTLY (`--ring` at 50%, the same as `outline-ring/50`): `button:focus-visible { outline: 2px solid color-mix(in oklab, var(--color-ring) 50%, transparent); outline-offset: 2px }`. Without it, its controls fall back to the raw browser outline (thick, light on a dark theme, and shown on window-refocus).
 
 ## Light-DOM host display, and shadow hosts
 
@@ -83,6 +152,17 @@ static styles = css`:host { display: block }`;   // a shadow host with no :host
 
 **Size the HOST, not just an inner wrapper.** The host custom element is the box the parent lays out. A host that is a flex/grid item in a centering parent (`flex justify-center`, `grid place-items-center`) is sized to its content unless it carries width itself. Put the sizing classes on the host (`w-full max-w-[400px]`), not only on an inner `<div>`. Symptom: a board or card renders tiny even though its inner grid says `w-full max-w-[400px]`. Fix: move the sizing onto the host.
 
+## Section rhythm: one gap, defined once
+
+Per-element margins can never give consistent vertical spacing: each element controls only one side, so a block's gap-above (the previous element's margin) drifts from its gap-below (its own). For a content column (a docs page, a demo page, an article), make the COLUMN own the spacing with a flex stack, and zero the children's own margins so only the one gap applies:
+
+```css
+.stack { --section-gap: 1.5rem; display: flex; flex-direction: column; gap: var(--section-gap); }
+.stack > * { margin: 0; }
+```
+
+Every top-level child (heading, paragraph, component, list) is then equally spaced from ONE variable, and a spacing change is a one-line edit. Flex `gap` beats forcing `display: block` + margins on children: a `grid`/`flex` child keeps its own layout (a blanket `display: block` clobbers it), an inline shadow-DOM host is blockified as a flex item so it honours the gap, a `display: contents` element (a streaming `<webjs-suspense>`) is replaced by its children which become the flex items, and a `display: none` node (a streaming `<script>`/`<template>`) is not an item at all, so it gets no phantom gap. A group that must stay tight (a caption directly above its code block) wraps in one child `<div>` and keeps its own inner spacing. The gallery's `/features` layout (`demo-stack`) is the worked example.
+
 ## Even grids, no reflow
 
 The reflow bug (a cell grows when it gets content while the others shrink) comes from `auto`-sized grid rows. Size the tracks explicitly so every cell is an equal fraction regardless of content:

package/templates/AGENTS.md

@@ -30,14 +30,21 @@ The order matters:
    `.agents/skills/webjs/` teaches the same patterns and SURVIVES the clear, so
    clearing is not a knowledge-loss event, the gallery is just a runnable bonus.
 2. **Clear it.** Run `npm run gallery:clear` to shed the whole gallery in one
-   step (removes `app/features/`, `app/examples/`, the demo `modules/`, the demo
-   `todos` table, and resets `app/page.ts` to a minimal home), while KEEPING the
-   agent skill, the layout, and the database wiring.
+   step: it removes `app/features/`, `app/examples/`, the demo `modules/`, the
+   gallery's example design system (`components/ui/`, the theme-toggle), the
+   example tests, and the demo `todos` table, and resets `app/page.ts` to a
+   minimal home AND `app/layout.ts` to a token-free blank slate (OS system
+   colours, no navbar, no palette). A layout you already customised (the gallery
+   brand removed) is KEPT, with only the theme-toggle wiring stripped. It KEEPS
+   the agent skill, the database wiring, and `lib/utils/cn.ts` (the
+   `webjs ui add` prerequisite).
 3. **Build.** Regenerate the database (`npm run db:generate` then `npm run
    db:migrate`), then grow the app in place: routes under `app/`, components
    under `components/`, features under `modules/<feature>/`, server-only code
-   behind `.server.ts`, and the app's own palette via the tokens in
-   `app/layout.ts`.
+   behind `.server.ts`. Build the app's OWN design system from the blank slate:
+   define design tokens in `app/layout.ts` and pull primitives with
+   `npx webjsdev ui add <name>`, following
+   `.agents/skills/webjs/references/styling.md`.
 
 If you are only exploring, keep the gallery and browse it.
 

package/templates/gallery/app/api/auth/[...path]/route.ts

@@ -0,0 +1,7 @@
+// The createAuth HTTP endpoints (signin, signout, OAuth callbacks). This route
+// stays at the app root, NOT under app/features/auth/, because createAuth
+// hardcodes /api/auth/signin/* and /api/auth/callback/* for its form posts and
+// OAuth redirect URIs. The rest of the auth card lives under app/features/auth/.
+import { handlers } from '#modules/auth/auth.server.ts';
+export const GET = handlers.GET;
+export const POST = handlers.POST;

package/templates/gallery/app/apple-icon.ts

@@ -1,14 +1,11 @@
-// (delete this file), then delete this marker line. webjs check fails while the
-// marker remains.
-//
 // app/apple-icon.ts serves /apple-icon (the Apple touch icon iOS uses when a
 // visitor adds the site to their home screen). Apple expects a 180x180 square
 // with no rounded corners (iOS rounds them). Same shape as icon.ts: return a
 // Response with the exact content type. Swap the inline SVG for your real mark.
 export default function AppleIcon() {
   const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="180" height="180" viewBox="0 0 180 180">
-    <rect width="180" height="180" fill="#1c1613"/>
-    <text x="90" y="120" font-family="system-ui, sans-serif" font-size="104" font-weight="700" fill="#ff8a3d" text-anchor="middle">w</text>
+    <rect width="180" height="180" fill="#1e2226"/>
+    <text x="90" y="120" font-family="system-ui, sans-serif" font-size="104" font-weight="700" fill="#94989c" text-anchor="middle">w</text>
   </svg>`;
   return new Response(svg, {
     headers: { 'content-type': 'image/svg+xml', 'cache-control': 'public, max-age=3600' },

package/templates/gallery/app/examples/layout.ts

@@ -0,0 +1,16 @@
+import { html } from '@webjsdev/core';
+import { backLink } from '#lib/utils/ui.ts';
+
+// Shared layout for every gallery example app under /examples/*. It adds the same
+// slim "back to the gallery" link the feature demos get, so an example is never a
+// dead end. A non-root layout, so it never writes the document shell.
+export default function ExamplesLayout({ children }: { children: unknown }) {
+  // An example app has no sidebar, so center it in a focused reading column
+  // (the root centers the whole page; this narrows the example within it).
+  return html`
+    <div class="max-w-xl mx-auto">
+      <div class="mb-6">${backLink('/', html`&larr; Gallery`)}</div>
+      ${children}
+    </div>
+  `;
+}

package/templates/gallery/app/examples/todo/page.ts

@@ -4,6 +4,7 @@
 // lives in modules/todo/. This is the idiomatic app-thin + modules-logic split.
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core'; // Metadata is a @webjsdev/core type
+import { pageHeading } from '#lib/utils/ui.ts';
 import { listTodos } from '#modules/todo/queries/list-todos.server.ts';
 import { createTodo } from '#modules/todo/actions/create-todo.server.ts';
 import { toggleTodo } from '#modules/todo/actions/toggle-todo.server.ts';
@@ -16,7 +17,7 @@ export default async function TodoExample() {
   // SSR-fetched and seeded, so <todo-app> paints the real list on first byte.
   const todos = await listTodos();
   return html`
-    <h1 class="text-h2 font-bold mb-4">Optimistic todo</h1>
+    ${pageHeading('Optimistic todo')}
     <todo-app .todos=${todos}></todo-app>
   `;
 }

package/templates/gallery/app/features/async-render/page.ts

@@ -1,5 +1,6 @@
 import { html, Suspense } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
+import { pageHeading, lede } from '#lib/utils/ui.ts';
 import '#modules/async-render/components/server-clock.ts';
 
 export const metadata: Metadata = { title: 'Async render (server data in first paint) | features' };
@@ -14,8 +15,8 @@ async function slowRegion() {
 
 export default function AsyncRenderExample() {
   return html`
-    <h1 class="text-h2 font-bold mb-4">Async render</h1>
-    <p class="text-muted-foreground mb-4">A component's <code>async render()</code> awaits server data. SSR blocks, so the resolved value is in the first paint (no fallback, readable with JS off).</p>
+    ${pageHeading('Async render')}
+    ${lede(html`A component's <code>async render()</code> awaits server data. SSR blocks, so the resolved value is in the first paint (no fallback, readable with JS off).`)}
     <server-clock></server-clock>
     <p class="text-muted-foreground mt-6 mb-2">For a SLOW region where blocking the first byte hurts, wrap it in <code class="font-mono">Suspense</code> to stream it instead:</p>
     ${Suspense({ fallback: html`<p class="text-muted-foreground">loading slow region…</p>`, children: slowRegion() })}

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

@@ -0,0 +1,21 @@
+import { html } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
+
+// Nested layout for the protected dashboard subtree. Logout is a plain
+// <form method="POST"> posting to the createAuth signout route: it clears the
+// session cookie and 302s home, and works with JS off (progressive-enhancement
+// default). signOut is server-only (modules/auth/auth.server.ts), so we POST to
+// its route rather than import it into a browser-shipping page. After signout the
+// dashboard middleware bounces any later visit to login.
+export default function DashboardLayout({ children }: { children: unknown }) {
+  return html`
+    <nav class="flex items-center gap-4 mb-6 pb-4 border-b border-border">
+      <a href="/features/auth/dashboard" class="text-sm font-medium text-foreground hover:underline">Dashboard</a>
+      <a href="/features/auth/dashboard/settings" class="text-sm font-medium text-foreground hover:underline">Settings</a>
+      <form method="POST" action="/api/auth/signout" class="ml-auto">
+        <button type="submit" class=${buttonClass({ variant: 'secondary', size: 'sm' })}>Log out</button>
+      </form>
+    </nav>
+    ${children}
+  `;
+}

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

@@ -0,0 +1,14 @@
+import { auth } from '#modules/auth/auth.server.ts';
+
+// The protected-route gate. A per-segment middleware.ts runs for every request
+// under /features/auth/dashboard/*. It reads the signed session off the request
+// with auth(req); with no valid session it 302s to login BEFORE the page renders,
+// so an anonymous visitor never sees the protected content. This needs no DB
+// query (only a cookie read), so the gate is real the moment the app boots.
+export default async function requireAuth(req: Request, next: () => Promise<Response>) {
+  const session = await auth(req);
+  if (!session?.user) {
+    return new Response(null, { status: 302, headers: { location: '/features/auth/login' } });
+  }
+  return next();
+}

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

@@ -0,0 +1,20 @@
+import { html } from '@webjsdev/core';
+import { cardClass } from '#components/ui/card.ts';
+import { badgeClass } from '#components/ui/badge.ts';
+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=${badgeClass()}>Signed in</span>
+    </div>
+    <div class="${cardClass()} p-6">
+      <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,22 @@
+import { html } from '@webjsdev/core';
+import { cardClass } from '#components/ui/card.ts';
+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="${cardClass()} p-6">
+      <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/middleware.ts

@@ -0,0 +1,15 @@
+import { auth } from '#modules/auth/auth.server.ts';
+
+// The mirror of the dashboard's protect-middleware: a visitor who is ALREADY
+// signed in has no reason to see the login form, so send them to the dashboard.
+// A per-segment middleware.ts reads the signed session off the request with
+// auth(req) (a cookie read, no DB), so the redirect happens before the page
+// renders. Keeping the check in middleware (not the page) keeps auth.server.ts
+// off the client.
+export default async function redirectIfSignedIn(req: Request, next: () => Promise<Response>) {
+  const session = await auth(req);
+  if (session?.user) {
+    return new Response(null, { status: 302, headers: { location: '/features/auth/dashboard' } });
+  }
+  return next();
+}

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

@@ -0,0 +1,43 @@
+import { html } from '@webjsdev/core';
+import { cardClass } from '#components/ui/card.ts';
+import { inputClass } from '#components/ui/input.ts';
+import { buttonClass } from '#components/ui/button.ts';
+
+export const metadata = { title: 'Log in' };
+
+const inputCls = inputClass();
+
+// 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="${cardClass()} grid gap-4 p-5">
+        <!-- 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="${buttonClass()} justify-self-start">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 underline underline-offset-2">Sign up</a></p>
+    </div>
+  `;
+}

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

@@ -0,0 +1,34 @@
+// 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 { pageHeading, lede } from '#lib/utils/ui.ts';
+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`
+    ${pageHeading('Auth')}
+    ${lede(html`Password login on <code>createAuth</code>, a signed session cookie, and a protected <code>/features/auth/dashboard</code> that redirects anonymous visitors to login.`)}
+
+    ${user
+      ? html`
+        <p class="mb-4">Signed in as <strong>${user.name || user.email}</strong>.</p>
+        <p><a class="text-primary underline underline-offset-2" href="/features/auth/dashboard">Open the protected dashboard</a></p>`
+      : html`
+        <p class="mb-4">You are signed out. <a class="text-primary underline underline-offset-2" href="/features/auth/dashboard">Visiting the dashboard</a> bounces you to login.</p>
+        <p class="flex gap-4"><a class="text-primary underline underline-offset-2" href="/features/auth/login">Log in</a><a class="text-primary underline underline-offset-2" 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/middleware.ts

@@ -0,0 +1,11 @@
+import { auth } from '#modules/auth/auth.server.ts';
+
+// Like the login middleware: an already-signed-in visitor has no reason to see
+// the signup form, so send them to the dashboard before the page renders.
+export default async function redirectIfSignedIn(req: Request, next: () => Promise<Response>) {
+  const session = await auth(req);
+  if (session?.user) {
+    return new Response(null, { status: 302, headers: { location: '/features/auth/dashboard' } });
+  }
+  return next();
+}

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

@@ -0,0 +1,61 @@
+import { html } from '@webjsdev/core';
+import { cardClass } from '#components/ui/card.ts';
+import { inputClass } from '#components/ui/input.ts';
+import { buttonClass } from '#components/ui/button.ts';
+import { signup } from '#modules/auth/actions/signup.server.ts';
+
+export const metadata = { title: 'Sign up' };
+
+const inputCls = inputClass();
+
+// 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="${cardClass()} grid gap-4 p-5">
+        <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="${buttonClass()} justify-self-start">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 underline underline-offset-2">Log in</a></p>
+    </div>
+  `;
+}

package/templates/gallery/app/features/boundaries/error.ts

@@ -3,14 +3,15 @@
 // rendered scoped to this boundary, so outer layouts stay alive. The default
 // export receives { error, ...ctx }; in production only error.message is sent.
 import { html } from '@webjsdev/core';
+import { pageHeading, lede } from '#lib/utils/ui.ts';
 
 export default function BoundariesError({ error }: { error: Error }) {
   return html`
-    <h1 class="text-h2 font-bold mb-4">Something went wrong</h1>
-    <p class="text-muted-foreground mb-4">
+    ${pageHeading('Something went wrong')}
+    ${lede(html`
       This segment's <code class="font-mono">error.ts</code> boundary caught a
       render error: <code class="font-mono">${error?.message ?? 'unknown'}</code>.
-    </p>
-    <p><a class="text-primary" href="/features/boundaries">Back to boundaries</a></p>
+    `)}
+    <p><a class="text-primary underline underline-offset-2" href="/features/boundaries">Back to boundaries</a></p>
   `;
 }

package/templates/gallery/app/features/boundaries/gated/forbidden.ts

@@ -4,15 +4,16 @@
 // forbidden.ts higher up the tree. Keep the message actionable for an
 // authenticated user who lacks permission.
 import { html } from '@webjsdev/core';
+import { pageHeading, lede } from '#lib/utils/ui.ts';
 
 export default function Forbidden() {
   return html`
-    <h1 class="text-h2 font-bold mb-4">403 Forbidden</h1>
-    <p class="text-muted-foreground mb-4">
+    ${pageHeading('403 Forbidden')}
+    ${lede(html`
       You are signed in but do not have permission to view this page. This is the
       nearest <code class="font-mono">forbidden.ts</code> boundary, rendered
       because the page threw <code class="font-mono">forbidden()</code>.
-    </p>
-    <p><a class="text-primary" href="/features/boundaries">Back to boundaries</a></p>
+    `)}
+    <p><a class="text-primary underline underline-offset-2" href="/features/boundaries">Back to boundaries</a></p>
   `;
 }

package/templates/gallery/app/features/boundaries/not-found.ts

@@ -3,15 +3,16 @@
 // /features/boundaries/ (try /features/boundaries/does-not-exist). Nearest wins,
 // so this beats the root not-found for anything in this segment.
 import { html } from '@webjsdev/core';
+import { pageHeading, lede } from '#lib/utils/ui.ts';
 
 export default function BoundariesNotFound() {
   return html`
-    <h1 class="text-h2 font-bold mb-4">404: Not here</h1>
-    <p class="text-muted-foreground mb-4">
+    ${pageHeading('404: Not here')}
+    ${lede(html`
       This segment's <code class="font-mono">not-found.ts</code> boundary rendered,
       because a page threw <code class="font-mono">notFound()</code> or the URL
       matched nothing under this segment.
-    </p>
-    <p><a class="text-primary" href="/features/boundaries">Back to boundaries</a></p>
+    `)}
+    <p><a class="text-primary underline underline-offset-2" href="/features/boundaries">Back to boundaries</a></p>
   `;
 }