@webjsdev/cli 0.10.36 → 0.10.38

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,8 +110,18 @@ 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,",
+    "  // A failed credentials sign-in 302s to `${pages.error}?error=CredentialsSignin`.",
+    "  // Point it at /login so app/login/page.ts reads searchParams.error and shows a",
+    "  // message, instead of the createAuth default (the home page) swallowing the error.",
+    "  pages: { error: '/login' },",
     "});",
     "",
   ].join('\n'));
@@ -333,7 +343,17 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "",
     "export const metadata = { title: 'Login' };",
     "",
-    "export default function LoginPage() {",
+    "// A failed sign-in 302s back here with ?error=... (createAuth is configured",
+    "// with pages.error: '/login' in lib/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-sm mx-auto mt-12\">",
     "      <div class=${cardClass()}>",
@@ -342,6 +362,7 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "          <p class=${cardDescriptionClass()}>Welcome back: log in to continue.</p>",
     "        </div>",
     "        <div class=${cardContentClass()}>",
+    "          ${error ? html`<p role=\"alert\" class=\"mb-4 text-sm text-destructive\">${error}</p>` : ''}",
     "          <form method=\"POST\" action=\"/api/auth/signin/credentials\" class=\"flex flex-col gap-4\">",
     "            <!-- createAuth reads redirectTo from the posted form and 302s there after a successful signin. -->",
     "            <input type=\"hidden\" name=\"redirectTo\" value=\"/dashboard\">",
@@ -455,12 +476,39 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "",
   ].join('\n'));
 
+  // app/dashboard/layout.ts: a thin sub-nav shared by every /dashboard page
+  // (page.ts and settings/page.ts). It carries the logout control so a signed-in
+  // user can end the session from anywhere under /dashboard.
+  await writeFile(join(appDir, 'app', 'dashboard', 'layout.ts'), [
+    "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 (lib/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 /dashboard 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=\"/dashboard\" class=\"text-sm font-medium hover:underline\">Dashboard</a>",
+    "      <a href=\"/dashboard/settings\" class=\"text-sm font-medium hover:underline\">Settings</a>",
+    "      <form method=\"POST\" action=\"/api/auth/signout\" class=\"ml-auto\">",
+    "        <button class=${buttonClass({ variant: 'outline', size: 'sm' })} type=\"submit\">Log out</button>",
+    "      </form>",
+    "    </nav>",
+    "    ${children}",
+    "  `;",
+    "}",
+    "",
+  ].join('\n'));
+
   // app/dashboard/page.ts
   await writeFile(join(appDir, 'app', 'dashboard', 'page.ts'), [
     "import { html } from '@webjsdev/core';",
     "import { currentUser } from '#modules/auth/queries/current-user.server.ts';",
-    "import { cardClass, cardHeaderClass, cardTitleClass, cardDescriptionClass, cardContentClass } from '#components/ui/card.ts';",
-    "import { buttonClass } from '#components/ui/button.ts';",
+    "import { cardClass, cardHeaderClass, cardTitleClass, cardDescriptionClass } from '#components/ui/card.ts';",
     "import { badgeClass } from '#components/ui/badge.ts';",
     "",
     "export const metadata = { title: 'Dashboard' };",
@@ -477,9 +525,6 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "        <h2 class=${cardTitleClass()}>Welcome, ${user?.name || user?.email}!</h2>",
     "        <p class=${cardDescriptionClass()}>You're authenticated. Replace this scaffold with your real app.</p>",
     "      </div>",
-    "      <div class=${cardContentClass()}>",
-    "        <a class=${buttonClass({ variant: 'outline' })} href=\"/dashboard/settings\">Settings</a>",
-    "      </div>",
     "    </div>",
     "  `;",
     "}",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.36",
+  "version": "0.10.38",
   "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');