@webjsdev/cli 0.10.36 → 0.10.37

package/lib/create.js

@@ -539,6 +539,8 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     'test/hello/browser/hello.test.js',
     'test/hello/e2e/hello.test.ts',
     'web-test-runner.config.js',
+    // Optional boot-time APM hook (setOnError). Delete if unused.
+    'instrumentation.ts',
     // Environment variables
     '.env.example',
     // Project-level gitignore (node_modules, .webjs, .env, OS junk).
@@ -1381,6 +1383,7 @@ const features = [
   { 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.' },
   { 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/sessions', title: 'Sessions', blurb: 'A signed-cookie session applied by a segment middleware, read and written per visitor with getSession() in a route.' },
 ];
 const examples = [
   { 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.' },
@@ -1479,6 +1482,7 @@ const features = [
   { 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.' },
   { 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/sessions', title: 'Sessions', blurb: 'A signed-cookie session applied by a segment middleware, read and written per visitor with getSession() in a route.' },
 ];
 const examples = [
   { 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.' },

package/lib/saas-template.js

@@ -88,7 +88,7 @@ export async function writeSaasFiles(appDir, opts = {}) {
 
   // lib/auth.server.ts
   await writeFile(join(appDir, 'lib', 'auth.server.ts'), [
-    "import { createAuth, Credentials } from '@webjsdev/server';",
+    "import { createAuth, Credentials, GitHub, Google } from '@webjsdev/server';",
     "import { db } from '#db/connection.server.ts';",
     "import { compare } from './password.server.ts';",
     "",
@@ -110,6 +110,12 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "        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,",
     "});",

package/package.json

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

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

@@ -0,0 +1,17 @@
+// webjs-scaffold-placeholder. Metadata route. Keep and adapt it, or prune it
+// (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>
+  </svg>`;
+  return new Response(svg, {
+    headers: { 'content-type': 'image/svg+xml', 'cache-control': 'public, max-age=3600' },
+  });
+}

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

@@ -1,14 +1,24 @@
 // webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/async-render route AND modules/async-render), then delete this marker line. webjs check fails while the marker remains.
-import { html } from '@webjsdev/core';
+import { html, Suspense } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
 import '#modules/async-render/components/server-clock.ts';
 
 export const metadata: Metadata = { title: 'Async render (server data in first paint) | features' };
 
+// A slow server region. Suspense flushes the fallback on the first byte and
+// streams the resolved content in when it settles, so a slow query does not
+// block the whole page's first paint. Multiple boundaries stream concurrently.
+async function slowRegion() {
+  await new Promise((r) => setTimeout(r, 800));
+  return html`<p class="text-foreground">Streamed in after the first byte.</p>`;
+}
+
 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>
     <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/caching/page.ts

@@ -8,6 +8,7 @@
 // use HTTP Cache-Control + ETag (conditional GET).
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
+import '#modules/caching/components/cache-buster.ts';
 
 export const metadata: Metadata = { title: 'Caching (revalidate) | features' };
 
@@ -35,5 +36,13 @@ export default function CachingExample() {
       <code>revalidateTag</code>, or a GET action's
       <code>export const cache</code>.
     </p>
+    <p class="text-muted-foreground text-sm mt-6 mb-2">
+      A mutation evicts the cache on demand. Click below (it calls
+      <code class="font-mono">revalidatePath('/features/caching')</code>), then refresh:
+      the timestamp updates immediately, even inside the 10s window, because the
+      cached HTML was dropped. Without clicking, the refresh serves the cached
+      copy until the window elapses.
+    </p>
+    <cache-buster></cache-buster>
   `;
 }

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

@@ -3,6 +3,8 @@ import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
 import '#modules/components/components/counter-card.ts';
 import '#modules/components/components/reactive-meter.ts';
+import '#modules/components/components/theme-context.ts';
+import '#modules/components/components/task-loader.ts';
 
 export const metadata: Metadata = { title: 'Components (signals + slots) | features' };
 
@@ -13,5 +15,11 @@ export default function ComponentsExample() {
     <counter-card label="Taps"><strong>A slotted title</strong></counter-card>
     <p class="text-muted-foreground mt-6 mb-2">Shadow DOM (scoped <code class="font-mono">css</code>) plus the rest of the signals API (<code class="font-mono">computed</code>, <code class="font-mono">effect</code>, <code class="font-mono">batch</code>):</p>
     <reactive-meter></reactive-meter>
+    <p class="text-muted-foreground mt-6 mb-2">The context API (<code class="font-mono">createContext</code> + <code class="font-mono">ContextProvider</code> / <code class="font-mono">ContextConsumer</code>): a value passed to a nested child without attribute drilling.</p>
+    <theme-provider>
+      <theme-consumer></theme-consumer>
+    </theme-provider>
+    <p class="text-muted-foreground mt-6 mb-2">A <code class="font-mono">Task</code> for client-only async data, switching on <code class="font-mono">TaskStatus</code>:</p>
+    <task-loader></task-loader>
   `;
 }

package/templates/gallery/app/features/file-storage/file/[key]/route.ts

@@ -4,8 +4,17 @@
 // storage singleton here is safe. The [key] segment is validated inside the
 // store (traversal-safe), so a crafted key cannot escape the uploads directory.
 import { getFileStore } from '@webjsdev/server';
+import { isValidSignedRequest } from '#modules/file-storage/store.server.ts';
 
-export async function GET(_req: Request, { params }: { params: { key: string } }) {
+export async function GET(req: Request, { params }: { params: { key: string } }) {
+  // If the request carries signed-URL params (?exp&sig), require them to be
+  // valid: this is how a private file is shared by link. A request WITHOUT the
+  // params is served normally here (the gallery demo keeps public access); drop
+  // that branch to make every download require a valid signature.
+  const url = new URL(req.url);
+  if (url.searchParams.has('sig') && !isValidSignedRequest(req.url)) {
+    return new Response('Forbidden', { status: 403 });
+  }
   const file = await getFileStore().get(params.key);
   if (!file) return new Response('Not found', { status: 404 });
   // file.body is a web ReadableStream at runtime (the diskStore streams the

package/templates/gallery/app/features/rate-limit/page.ts

@@ -22,7 +22,7 @@ export default function RateLimitExample() {
     <rate-probe></rate-probe>
     <p class="text-muted-foreground text-sm mt-4">
       With JavaScript off, hit
-      <a class="text-primary" href="/features/rate-limit/ping">/features/rate-limit/ping</a>
+      <a class="text-primary" href="/features/rate-limit/ping" data-no-router>/features/rate-limit/ping</a>
       directly (refresh past five times in ten seconds).
     </p>
   `;

package/templates/gallery/app/features/route-handler/data/route.ts

@@ -1,8 +1,37 @@
 // A route.ts is a server-only HTTP handler (named GET / POST / PUT / PATCH /
 // DELETE exports). It is NOT isomorphic and never ships to the client, the webjs
-// equivalent of a Next route handler. Each handler returns a Response (a plain
-// value auto-JSONs). A folder cannot have BOTH page.ts and route.ts, so this
-// endpoint lives one segment deeper, at /features/route-handler/data.
-export async function GET() {
-  return Response.json({ ok: true, at: new Date().toISOString() });
+// equivalent of a Next route handler. A folder cannot have BOTH page.ts and
+// route.ts, so this endpoint lives one segment deeper, at
+// /features/route-handler/data.
+//
+// `json(data)` (from @webjsdev/server) responds with the WebJs rich serializer,
+// so a `Date` (or Map / Set / BigInt) round-trips as its real type when the
+// caller uses `richFetch` (see modules/route-handler/components/rich-data.ts).
+// The request accessors read the IN-FLIGHT request from context: `headers()`,
+// `cookies()`, and `requestId()` take no argument (they read the active
+// request), while `clientIp(req)` and `readBody(req)` take it explicitly.
+import { json, headers, cookies, clientIp, requestId, cspNonce, readBody } from '@webjsdev/server';
+
+export async function GET(req: Request) {
+  return json({
+    ok: true,
+    at: new Date(), // a real Date; richFetch decodes it back to a Date, not a string
+    ip: clientIp(req),
+    requestId: requestId(),
+    userAgent: headers().get('user-agent') ?? 'unknown',
+    // cookies() reads the REQUEST cookies. Report how many are present (a
+    // truthful, always-correct value); the app's theme lives in localStorage,
+    // not a cookie, so do not read it here.
+    cookieCount: cookies().entries().length,
+    // cspNonce() reads the request's CSP nonce ('' with CSP off). Server-side
+    // you use it to nonce a server-rendered inline <script>/<style> under CSP.
+    hasNonce: cspNonce().length > 0,
+  });
+}
+
+export async function POST(req: Request) {
+  // readBody(req) parses the request body (the inverse of json()): rich types
+  // sent by richFetch are decoded here.
+  const body = await readBody(req);
+  return json({ echoed: body, at: new Date() });
 }

package/templates/gallery/app/features/route-handler/page.ts

@@ -1,13 +1,16 @@
 // webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/route-handler route, including its data/route.ts handler), then delete this marker line. webjs check fails while the marker remains.
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
+import '#modules/route-handler/components/rich-data.ts';
 
 export const metadata: Metadata = { title: 'Route handlers (route.ts) | features' };
 
 export default function RouteHandlerExample() {
   return html`
     <h1 class="text-h2 font-bold mb-4">Route handlers</h1>
-    <p class="text-muted-foreground mb-4">A <code>route.ts</code> is a server-only HTTP endpoint (named <code>GET</code>/<code>POST</code>/... exports), the webjs equivalent of a Next route handler. It never ships to the client.</p>
-    <p><a class="text-primary" href="/features/route-handler/data">GET /features/route-handler/data</a> returns JSON.</p>
+    <p class="text-muted-foreground mb-4">A <code>route.ts</code> is a server-only HTTP endpoint (named <code>GET</code>/<code>POST</code>/... exports), the WebJs equivalent of a Next route handler. It never ships to the client.</p>
+    <p>GET <a class="text-primary" href="/features/route-handler/data" data-no-router>/features/route-handler/data</a> returns rich JSON via <code class="font-mono">json()</code>. It carries <code class="font-mono">data-no-router</code> so the client router does not try to soft-navigate to it: a <code>route.ts</code> is not a page, so the browser loads its JSON directly.</p>
+    <p class="text-muted-foreground mt-6 mb-2">A client component reading it with <code class="font-mono">richFetch</code>, so <code class="font-mono">at</code> comes back as a real <code class="font-mono">Date</code>:</p>
+    <rich-data></rich-data>
   `;
 }

package/templates/gallery/app/features/routing/legacy/page.ts

@@ -0,0 +1,12 @@
+// A redirect: throw redirect(url) from a page to short-circuit the render into
+// a redirect response. This route always sends you to the routing index, the
+// pattern for a moved or renamed URL. The status is convention-picked at the
+// catching site (302 for a GET page-render gate, 307 for a server-action
+// redirect); pass redirect(url, 308) for a permanent one, or an absolute URL
+// for an external redirect. NEVER throw redirect() from a route.ts handler,
+// which must return Response.redirect(url, 303) instead.
+import { redirect } from '@webjsdev/core';
+
+export default function LegacyRoute() {
+  redirect('/features/routing');
+}

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

@@ -14,6 +14,7 @@ export default function RoutingExample() {
     <ul class="list-disc pl-5 mb-4">
       <li><a class="text-primary" href="/features/routing/42">/features/routing/42</a></li>
       <li><a class="text-primary" href="/features/routing/hello">/features/routing/hello</a></li>
+      <li><a class="text-primary" href="/features/routing/legacy">/features/routing/legacy</a> throws <code class="font-mono">redirect()</code> back here</li>
     </ul>
     <p class="text-muted-foreground text-sm mb-2">
       Routes are type-safe: <code class="font-mono">webjs types</code> (run by

package/templates/gallery/app/features/sessions/count/route.ts

@@ -0,0 +1,12 @@
+// getSession(req) reads the Session for the in-flight request (populated by the
+// session middleware one level up). It is a small key/value store with .get() /
+// .set() / .flash() / .destroy(); mutating it makes the middleware re-sign and
+// set the cookie on the way out. Here each request bumps a per-visitor counter.
+import { json, getSession } from '@webjsdev/server';
+
+export async function GET(req: Request) {
+  const s = getSession(req);
+  const count = (Number(s.get('count')) || 0) + 1;
+  s.set('count', count);
+  return json({ count });
+}

package/templates/gallery/app/features/sessions/middleware.ts

@@ -0,0 +1,7 @@
+// Per-segment middleware: applies the cookie session to every request under
+// /features/sessions, so getSession(req) works in the route below. Middleware
+// nests by folder (outermost to innermost); this one scopes the session to just
+// this feature. A root middleware.ts would apply it app-wide.
+import { cookieSessions } from '#modules/sessions/session-config.server.ts';
+
+export default cookieSessions;

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

@@ -0,0 +1,19 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/sessions route AND modules/sessions), then delete this marker line. webjs check fails while the marker remains.
+// Sessions: a per-segment middleware.ts applies session() (a signed cookie by
+// default; store-backed for larger sessions), and a route.ts reads/writes it
+// with getSession(req). Session state is per-user, so it lives on the server
+// boundary (a route/middleware), never in a page/component that ships to the
+// browser. See modules/sessions/session-config.server.ts.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+
+export const metadata: Metadata = { title: 'Sessions (cookie + store) | features' };
+
+export default function SessionsExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Sessions</h1>
+    <p class="text-muted-foreground mb-4">A per-segment <code>middleware.ts</code> applies <code>session()</code>; a <code>route.ts</code> reads it with <code>getSession(req)</code>.</p>
+    <p>GET <a class="text-primary" href="/features/sessions/count" data-no-router>/features/sessions/count</a> increments a per-visitor counter kept in the signed session cookie. Reload it and the count climbs; open it in a private window and it starts over. (<code class="font-mono">data-no-router</code> opts the link out of the client router, since a <code>route.ts</code> returns JSON, not a page.)</p>
+    <p class="text-muted-foreground text-sm mt-3">Swap the storage from <code class="font-mono">cookieSession()</code> to <code class="font-mono">storeSession()</code> to hold larger sessions in the active store (Redis in production).</p>
+  `;
+}

package/templates/gallery/app/global-error.ts

@@ -0,0 +1,46 @@
+// webjs-scaffold-placeholder. Keep and adapt it, or prune it (delete this
+// file), then delete this marker line. webjs check fails while the marker
+// remains.
+//
+// app/global-error.ts is the ROOT-ONLY, app-wide catch-all error boundary. It
+// fires only after every nested error.ts boundary is exhausted, which includes
+// a failure in the root layout itself. Because a root-layout failure is exactly
+// when it runs, it renders its OWN complete document (<!doctype><html><body>),
+// returned verbatim with NO framework <head> splice, so it ships no importmap
+// and no boot script. Keep it static HTML with no components or hydration: a
+// last-resort page must not depend on the module system that may have just
+// failed. (Under an opt-in CSP, any inline <style>/<script> here needs a nonce
+// via cspNonce() from @webjsdev/server.)
+//
+// Distinct from error.ts (a nested, per-segment boundary that renders a body
+// fragment the framework wraps) and from global-not-found.ts (the unmatched-URL
+// 404). In production only error.message is exposed, never the stack.
+import { html, cspNonce } from '@webjsdev/core';
+
+export default function GlobalError({ error }: { error: Error }) {
+  const message = process.env.NODE_ENV === 'production'
+    ? 'Something went wrong. Please try again.'
+    : error?.message || 'Unknown error';
+  // cspNonce() is '' with CSP off (the default), so this is safe as-is; under an
+  // opt-in CSP it carries the per-request nonce so the inline <style> is allowed.
+  return html`<!doctype html>
+    <html lang="en">
+      <head>
+        <meta charset="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <title>Something went wrong</title>
+        <style nonce="${cspNonce()}">
+          body { font: 16px/1.6 system-ui, sans-serif; margin: 0; display: grid; place-items: center; min-height: 100vh; background: #1c1613; color: #f5f0eb; }
+          main { max-width: 32rem; padding: 2rem; text-align: center; }
+          a { color: #ff8a3d; }
+        </style>
+      </head>
+      <body>
+        <main>
+          <h1>Something went wrong</h1>
+          <p>${message}</p>
+          <p><a href="/">Back to home</a></p>
+        </main>
+      </body>
+    </html>`;
+}

package/templates/gallery/app/global-not-found.ts

@@ -0,0 +1,22 @@
+// webjs-scaffold-placeholder. Keep and adapt it, or prune it (delete this
+// file), then delete this marker line. webjs check fails while the marker
+// remains.
+//
+// app/global-not-found.ts is the ROOT-ONLY 404 for a URL that matches nothing
+// anywhere, used when no nested not-found.ts applies. Unlike global-error.ts it
+// renders only a BODY fragment: the framework wraps it in the document shell
+// (head, importmap, boot script), so the client router and components work
+// here. Use a nested <segment>/not-found.ts for a section-specific 404 (nearest
+// wins); this file is the app-wide fallback.
+import { html } from '@webjsdev/core';
+
+export default function GlobalNotFound() {
+  return html`
+    <main class="mx-auto max-w-[40rem] px-6 py-24 text-center">
+      <p class="text-sm font-semibold uppercase tracking-wide text-orange-500">404</p>
+      <h1 class="mt-2 text-3xl font-bold">Page not found</h1>
+      <p class="mt-4 text-neutral-500">We could not find the page you were looking for.</p>
+      <a href="/" class="mt-8 inline-block rounded-md bg-neutral-900 px-4 py-2 text-white transition-colors hover:bg-neutral-700 dark:bg-white dark:text-neutral-900 dark:hover:bg-neutral-200">Back to home</a>
+    </main>
+  `;
+}

package/templates/gallery/app/icon.ts

@@ -0,0 +1,19 @@
+// webjs-scaffold-placeholder. Metadata route. Keep and adapt it, or prune it
+// (delete this file), then delete this marker line. webjs check fails while the
+// marker remains.
+//
+// app/icon.ts serves /icon (the dynamic favicon). The default export is a
+// (possibly async) server function; returning a Response lets you set the exact
+// content type, so an inline SVG needs no asset file. For a favicon that never
+// changes, put a static file in public/ instead (e.g. public/favicon.ico) and
+// delete this route. Generate it dynamically (per-theme, per-tenant) when the
+// mark must be computed at request time.
+export default function Icon() {
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32">
+    <rect width="32" height="32" rx="7" fill="#1c1613"/>
+    <text x="16" y="22" font-family="system-ui, sans-serif" font-size="18" font-weight="700" fill="#ff8a3d" 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/opengraph-image.ts

@@ -0,0 +1,20 @@
+// webjs-scaffold-placeholder. Metadata route. Keep and adapt it, or prune it
+// (delete this file), then delete this marker line. webjs check fails while the
+// marker remains.
+//
+// app/opengraph-image.ts serves /opengraph-image (the preview card social
+// platforms show when the site is shared). The Open Graph spec wants 1200x630.
+// Returning a Response with an inline SVG keeps this buildless; for per-page
+// previews, read the request in a nested static segment's opengraph-image.ts
+// and compose the title in. Reference it from metadata via
+// `openGraph: { images: ['/opengraph-image'] }`.
+export default function OpengraphImage() {
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630" viewBox="0 0 1200 630">
+    <rect width="1200" height="630" fill="#1c1613"/>
+    <text x="80" y="330" font-family="system-ui, sans-serif" font-size="88" font-weight="700" fill="#f5f0eb">My App</text>
+    <text x="80" y="410" font-family="system-ui, sans-serif" font-size="36" fill="#ff8a3d">Build on the platform, not against it</text>
+  </svg>`;
+  return new Response(svg, {
+    headers: { 'content-type': 'image/svg+xml', 'cache-control': 'public, max-age=3600' },
+  });
+}

package/templates/gallery/app/sitemaps/route.ts

@@ -0,0 +1,17 @@
+// A sitemap INDEX: for a large site split across several sitemaps, this points
+// crawlers at each child sitemap. `sitemapIndex(sitemaps)` (from @webjsdev/server)
+// serializes the spec-valid <sitemapindex> XML, the counterpart of `sitemap(entries)`
+// in app/sitemap.ts (the single-file case). A route.ts serves it at /sitemaps;
+// in a real app the children would be sharded (posts, products, ...).
+import { sitemapIndex } from '@webjsdev/server';
+
+const SITE_URL = (process.env.SITE_URL || 'http://localhost:8080').replace(/\/$/, '');
+
+export async function GET() {
+  return new Response(
+    sitemapIndex([
+      { url: `${SITE_URL}/sitemap.xml` },
+    ]),
+    { headers: { 'content-type': 'application/xml; charset=utf-8' } },
+  );
+}

package/templates/gallery/app/twitter-image.ts

@@ -0,0 +1,19 @@
+// webjs-scaffold-placeholder. Metadata route. Keep and adapt it, or prune it
+// (delete this file), then delete this marker line. webjs check fails while the
+// marker remains.
+//
+// app/twitter-image.ts serves /twitter-image (the card image shown when the
+// site is shared on Twitter/X). Its own route so the Twitter card can differ
+// from the Open Graph image (opengraph-image.ts); when they are identical, drop
+// this file and let the OG image cover both. A `summary_large_image` card wants
+// roughly 1200x630. Reference it via metadata `twitter: { images: [...] }`.
+export default function TwitterImage() {
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630" viewBox="0 0 1200 630">
+    <rect width="1200" height="630" fill="#1c1613"/>
+    <text x="80" y="330" font-family="system-ui, sans-serif" font-size="88" font-weight="700" fill="#f5f0eb">My App</text>
+    <text x="80" y="410" font-family="system-ui, sans-serif" font-size="36" fill="#ff8a3d">Build on the platform, not against it</text>
+  </svg>`;
+  return new Response(svg, {
+    headers: { 'content-type': 'image/svg+xml', 'cache-control': 'public, max-age=3600' },
+  });
+}

package/templates/gallery/modules/caching/actions/bust-caches.server.ts

@@ -0,0 +1,25 @@
+'use server';
+// A mutation that evicts cached reads. After you change data, call the narrowest
+// revalidate that covers the change so the next request refetches instead of
+// serving a stale cache() result or a revalidate-cached page. (A configured
+// action already runs its declared `invalidates` tags automatically; these are
+// the same helpers, callable directly when you need finer control.)
+import { revalidateTag, revalidateTags, revalidatePath, revalidateAll, getStore, memoryStore } from '@webjsdev/server';
+
+export async function bustCaches(scope: 'tags' | 'path' | 'all' = 'tags') {
+  // getStore() is the store cache() reads from (a memoryStore() in dev, a
+  // redisStore() in prod via setStore()); fall back to a fresh in-memory one.
+  const active = getStore();
+  const store = active ?? memoryStore();
+
+  // Evict only what changed. Pick the narrowest scope that covers the mutation.
+  if (scope === 'all') {
+    revalidateAll(); // nuclear: drop the whole store
+  } else if (scope === 'path') {
+    revalidatePath('/features/caching'); // one revalidate-cached page URL
+  } else {
+    revalidateTag('todos'); // one cache() tag
+    revalidateTags(['todos', 'user:me']); // several tags at once
+  }
+  return { success: true as const, data: { evicted: scope, store: store === active ? 'active' : 'memory' } };
+}

package/templates/gallery/modules/caching/components/cache-buster.ts

@@ -0,0 +1,30 @@
+// A button that calls the bustCaches() server action (imported as a typed RPC
+// stub). Client-only interactivity, so it lives in a component; with JS off the
+// button is inert (cache eviction there happens as a side effect of the write
+// action that changed the data).
+import { WebComponent, signal, html } from '@webjsdev/core';
+import { bustCaches } from '#modules/caching/actions/bust-caches.server.ts';
+
+export class CacheBuster extends WebComponent {
+  private status = signal('');
+
+  private async bust() {
+    this.status.set('evicting…');
+    // 'path' evicts THIS page's cached HTML (revalidatePath), so a refresh
+    // re-renders with a fresh timestamp even inside the 10s window. 'tags' would
+    // only evict cache() query results, which this page does not use.
+    const result = await bustCaches('path');
+    this.status.set(result.success ? 'evicted, now refresh the page' : 'failed');
+  }
+
+  render() {
+    return html`
+      <div class="flex items-center gap-3 text-[15px]">
+        <button @click=${() => this.bust()}
+          class="px-3.5 py-1.5 rounded-xl bg-card border border-border text-foreground text-sm cursor-pointer transition-colors hover:border-border-strong">revalidate this page</button>
+        <span class="text-muted-foreground">${this.status.get()}</span>
+      </div>
+    `;
+  }
+}
+CacheBuster.register('cache-buster');

package/templates/gallery/modules/client-router/components/router-controls.ts

@@ -1,22 +1,50 @@
 // Programmatic client navigation. `navigate(url)` does the same soft, in-place
 // swap an <a> click does, but from an event handler (after a save, a wizard
 // step, etc.). `revalidate(url?)` evicts the browser snapshot cache so the next
-// visit refetches fresh HTML instead of the cached page. Both are client-only
-// (they run in the browser), so a component is the right home; a page/layout
-// never hydrates. With JS off this component is inert, so keep real navigation
-// on plain <a href> and use navigate() only for JS-driven flows.
-import { WebComponent, html, navigate, revalidate } from '@webjsdev/core';
+// visit refetches fresh HTML instead of the cached page. `disableClientRouter()`
+// / `enableClientRouter()` turn soft navigation off / back on at runtime (for a
+// moment where you want a full page load, e.g. handing off to a third-party
+// flow). disableClientRouter() removes the document-level <a>/<form> click
+// interception, so PLAIN links start doing full page loads again. It does NOT
+// affect navigate(), which is an explicit programmatic swap the toggle never
+// intercepts, so the plain link below is what visibly changes when you toggle.
+// All are client-only (they run in the browser), so a component is the right
+// home; a page/layout never hydrates. With JS off the plain link still works
+// (progressive enhancement), while the buttons are inert.
+import { WebComponent, html, signal, navigate, revalidate, disableClientRouter, enableClientRouter } from '@webjsdev/core';
 
 export class RouterControls extends WebComponent {
+  // Instance signal mirroring whether soft navigation is currently on.
+  private soft = signal(true);
+
+  private toggleRouter() {
+    if (this.soft.get()) disableClientRouter();
+    else enableClientRouter();
+    this.soft.set(!this.soft.get());
+  }
+
   render() {
+    const soft = this.soft.get();
     return html`
-      <div class="flex gap-3 items-center">
-        <button
-          @click=${() => navigate('/features/client-router/second')}
-          class="inline-flex items-center px-4 py-2 rounded-xl bg-card border border-border text-foreground font-medium text-sm cursor-pointer transition-colors hover:border-border-strong">navigate() to page two</button>
-        <button
-          @click=${() => revalidate()}
-          class="text-muted-foreground font-medium text-sm cursor-pointer transition-colors hover:text-foreground underline decoration-dotted underline-offset-4">revalidate() the snapshot cache</button>
+      <div class="grid gap-3">
+        <div class="flex flex-wrap gap-3 items-center">
+          <button
+            @click=${() => navigate('/features/client-router/second')}
+            class="inline-flex items-center px-4 py-2 rounded-xl bg-card border border-border text-foreground font-medium text-sm cursor-pointer transition-colors hover:border-border-strong">navigate() to page two</button>
+          <button
+            @click=${() => revalidate()}
+            class="text-muted-foreground font-medium text-sm cursor-pointer transition-colors hover:text-foreground underline decoration-dotted underline-offset-4">revalidate() the snapshot cache</button>
+          <button
+            @click=${() => this.toggleRouter()}
+            class="text-muted-foreground font-medium text-sm cursor-pointer transition-colors hover:text-foreground underline decoration-dotted underline-offset-4">${soft ? 'disableClientRouter()' : 'enableClientRouter()'} (soft nav: ${soft ? 'on' : 'off'})</button>
+        </div>
+        <p class="text-sm text-muted-foreground">
+          Plain link:
+          <a href="/features/client-router/second" class="text-primary underline">/features/client-router/second</a>.
+          ${soft
+            ? html`The router is on, so this soft-navigates (no full reload). Toggle it off, then click again to watch the browser do a full page load.`
+            : html`The router is off, so this now does a FULL page load. The navigate() button still soft-navigates (it is explicit and ignores the toggle).`}
+        </p>
       </div>
     `;
   }

package/templates/gallery/modules/components/components/browser/counter-card.test.js

@@ -9,7 +9,7 @@
 //     REAL SSR output and the client interactivity, not a jsdom approximation.
 // It lives NEXT TO the component (a `browser/` dir inside the module), the
 // co-located default; the runner discovers browser tests under any browser dir.
-import { html } from '@webjsdev/core';
+import { html, render } from '@webjsdev/core';
 import { ssrFixture } from '@webjsdev/core/testing';
 import '../counter-card.ts';
 
@@ -22,6 +22,26 @@ suite('<counter-card>', () => {
     assert(el.textContent.includes('Clicks'), 'the default label renders');
   });
 
+  test('render() mounts a template imperatively into a container', async () => {
+    // render(value, container) is the client-side imperative render: mount a
+    // WebJs template into any DOM node (a portal, a plain page). Components
+    // render themselves, so reach for this only when you need to drive the
+    // mount point yourself. The container must be CONNECTED to the document, or
+    // the custom element never upgrades (connectedCallback, and so its first
+    // render, only fire on connection).
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    try {
+      render(html`<counter-card label="Imperative"></counter-card>`, container);
+      const el = container.querySelector('counter-card');
+      assert(el, 'the element mounts into the container');
+      await el.updateComplete; // wait for the component's first client render
+      assert(container.textContent.includes('Imperative'), 'the label renders');
+    } finally {
+      container.remove();
+    }
+  });
+
   test('reads the label reactive prop', async () => {
     const el = await ssrFixture(html`<counter-card label="Taps"></counter-card>`);
     assert(el.textContent.includes('Taps'), 'the provided label renders');

package/templates/gallery/modules/components/components/server-render.test.ts

@@ -0,0 +1,20 @@
+// A node unit test (webjs test --server): `renderToString` server-renders an
+// html`` template to a string, with Declarative Shadow DOM for shadow-DOM
+// components. Import it from `@webjsdev/core/server` (NOT the root), so the test
+// stays explicit about which side it runs on. Use it to assert SSR output and
+// escaping without a browser; for a full request through the pipeline, use the
+// handle() harness from @webjsdev/server/testing instead (see the testing docs).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { html } from '@webjsdev/core';
+import { renderToString } from '@webjsdev/core/server';
+
+test('renderToString renders interpolated text and escapes it', async () => {
+  const out = await renderToString(html`<p>${'hello'}</p>`);
+  assert.match(out, /hello/);
+});
+
+test('renderToString escapes an interpolated angle bracket (no injection)', async () => {
+  const out = await renderToString(html`<p>${'<script>'}</p>`);
+  assert.doesNotMatch(out, /<script>/);
+});

package/templates/gallery/modules/components/components/task-loader.ts

@@ -0,0 +1,48 @@
+// `Task` runs an async function and exposes its state (via `TaskStatus`:
+// INITIAL / PENDING / COMPLETE / ERROR) so render() can show a spinner, the
+// value, or an error without hand-rolling the bookkeeping. Use it for
+// genuinely CLIENT-only async data (a browser-driven fetch, a retry-on-click
+// load). For request-time server data that should be in the first paint, prefer
+// `async render()` instead, which blocks SSR so the data is server-rendered;
+// a Task shows its PENDING state at SSR, so the value is not in the first paint.
+import { WebComponent, html } from '@webjsdev/core';
+import { Task, TaskStatus } from '@webjsdev/core/task';
+
+export class TaskLoader extends WebComponent {
+  // Bumped on each reload so args change and the task re-runs.
+  private attempt = 0;
+
+  // Task calls task(...args(), { signal }), so the args() array is SPREAD into
+  // positional parameters (not passed as one array). One arg here, so read it
+  // directly as `attempt`.
+  private task = new Task<string>(this, {
+    task: async (attempt: number) => {
+      await new Promise((r) => setTimeout(r, 600));
+      if (attempt % 3 === 2) throw new Error('unlucky attempt');
+      return `loaded on attempt #${attempt}`;
+    },
+    args: () => [this.attempt],
+  });
+
+  private reload() {
+    this.attempt += 1;
+    this.task.run();
+  }
+
+  render() {
+    const t = this.task;
+    const body =
+      t.status === TaskStatus.PENDING ? html`<span class="text-muted-foreground">loading…</span>`
+      : t.status === TaskStatus.ERROR ? html`<span class="text-red-500">error: ${String((t.error as Error)?.message ?? t.error)}</span>`
+      : t.status === TaskStatus.COMPLETE ? html`<span class="text-foreground">${t.value}</span>`
+      : html`<span class="text-muted-foreground">idle</span>`;
+    return html`
+      <div class="flex items-center gap-3 text-[15px]">
+        <button @click=${() => this.reload()}
+          class="px-3.5 py-1.5 rounded-xl bg-card border border-border text-foreground text-sm cursor-pointer transition-colors hover:border-border-strong">reload</button>
+        ${body}
+      </div>
+    `;
+  }
+}
+TaskLoader.register('task-loader');

package/templates/gallery/modules/components/components/theme-context.ts

@@ -0,0 +1,67 @@
+// The context API: pass a value down to descendant components WITHOUT threading
+// it through every level as an attribute. `createContext(name)` mints a typed
+// key; a `ContextProvider` on an ancestor holds the value; a `ContextConsumer`
+// on any descendant reads it (and, with `subscribe: true`, re-renders when it
+// changes). Under the hood a consumer dispatches a `ContextRequestEvent` that
+// bubbles up to the nearest provider, which is the low-level protocol the two
+// controllers automate. All light DOM, so the provider's <slot> projects its
+// children normally.
+import { WebComponent, html, signal } from '@webjsdev/core';
+import { createContext, ContextProvider, ContextConsumer, ContextRequestEvent } from '@webjsdev/core/context';
+
+type Theme = 'light' | 'dark';
+
+// One shared key. Descendants that read `themeContext` get the provider's value.
+export const themeContext = createContext<Theme>('demo-theme');
+
+export class ThemeProvider extends WebComponent {
+  // The provider holds the value. setValue() pushes it to every subscribing
+  // consumer in one shot.
+  private provider = new ContextProvider<Theme>(this, { context: themeContext, initialValue: 'light' });
+
+  private toggle() {
+    this.provider.setValue(this.provider.value === 'light' ? 'dark' : 'light');
+    this.requestUpdate(); // re-render the provider's own button label too
+  }
+
+  render() {
+    return html`
+      <div class="grid gap-3 p-3 rounded-xl bg-card border border-border max-w-[420px]">
+        <button @click=${() => this.toggle()}
+          class="w-fit 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]">
+          provider theme: ${this.provider.value} (toggle)
+        </button>
+        <slot></slot>
+      </div>
+    `;
+  }
+}
+ThemeProvider.register('theme-provider');
+
+export class ThemeConsumer extends WebComponent {
+  // subscribe: true re-renders this element whenever the provider calls setValue.
+  private consumer = new ContextConsumer<Theme>(this, { context: themeContext, subscribe: true });
+  private lastRead = signal<Theme | 'not read yet'>('not read yet');
+
+  // The imperative escape hatch: dispatch a ContextRequestEvent yourself to
+  // grab the current value ONCE without subscribing. It bubbles up to the
+  // nearest provider, which answers via the callback.
+  private readOnce() {
+    this.dispatchEvent(
+      new ContextRequestEvent<Theme>(themeContext, (value) => this.lastRead.set(value), false),
+    );
+  }
+
+  render() {
+    const theme = this.consumer.value ?? 'light';
+    return html`
+      <div class="flex items-center gap-3 text-[15px] text-foreground">
+        <span>child sees: <strong>${theme}</strong></span>
+        <button @click=${() => this.readOnce()}
+          class="px-3 py-1 rounded-lg text-sm bg-card border border-border text-foreground cursor-pointer transition-colors hover:border-border-strong">read once</button>
+        <span class="text-muted-foreground text-sm">last one-shot: ${this.lastRead.get()}</span>
+      </div>
+    `;
+  }
+}
+ThemeConsumer.register('theme-consumer');

package/templates/gallery/modules/directives/components/directive-demo.ts

@@ -1,4 +1,4 @@
-// The lit-html directive set webjs re-exports (from '@webjsdev/core/directives').
+// The lit-html directive set WebJs re-exports (from '@webjsdev/core/directives').
 // `repeat` keys a list so DOM nodes are REUSED across reorders instead of being
 // recreated (use it for keyed lists that reorder; plain `.map()` is fine for
 // static lists). `watch(signal)` does a fine-grained DOM swap of ONE node when
@@ -6,9 +6,13 @@
 // shows more of the set: `live` (a controlled input), `ref` + `createRef` (a
 // handle to a DOM node), `until` (a pending fallback for a promise),
 // `unsafeHTML` (trusted raw HTML, NEVER user input), and `keyed` (force a fresh
-// subtree when a key changes).
+// subtree when a key changes). The third card shows the rest: `guard` (skip a
+// re-render when its deps are unchanged), `cache` (keep an inactive branch's
+// DOM around while you toggle), `templateContent` (stamp an existing template's
+// HTML), and `asyncAppend` / `asyncReplace` (stream values from an async
+// iterable, appending each or replacing with the latest).
 import { WebComponent, signal, html } from '@webjsdev/core';
-import { repeat, watch, live, until, keyed, unsafeHTML, ref, createRef } from '@webjsdev/core/directives';
+import { repeat, watch, live, until, keyed, unsafeHTML, ref, createRef, guard, cache, templateContent, asyncAppend, asyncReplace } from '@webjsdev/core/directives';
 
 interface Item { id: number; label: string }
 
@@ -29,6 +33,57 @@ export class DirectiveDemo extends WebComponent {
   // Created ONCE (not per render), so `until` keeps the resolved value across
   // re-renders instead of flashing back to the fallback each time.
   private asyncValue: Promise<string> = this.later();
+  // Which cached branch is showing (for `cache`), and a counter that lets us
+  // prove `guard` skips its recompute unless its dep actually changes.
+  private tab = signal<'a' | 'b'>('a');
+  private guardBumps = signal(0);
+  // Async iterables consumed on the client (both render empty at SSR). The
+  // generators are lazy, so the field initializer just creates the iterator
+  // without running the body. Both are FINITE and run ONCE: they animate on
+  // first paint, then settle on their final value. restartStreams() swaps in
+  // fresh iterables to replay them (a new iterable identity makes asyncAppend /
+  // asyncReplace tear down and re-subscribe). streamRun is read in render() so
+  // the swap triggers a re-render.
+  private logIter: AsyncIterable<string> = this.log();
+  private countIter: AsyncIterable<number> = this.countdown();
+  private streamRun = signal(0);
+
+  private restartStreams() {
+    this.logIter = this.log();
+    this.countIter = this.countdown();
+    this.streamRun.set(this.streamRun.get() + 1);
+  }
+  // For `templateContent`: a real <template> element on the CLIENT (the client
+  // directive clones its `.content`), and a plain { innerHTML } object at SSR
+  // (there is no document to build a template with, and the server directive
+  // emits innerHTML directly). The real template is built in connectedCallback,
+  // which SSR never calls, so the two paths agree on the output.
+  private stampTpl: HTMLTemplateElement | { innerHTML: string } = {
+    innerHTML: '<strong>stamped</strong> from a template',
+  };
+
+  connectedCallback() {
+    super.connectedCallback();
+    const tpl = document.createElement('template');
+    tpl.innerHTML = '<strong>stamped</strong> from a template';
+    this.stampTpl = tpl;
+  }
+
+  // A finite async iterable: asyncAppend adds each line as it arrives.
+  private async *log(): AsyncGenerator<string> {
+    for (const line of ['connecting', 'authenticated', 'ready']) {
+      await new Promise((r) => setTimeout(r, 500));
+      yield line;
+    }
+  }
+  // A finite async iterable: asyncReplace shows only the latest value, counting
+  // down 5 -> 0 one step at a time.
+  private async *countdown(): AsyncGenerator<number> {
+    for (let n = 5; n >= 0; n--) {
+      yield n;
+      await new Promise((r) => setTimeout(r, 500));
+    }
+  }
 
   private reverse() {
     this.items.set(this.items.get().slice().reverse());
@@ -91,6 +146,48 @@ export class DirectiveDemo extends WebComponent {
             class="w-fit text-sm text-muted-foreground cursor-pointer transition-colors hover:text-foreground underline decoration-dotted underline-offset-4">rekey</button>
           ${keyed(variant, html`<div class="text-[15px] text-foreground">${unsafeHTML('<em>fresh subtree</em>')} #${variant}</div>`)}
         </div>
+
+        <div class="grid gap-3 border-t border-border pt-4">
+          <!-- guard([deps], fn) only re-runs fn when a dep changes. Bumping the
+               guard counter re-renders it; the OTHER counter (ticks above) does
+               not, so the guarded value stays put. -->
+          <button @click=${() => this.guardBumps.set(this.guardBumps.get() + 1)}
+            class="w-fit text-sm text-muted-foreground cursor-pointer transition-colors hover:text-foreground underline decoration-dotted underline-offset-4">bump guard dep</button>
+          <p class="text-sm text-foreground">guarded: ${guard([this.guardBumps.get()], () => html`computed at bump #${this.guardBumps.get()}`)}</p>
+
+          <!-- cache(value) keeps the inactive tab's DOM alive while you toggle,
+               so switching back is instant and preserves any element state. -->
+          <div class="flex gap-2">
+            <button @click=${() => this.tab.set('a')}
+              class="px-3 py-1 rounded-lg text-sm border cursor-pointer transition-colors ${this.tab.get() === 'a' ? 'bg-primary text-primary-foreground border-transparent' : 'bg-card border-border text-foreground hover:border-border-strong'}">Tab A</button>
+            <button @click=${() => this.tab.set('b')}
+              class="px-3 py-1 rounded-lg text-sm border cursor-pointer transition-colors ${this.tab.get() === 'b' ? 'bg-primary text-primary-foreground border-transparent' : 'bg-card border-border text-foreground hover:border-border-strong'}">Tab B</button>
+          </div>
+          <div class="text-[15px] text-foreground">${cache(
+            this.tab.get() === 'a'
+              ? html`<span>Panel A content</span>`
+              : html`<span>Panel B content</span>`,
+          )}</div>
+
+          <!-- templateContent stamps a <template> element's content (see
+               stampTpl: a real template on the client, a plain { innerHTML } at
+               SSR, so first paint and hydration match). -->
+          <div class="text-[15px] text-foreground">${templateContent(this.stampTpl)}</div>
+
+          <!-- asyncAppend appends each value from an async iterable as it
+               arrives; asyncReplace shows only the latest. Both render empty at
+               SSR, stream in on the client, and finish (the log stops at
+               "ready", the countdown at 0). Restart swaps in fresh iterables so
+               you can watch them replay. The run counter forces the re-render. -->
+          <div class="flex items-center gap-3">
+            <button @click=${() => this.restartStreams()}
+              class="w-fit px-3.5 py-1.5 rounded-xl bg-card border border-border text-foreground text-sm cursor-pointer transition-colors hover:border-border-strong">restart streams</button>
+            <span class="text-sm text-muted-foreground">run #${this.streamRun.get()}</span>
+          </div>
+          <div class="text-sm text-muted-foreground">log (asyncAppend, one row per value):</div>
+          <ul class="grid gap-1 list-none m-0 p-0 text-sm text-muted-foreground min-h-[1.25rem]">${asyncAppend(this.logIter, (line: string) => html`<li>· ${line}</li>`)}</ul>
+          <p class="text-sm text-foreground">countdown (asyncReplace, latest value only): ${asyncReplace(this.countIter)}</p>
+        </div>
       </div>
     `;
   }

package/templates/gallery/modules/file-storage/actions/store-upload.server.ts

@@ -7,6 +7,9 @@
 // whitelisted extension.
 'use server';
 import { getFileStore, generateKey } from '@webjsdev/server';
+// Importing the config module runs setFileStore(diskStore(...)) once at load,
+// so uploads land in the configured store. See ../store.server.ts.
+import '../store.server.ts';
 
 export async function storeUpload(file: File) {
   if (!(file instanceof File) || file.size === 0) {

package/templates/gallery/modules/file-storage/store.server.ts

@@ -0,0 +1,29 @@
+// Server-only file-store configuration (no 'use server': a plain server
+// utility, imported by the upload action and the serve route). `setFileStore()`
+// swaps the active store; `diskStore()` is the built-in local-disk store
+// (streaming, traversal-safe), the drop-in slot for an S3 / R2 / GCS adapter of
+// the same shape. `signedUrl(key, { secret })` mints a time-limited,
+// tamper-proof download URL and `verifySignedUrl(input, secret)` checks it, so a
+// private file can be shared by link without making the serve route public.
+import { setFileStore, diskStore, signedUrl, verifySignedUrl } from '@webjsdev/server';
+
+// Configure the store once at module load. This mirrors the framework default
+// (a local diskStore under .webjs/uploads); in production swap diskStore for an
+// S3/R2 adapter with the same put/get/delete shape.
+setFileStore(diskStore({ dir: '.webjs/uploads' }));
+
+const URL_SECRET = process.env.FILE_URL_SECRET || 'dev-file-url-secret-change-me';
+
+// A 1-hour signed link to the serve route for a given key.
+export function signedDownloadUrl(key: string): string {
+  return signedUrl(key, {
+    secret: URL_SECRET,
+    base: `/features/file-storage/file/${encodeURIComponent(key)}`,
+    expiresIn: 3600,
+  });
+}
+
+// True when a request's ?key&exp&sig params are a valid, unexpired signature.
+export function isValidSignedRequest(url: string): boolean {
+  return verifySignedUrl(url, URL_SECRET).valid;
+}

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

@@ -0,0 +1,31 @@
+// `richFetch(url, init?)` is a drop-in `fetch` for your own API routes that
+// preserves rich types: it sends Accept: application/vnd.webjs+json, and when
+// the route answered with `json(...)` it decodes the WebJs wire, so a `Date`
+// comes back as a real Date (not an ISO string), and Map / Set / BigInt / Blob
+// round-trip too. A plain-object `body` is encoded the same way. Client-only
+// (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';
+
+interface RichPayload { at: Date; ip: string; requestId: string; cookieCount: number }
+
+export class RichData extends WebComponent {
+  private line = signal('click to fetch');
+
+  private async load() {
+    const data = await richFetch<RichPayload>('/features/route-handler/data');
+    // data.at is a Date, so Date methods work with no manual parsing.
+    this.line.set(`at ${data.at.toLocaleTimeString()} · id ${data.requestId} · ${data.cookieCount} cookie(s)`);
+  }
+
+  render() {
+    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>
+        <span class="text-muted-foreground">${this.line.get()}</span>
+      </div>
+    `;
+  }
+}
+RichData.register('rich-data');

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

@@ -3,10 +3,18 @@
 // stub POSTing to the server. It may use server-only utilities (they run here,
 // server-side), which is why the util above stays off the client.
 import { shout } from '../utils/format.server.ts';
+import { actionContext, actionSignal } from '@webjsdev/server';
 import type { ActionResult } from '@webjsdev/server';
 
 export async function greet(input: { name: string }): Promise<ActionResult<{ message: string }>> {
-  const name = String(input?.name ?? '').trim();
+  // actionSignal() is the request's AbortSignal (fires on client disconnect or a
+  // superseded render); bail early on long work instead of finishing wasted work.
+  if (actionSignal().aborted) return { success: false, error: 'Request cancelled.', status: 499 };
+  // actionContext() is the per-action middleware context (e.g. actionContext().user
+  // set by an auth middleware via `export const middleware`). Empty here, no middleware.
+  const who = (actionContext().user as { name?: string } | undefined)?.name;
+
+  const name = String(input?.name ?? who ?? '').trim();
   if (!name) return { success: false, error: 'Name required.', status: 400 };
   return { success: true, data: { message: shout('hello ' + name) } };
 }

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

@@ -0,0 +1,37 @@
+// 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.
+// buildRouteTable(appDir) parses the file router; matchPage / matchApi resolve a
+// URL against it, params included. See the testing docs.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequestHandler, buildRouteTable, matchPage, matchApi, rawActionRequest } from '@webjsdev/server';
+
+const appDir = process.cwd();
+
+test('buildRouteTable + matchPage resolve a dynamic route with its params', async () => {
+  const table = await buildRouteTable(appDir);
+  const m = matchPage(table, '/features/routing/42');
+  assert.ok(m, 'the [id] route matches');
+  assert.equal(m.params.id, '42');
+});
+
+test('matchApi resolves the route-handler endpoint', async () => {
+  const table = await buildRouteTable(appDir);
+  const m = matchApi(table, '/features/route-handler/data');
+  assert.ok(m, 'the route.ts endpoint matches');
+});
+
+test('rawActionRequest fires the greet action through the pipeline', 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);
+});

package/templates/gallery/modules/sessions/session-config.server.ts

@@ -0,0 +1,31 @@
+// The session helpers. `session(opts)` builds session MIDDLEWARE; its storage is
+// pluggable. `cookieSessionStorage()` (alias `cookieSession`) keeps the whole
+// session in a signed cookie (stateless, the default). `storeSessionStorage()`
+// (alias `storeSession`) persists the session in the active store (memoryStore
+// in dev, Redis in prod via setStore()) and keeps only an id in the cookie, for
+// larger or server-held sessions. `getSession(req)` reads the current session
+// inside a route or middleware the session wraps.
+import { session, getSession, cookieSession, cookieSessionStorage, storeSession, storeSessionStorage } from '@webjsdev/server';
+
+// A dev fallback keeps a fresh scaffold booting; set SESSION_SECRET in .env for
+// any real deployment (and fail fast in production).
+const trimmed = process.env.SESSION_SECRET?.trim();
+if (process.env.NODE_ENV === 'production' && !trimmed) {
+  throw new Error('SESSION_SECRET must be set in production');
+}
+const secret = trimmed || 'dev-insecure-session-secret-change-me';
+
+// Cookie-backed session middleware (all state in a signed cookie): the default
+// this demo applies. cookieSession() is the alias for cookieSessionStorage().
+export const cookieSessions = session({ secret, storage: cookieSession() });
+
+// Store-backed alternative (session in the active store, id in the cookie).
+// storeSession() is the alias for storeSessionStorage(); swap it in above for
+// larger sessions. Kept here to show both strategies.
+export const storeSessions = session({ secret, storage: storeSession() });
+
+// Equivalent explicit spellings (the aliases just name the storage factories):
+export const cookieStorageExplicit = cookieSessionStorage();
+export const storeStorageExplicit = storeSessionStorage();
+
+export { getSession };

package/templates/gallery/modules/websockets/components/ws-echo.ts

@@ -4,7 +4,7 @@
 // it never runs during SSR) and closed in disconnectedCallback. At SSR the
 // component renders its disconnected state, so with JS off the page still reads
 // (a live socket has no no-JS equivalent, which is the honest fallback here).
-import { WebComponent, signal, html, connectWS } from '@webjsdev/core';
+import { WebComponent, signal, html, connectWS, renderStream } from '@webjsdev/core';
 
 export class WsEcho extends WebComponent {
   private connected = signal(false);
@@ -36,6 +36,19 @@ export class WsEcho extends WebComponent {
     input.value = '';
   }
 
+  #streamN = 0;
+  // renderStream() applies a <webjs-stream> payload with native DOM methods:
+  // the SAME element-level applier a connectWS onMessage handler (or a
+  // broadcast() push) uses for surgical live updates, so a chat / presence /
+  // toast reuses it instead of hand-written DOM code. Here a button drives it
+  // locally; over a channel the server would send this HTML string.
+  private applyStreamUpdate() {
+    this.#streamN += 1;
+    renderStream(
+      `<webjs-stream action="append" target="ws-stream-log"><template><li class="px-3 py-2 rounded-xl bg-card border border-border text-[15px] text-foreground">streamed row #${this.#streamN}</li></template></webjs-stream>`,
+    );
+  }
+
   render() {
     const on = this.connected.get();
     return html`
@@ -55,6 +68,11 @@ export class WsEcho extends WebComponent {
             <li class="px-3 py-2 rounded-xl bg-card border border-border text-[15px] text-foreground font-mono">${line}</li>
           `)}
         </ul>
+        <div class="grid gap-2 border-t border-border pt-4">
+          <button @click=${() => this.applyStreamUpdate()}
+            class="w-fit px-3.5 py-1.5 rounded-xl bg-card border border-border text-foreground text-sm cursor-pointer transition-colors hover:border-border-strong">renderStream() an element-level update</button>
+          <ul id="ws-stream-log" class="grid gap-1.5 list-none m-0 p-0"></ul>
+        </div>
       </div>
     `;
   }

package/templates/gallery/modules/websockets/echo.test.ts

@@ -0,0 +1,21 @@
+// Example node test for booting the app in-process (from @webjsdev/server).
+// startServer({ appDir, port }) boots the whole app and resolves to
+// { server, close } (the same entry `webjs start` uses; port 0 picks a free
+// port, so a test never collides). Close it in a finally so the port is
+// released. This is the realistic way to smoke-test that the app boots and
+// listens; for asserting on responses without a socket, use the handle()
+// harness (see modules/server-actions/actions/greet.test.ts and the docs).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { startServer } from '@webjsdev/server';
+
+const appDir = process.cwd();
+
+test('startServer boots the app in-process on an ephemeral port', async () => {
+  const { server, close } = await startServer({ appDir, dev: true, port: 0 });
+  try {
+    assert.ok(server.address(), 'the server is listening');
+  } finally {
+    await close();
+  }
+});

package/templates/instrumentation.ts

@@ -0,0 +1,16 @@
+// Optional boot-time hook (app root, sibling of app/). register() runs once at
+// server start, the place to wire APM / logging / tracing. setOnError(fn) (from
+// @webjsdev/server) registers a sink for every request error the framework
+// catches (an SSR render crash, a thrown server action, a 500), so you can
+// forward it to Sentry / a logger with the request context. Call setOnError
+// INSIDE register() so it runs within the instrumentation context (a top-level
+// call has no context yet and is a no-op). Delete this file if you do not need
+// the hook.
+import { setOnError } from '@webjsdev/server';
+
+export function register() {
+  setOnError((error, ctx) => {
+    // Replace with your APM. `ctx` carries request context (e.g. a correlation id).
+    console.error('[instrumentation] request error:', error, ctx ?? '');
+  });
+}