@webjsdev/cli 0.10.35 → 0.10.37

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

@@ -2,6 +2,9 @@
 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' };
 
@@ -10,5 +13,13 @@ export default function ComponentsExample() {
     <h1 class="text-h2 font-bold mb-4">Components</h1>
     <p class="text-muted-foreground mb-4">The WebComponent factory, a reactive prop, an instance signal, and a slot.</p>
     <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/file-storage/page.ts

@@ -42,7 +42,7 @@ export default function FileStorageExample({
       <code class="font-mono">setFileStore()</code> call, no call-site change.
     </p>
     <form method="post" enctype="multipart/form-data" class="flex flex-wrap gap-3 items-center mb-4">
-      <input type="file" name="file" required
+      <input type="file" name="file" required aria-label="Choose a file to upload"
         class="text-sm text-muted-foreground file:mr-3 file:px-3.5 file:py-2 file:rounded-xl file:border-0 file:bg-card file:border file:border-border file:text-foreground file:text-sm file:cursor-pointer" />
       <button type="submit"
         class="px-4 py-2 rounded-xl bg-primary text-primary-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-primary/90 active:scale-[0.97]">Upload</button>
@@ -54,7 +54,7 @@ export default function FileStorageExample({
       ? html`
         <div class="px-4 py-3 rounded-xl bg-card border border-border text-sm">
           Stored <span class="text-foreground font-medium">${name}</span>
-          <span class="text-muted-foreground/70">(${size} bytes)</span>
+          <span class="text-muted-foreground">(${size} bytes)</span>
           <a class="text-primary no-underline ml-2" href="/features/file-storage/file/${key}">download</a>
         </div>`
       : ''}

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

@@ -26,7 +26,7 @@ const field = (label: string, name: string, input: unknown, error?: string) => h
   </div>
 `;
 
-const inputCls = 'w-full bg-background border border-border rounded-xl px-3 py-2 text-[15px] text-foreground outline-none transition-colors focus:border-primary placeholder:text-muted-foreground/70';
+const inputCls = 'w-full bg-background border border-border rounded-xl px-3 py-2 text-[15px] text-foreground outline-none transition-colors focus:border-primary placeholder:text-muted-foreground';
 
 export default function FormsFeature({ searchParams, actionData }: { searchParams: Record<string, string | undefined>; actionData?: Result }) {
   if (searchParams.sent) {

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/[id]/page.ts

@@ -12,12 +12,16 @@
 // params, so PageProps<'/features/routing/[id]'>['params'] narrows to
 // { id: string } automatically. Rename the folder and the type follows; pass a
 // route literal that does not exist and it is a compile error.
-import { html } from '@webjsdev/core';
+import { html, notFound } from '@webjsdev/core';
 import type { PageProps } from '@webjsdev/core';
 
 export default async function RoutingParam({ params }: PageProps<'/features/routing/[id]'>) {
   // The Next-style await also works; `params.id` sync would be identical.
   const { id } = await params;
+  // Throw notFound() to short-circuit into the nearest not-found boundary (404).
+  // Here the reserved id "missing" stands in for "no such record"; in a real app
+  // you throw this after a DB lookup returns nothing. Try /features/routing/missing.
+  if (id === 'missing') notFound();
   return html`
     <h1 class="text-h2 font-bold mb-4">Route param</h1>
     <p>The <code>[id]</code> segment is: <strong>${id}</strong></p>
@@ -28,6 +32,14 @@ export default async function RoutingParam({ params }: PageProps<'/features/rout
       <code class="font-mono">params</code> is awaitable too:
       <code class="font-mono">const { id } = await params</code> works, same value.
     </p>
+    <p class="text-muted-foreground text-sm mt-3">
+      Throwing wins over rendering: <a class="text-primary" href="/features/routing/missing">/features/routing/missing</a>
+      throws <code class="font-mono">notFound()</code> and renders the nearest
+      not-found boundary at 404. See the
+      <a class="text-primary" href="/features/boundaries">Boundaries</a> demo for
+      <code class="font-mono">forbidden()</code> and
+      <code class="font-mono">unauthorized()</code>.
+    </p>
     <p class="mt-3"><a class="text-primary" href="/features/routing">Back</a></p>
   `;
 }

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
@@ -43,5 +44,13 @@ export default function RoutingExample() {
       <code class="font-mono">redirect()</code> on the server, call
       <code class="font-mono">navigate()</code> on the client.
     </p>
+    <p class="text-muted-foreground text-sm mt-3">
+      A page can also THROW to short-circuit rendering:
+      <code class="font-mono">notFound()</code> (404),
+      <code class="font-mono">forbidden()</code> (403), and
+      <code class="font-mono">unauthorized()</code> (401), each rendering the
+      nearest matching boundary file. See the
+      <a class="text-primary" href="/features/boundaries">Boundaries</a> demo.
+    </p>
   `;
 }

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/manifest.ts

@@ -0,0 +1,22 @@
+// 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/manifest.ts serves /manifest.json (the web app manifest). The default
+// export returns an object, serialized to JSON. Adapt the name, colors, and
+// icons to your app; pair it with the opt-in service worker for an installable
+// PWA. See agent-docs/service-worker.md. (Gallery files are copied verbatim, so
+// set the real app name here by hand rather than expecting substitution.)
+export default function Manifest() {
+  return {
+    name: 'webjs app',
+    short_name: 'webjs app',
+    start_url: '/',
+    display: 'standalone',
+    background_color: '#ffffff',
+    theme_color: '#1c1613',
+    icons: [
+      { src: '/favicon.svg', sizes: 'any', type: 'image/svg+xml' },
+    ],
+  };
+}

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/robots.ts

@@ -0,0 +1,16 @@
+// 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/robots.ts serves /robots.txt. The default export returns a string (served
+// as text/plain) or an object. This example allows all crawlers and points them
+// at the sitemap. Tighten the rules (Disallow paths) for a real app.
+const SITE_URL = (process.env.SITE_URL || 'http://localhost:8080').replace(/\/$/, '');
+
+export default function Robots() {
+  return [
+    'User-agent: *',
+    'Allow: /',
+    `Sitemap: ${SITE_URL}/sitemap.xml`,
+  ].join('\n');
+}

package/templates/gallery/app/sitemap.ts

@@ -0,0 +1,23 @@
+// webjs-scaffold-placeholder. Metadata route. Keep and adapt it to your real
+// routes, or prune it (delete this file), then delete this marker line. webjs
+// check fails while the marker remains.
+//
+// app/sitemap.ts serves /sitemap.xml. The default export is a (possibly async)
+// server function; `sitemap(entries)` from @webjsdev/server serializes a
+// spec-valid XML sitemap. In a real app, build the entries from your content
+// (a query over posts/products), so new content is discoverable without editing
+// this file. Here it lists the gallery's static routes as an example.
+import { sitemap } from '@webjsdev/server';
+
+const SITE_URL = (process.env.SITE_URL || 'http://localhost:8080').replace(/\/$/, '');
+
+export default function Sitemap() {
+  const routes = ['/', '/features/routing', '/features/boundaries'];
+  return sitemap(
+    routes.map((path) => ({
+      url: `${SITE_URL}${path}`,
+      changeFrequency: 'weekly' as const,
+      priority: path === '/' ? 1.0 : 0.7,
+    })),
+  );
+}

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

@@ -0,0 +1,52 @@
+// 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. `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="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>
+    `;
+  }
+}
+RouterControls.register('router-controls');