@webjsdev/cli 0.10.29 → 0.10.31

package/templates/gallery/app/features/client-router/page.ts

@@ -0,0 +1,34 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/client-router route AND its second/ subpage), then delete this marker line. webjs check fails while the marker remains.
+// Client router: automatic. It auto-enables the moment @webjsdev/core loads in
+// the browser (the bundle every component pulls, so any page with a component
+// gets it for free). There is nothing to import. An <a href> to another page
+// does a soft navigation: the framework fetches only the divergent fragment
+// (via the X-Webjs-Have header), swaps it in place, and restores scroll on
+// back/forward. Links prefetch on hover by default. It degrades perfectly: with
+// JS off, every link is a normal full-page navigation.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+
+export const metadata: Metadata = { title: 'Client router (soft nav) | features' };
+
+export default function ClientRouterExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Client router</h1>
+    <p class="text-muted-foreground mb-4">
+      Navigate to the second page and back. With JS on it is a soft swap (no full
+      reload, scroll restored); open the network tab to see only a fragment
+      fetched, prefetched on hover. With JS off the same links do full-page
+      navigations. Nothing was imported to get this.
+    </p>
+    <div class="flex gap-3 items-center">
+      <a href="/features/client-router/second" class="inline-flex items-center px-4 py-2 rounded-xl bg-primary text-primary-foreground font-semibold text-sm no-underline transition-all hover:bg-primary/90 active:scale-[0.97]">Go to page two</a>
+      <a href="/" class="text-muted-foreground no-underline font-medium text-sm hover:text-foreground transition-colors">Home</a>
+    </div>
+    <p class="text-muted-foreground text-sm mt-6">
+      Opt out app-wide with <code class="font-mono">{ "webjs": { "clientRouter": false } }</code>,
+      or per-link with <code class="font-mono">data-no-router</code> (use it for
+      auth flows like <code class="font-mono">/logout</code> that must reset
+      in-memory state).
+    </p>
+  `;
+}

package/templates/gallery/app/features/client-router/second/page.ts

@@ -0,0 +1,20 @@
+// webjs-scaffold-placeholder. Feature gallery route (client-router page two). Pruned together with the parent app/features/client-router route. Delete this marker line once you adapt or remove it. webjs check fails while the marker remains.
+// The soft-navigation target for the client-router demo. A plain page: the
+// router needs no per-page code. The browser Back button restores this page and
+// its scroll position from the client-router snapshot cache.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+
+export const metadata: Metadata = { title: 'Client router: page two | features' };
+
+export default function ClientRouterSecond() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Page two</h1>
+    <p class="text-muted-foreground mb-4">
+      You arrived here without a full reload. Press the browser Back button (or
+      the link below): the previous page and its scroll position are restored
+      from the snapshot cache.
+    </p>
+    <a href="/features/client-router" class="text-primary no-underline font-medium">&larr; Back to page one</a>
+  `;
+}

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

@@ -0,0 +1,14 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/components route AND modules/components), 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/components/components/counter-card.ts';
+
+export const metadata: Metadata = { title: 'Components (signals + slots) | features' };
+
+export default function ComponentsExample() {
+  return html`
+    <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>
+  `;
+}

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

@@ -0,0 +1,14 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/directives route AND modules/directives), 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/directives/components/directive-demo.ts';
+
+export const metadata: Metadata = { title: 'Directives (repeat + watch) | features' };
+
+export default function DirectivesExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Directives</h1>
+    <p class="text-muted-foreground mb-4">The lit-html directive set: <code>repeat</code> keys a reordering list so nodes are reused, and <code>watch(signal)</code> swaps one node without a full re-render.</p>
+    <directive-demo></directive-demo>
+  `;
+}

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

@@ -0,0 +1,36 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/env route), then delete this marker line. webjs check fails while the marker remains.
+// Environment variables: process.env.X reads are server-only. NODE_ENV is
+// defined on both sides. A name prefixed WEBJS_PUBLIC_ is exposed to the browser
+// through an inline script (no build step); everything else stays server-side
+// so secrets never reach the client. This page reads them during SSR, so the
+// values are in the first paint with no JS. Validate required vars at boot with
+// an app-root env.ts (a schema or a validator fn) that fails fast.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+
+export const metadata: Metadata = { title: 'Env vars (public vs server) | features' };
+
+export default function EnvExample() {
+  // Server-only read (this function runs on the server for SSR).
+  const nodeEnv = process.env.NODE_ENV || 'development';
+  // A WEBJS_PUBLIC_ var is safe to surface to the browser; unset here unless you
+  // add WEBJS_PUBLIC_APP_NAME=... to .env, which demonstrates the default.
+  const publicName = process.env.WEBJS_PUBLIC_APP_NAME || '(unset, add WEBJS_PUBLIC_APP_NAME to .env)';
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Environment variables</h1>
+    <p class="text-muted-foreground mb-4">
+      Read on the server during SSR. Only <code>WEBJS_PUBLIC_</code>-prefixed
+      names are exposed to the browser; the rest stay server-side.
+    </p>
+    <ul class="list-disc pl-5 mb-4 space-y-1">
+      <li><code class="font-mono text-sm">NODE_ENV</code> = <span class="text-primary">${nodeEnv}</span> <span class="text-muted-foreground text-sm">(defined both sides)</span></li>
+      <li><code class="font-mono text-sm">WEBJS_PUBLIC_APP_NAME</code> = <span class="text-primary">${publicName}</span></li>
+    </ul>
+    <p class="text-muted-foreground text-sm">
+      Never read a secret in a page, layout, or component that ships to the
+      browser. Keep secret reads in <code class="font-mono">.server.ts</code>
+      files, and validate required vars at boot with
+      <code class="font-mono">app/env.ts</code>.
+    </p>
+  `;
+}

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

@@ -0,0 +1,19 @@
+// Serves a stored file back by key. getFileStore().get(key) returns the bytes as
+// a web ReadableStream (streamed, never buffered whole into memory) plus the
+// content type recorded at upload. A route.ts is server-only, so importing the
+// 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';
+
+export async function GET(_req: Request, { params }: { params: { key: string } }) {
+  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
+  // bytes); the store's type is a Node/web union, so narrow it for Response.
+  return new Response(file.body as ReadableStream<Uint8Array>, {
+    headers: {
+      'content-type': file.contentType,
+      'content-length': String(file.size),
+    },
+  });
+}

package/templates/gallery/app/features/file-storage/page.ts

@@ -0,0 +1,62 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/file-storage route AND modules/file-storage), then delete this marker line. webjs check fails while the marker remains.
+// File storage: a no-JS upload. A multipart <form> posts to this page's `action`
+// (the progressive-enhancement write path); the action calls a 'use server'
+// helper that streams the bytes into the FileStore. On success it redirects
+// (PRG) with the new key in the query, and the page renders a download link that
+// streams the file back through file/[key]/route.ts. Works with JS off; the
+// client router applies the same flow in place with JS on.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+import { storeUpload } from '#modules/file-storage/actions/store-upload.server.ts';
+
+export const metadata: Metadata = { title: 'File storage (upload + serve) | features' };
+
+export async function action({ formData }: { formData: FormData }) {
+  const file = formData.get('file');
+  if (!(file instanceof File) || file.size === 0) {
+    return { success: false, error: 'Choose a file to upload.' };
+  }
+  const result = await storeUpload(file);
+  if (!result.success) return result;
+  const { key, name, size } = result.data;
+  const q = new URLSearchParams({ key, name, size: String(size) });
+  return { success: true, redirect: '/features/file-storage?' + q.toString() };
+}
+
+export default function FileStorageExample({
+  searchParams,
+  actionData,
+}: {
+  searchParams: Record<string, string | undefined>;
+  actionData?: { error?: string };
+}) {
+  const key = (searchParams.key || '').trim();
+  const name = (searchParams.name || '').trim();
+  const size = (searchParams.size || '').trim();
+  return html`
+    <h1 class="text-h2 font-bold mb-4">File storage</h1>
+    <p class="text-muted-foreground mb-4">
+      Upload a file: the bytes stream into the FileStore (a local
+      <code class="font-mono">.webjs/uploads</code> directory by default,
+      gitignored). Swap the backend for S3/R2 with one
+      <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
+        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>
+    </form>
+    ${actionData?.error
+      ? html`<p class="text-destructive text-sm mb-4">${actionData.error}</p>`
+      : ''}
+    ${key
+      ? 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>
+          <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

@@ -0,0 +1,72 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/forms route), then delete this marker line. webjs check fails while the marker remains.
+// forms: the no-JS write path. A real <form method="post"> posts to this page's
+// `action` export, and the framework re-renders the SAME page with the result on
+// `actionData`. WHY it matters: the form works with JS OFF (server round-trip),
+// and with JS the client router applies the response in place (no full reload).
+// Never reach for fetch() + a click handler where a <form> + page action does.
+// On failure the framework re-renders at 422 with the result; on success it
+// does a 303 Post-Redirect-Get, so we redirect to ?sent=1 to show a confirmation.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+
+export const metadata: Metadata = { title: 'Forms (no-JS PE) | features' };
+
+interface Result {
+  success: boolean;
+  fieldErrors?: Record<string, string>;
+  values?: Record<string, string>;
+  redirect?: string;
+}
+
+const field = (label: string, name: string, input: unknown, error?: string) => html`
+  <div class="grid gap-1.5">
+    <label for=${name} class="text-[13px] font-medium text-muted-foreground">${label}</label>
+    ${input}
+    ${error ? html`<p class="m-0 text-[12.5px] text-destructive">${error}</p>` : ''}
+  </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';
+
+export default function FormsFeature({ searchParams, actionData }: { searchParams: Record<string, string | undefined>; actionData?: Result }) {
+  if (searchParams.sent) {
+    return html`
+      <h1 class="text-h2 font-bold mb-4">Forms</h1>
+      <div class="max-w-[460px] grid gap-3 p-6 rounded-2xl bg-card border border-border text-center">
+        <span class="mx-auto grid place-items-center w-12 h-12 rounded-2xl bg-primary/15 text-primary">
+          <svg viewBox="0 0 24 24" class="w-6 h-6 stroke-current fill-none" style="stroke-width:2.4;stroke-linecap:round;stroke-linejoin:round"><path d="m5 13 4 4L19 7"/></svg>
+        </span>
+        <p class="m-0 text-lg font-semibold text-foreground">Message sent</p>
+        <p class="m-0 text-sm text-muted-foreground">Thanks, we got it. <a class="text-primary" href="/features/forms">Send another</a>.</p>
+      </div>
+    `;
+  }
+  const errs = actionData?.fieldErrors ?? {};
+  const v = actionData?.values ?? {};
+  return html`
+    <h1 class="text-h2 font-bold mb-2">Forms</h1>
+    <p class="text-muted-foreground mb-5 max-w-[460px]">A real <code>&lt;form&gt;</code> posting to this page's <code>action</code>. It works with JS off; validation errors come back on <code>actionData</code>.</p>
+    <form method="post" action="" class="max-w-[460px] grid gap-4 p-5 rounded-2xl bg-card border border-border">
+      ${field('Name', 'name', html`<input id="name" name="name" value=${v.name ?? ''} class=${inputCls} placeholder="Ada Lovelace" />`, errs.name)}
+      ${field('Email', 'email', html`<input id="email" name="email" type="email" value=${v.email ?? ''} class=${inputCls} placeholder="ada@example.com" />`, errs.email)}
+      ${field('Message', 'message', html`<textarea id="message" name="message" rows="3" class=${inputCls} placeholder="Say hello...">${v.message ?? ''}</textarea>`, errs.message)}
+      <button type="submit" class="justify-self-start px-4 py-2 rounded-xl bg-primary text-primary-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-primary/90 active:scale-[0.97]">Send message</button>
+    </form>
+  `;
+}
+
+// The page action runs on a non-GET submission to this URL (the no-JS write
+// path). Validate, then return a failure (re-renders at 422 with fieldErrors +
+// values) or a success with a same-site `redirect` (a 303 PRG to the confirmation).
+export async function action({ formData }: { formData: FormData }): Promise<Result> {
+  const name = String(formData.get('name') ?? '').trim();
+  const email = String(formData.get('email') ?? '').trim();
+  const message = String(formData.get('message') ?? '').trim();
+  const fieldErrors: Record<string, string> = {};
+  if (!name) fieldErrors.name = 'Your name is required.';
+  if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email)) fieldErrors.email = 'A valid email is required.';
+  if (message.length < 5) fieldErrors.message = 'Message must be at least 5 characters.';
+  if (Object.keys(fieldErrors).length) return { success: false, fieldErrors, values: { name, email, message } };
+  // A real app would persist / email here. We just confirm.
+  return { success: true, redirect: '/features/forms?sent=1' };
+}

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

@@ -0,0 +1,55 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/metadata route), then delete this marker line. webjs check fails while the marker remains.
+// Metadata: how a page declares its <title>, description, and Open Graph tags.
+// A static `metadata` export is read as-is. `generateMetadata(ctx)` takes
+// precedence and can read the request (params, searchParams, url) to compute
+// the tags, and may be async. Both run only on the server, so the tags are in
+// the first paint (no JS, crawler-friendly). Whole-page metadata ROUTES
+// (sitemap.ts, robots.ts, opengraph-image.ts, ...) live at the app root.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+
+// generateMetadata wins over a static `metadata` export when both exist. Here
+// it derives the title from a ?topic= query param to show the dynamic form;
+// with no param it falls back to a default. Change the URL to ?topic=webjs and
+// view source: the <title> follows.
+export function generateMetadata({
+  searchParams,
+}: {
+  searchParams: Record<string, string | undefined>;
+}): Metadata {
+  const topic = (searchParams.topic || '').trim();
+  return {
+    title: topic ? topic + ' | metadata' : 'Metadata (generateMetadata) | features',
+    description: 'How a webjs page declares title, description, and Open Graph tags.',
+    openGraph: { title: topic || 'Metadata', type: 'article' },
+  };
+}
+
+export default function MetadataExample({
+  searchParams,
+}: {
+  searchParams: Record<string, string | undefined>;
+}) {
+  const topic = (searchParams.topic || '').trim();
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Metadata</h1>
+    <p class="text-muted-foreground mb-4">
+      <code>generateMetadata(ctx)</code> runs on the server and can read the
+      request, so the <code>&lt;title&gt;</code> is computed per URL. View source
+      to see the tag this page produced.
+    </p>
+    <p class="mb-4">
+      Current title source:
+      <code class="font-mono text-sm">${topic ? '?topic=' + topic : '(default, no ?topic=)'}</code>
+    </p>
+    <ul class="list-disc pl-5 mb-4">
+      <li><a class="text-primary" href="/features/metadata?topic=webjs">?topic=webjs</a></li>
+      <li><a class="text-primary" href="/features/metadata?topic=Routing">?topic=Routing</a></li>
+      <li><a class="text-primary" href="/features/metadata">clear the param</a></li>
+    </ul>
+    <p class="text-muted-foreground text-sm">
+      Site-wide metadata (sitemap, robots, Open Graph images) lives in metadata
+      ROUTES at the app root, e.g. <code class="font-mono">app/sitemap.ts</code>.
+    </p>
+  `;
+}

package/templates/gallery/app/features/optimistic-ui/page.ts

@@ -0,0 +1,14 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/optimistic-ui route AND modules/optimistic-ui), 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/optimistic-ui/components/like-button.ts';
+
+export const metadata: Metadata = { title: 'Optimistic UI (imperative flip) | features' };
+
+export default function OptimisticUiFeature() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Optimistic UI</h1>
+    <p class="text-muted-foreground mb-4">The imperative <code>optimistic(signal, value, action)</code> form: the UI flips instantly and rolls back if the action fails. For the declarative list form (add / remove with rollback) in a full app, see <a class="text-primary" href="/examples/todo">/examples/todo</a>.</p>
+    <like-button></like-button>
+  `;
+}

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

@@ -0,0 +1,29 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/rate-limit route AND modules/rate-limit), then delete this marker line. webjs check fails while the marker remains.
+// Rate limiting: rateLimit() from '@webjsdev/server' is a middleware. It lives in
+// a middleware.ts scoped to the endpoint it protects (here app/features/
+// rate-limit/ping/middleware.ts, so it limits /features/rate-limit/ping WITHOUT
+// touching this page). It is backed by the pluggable cache store, in-memory by
+// default; point the store at Redis to share the window across instances.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+import '#modules/rate-limit/components/rate-probe.ts';
+
+export const metadata: Metadata = { title: 'Rate limiting (rateLimit middleware) | features' };
+
+export default function RateLimitExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Rate limiting</h1>
+    <p class="text-muted-foreground mb-4">
+      The <code class="font-mono">/ping</code> endpoint is limited to five
+      requests per ten seconds by a scoped <code class="font-mono">middleware.ts</code>.
+      Ping past the limit to get a <code class="font-mono">429</code> with a
+      <code class="font-mono">Retry-After</code> header.
+    </p>
+    <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>
+      directly (refresh past five times in ten seconds).
+    </p>
+  `;
+}

package/templates/gallery/app/features/rate-limit/ping/middleware.ts

@@ -0,0 +1,8 @@
+// Per-segment middleware. It sits in the ping/ folder, so it applies ONLY to
+// /features/rate-limit/ping (its route.ts), not to the demo page one level up.
+// rateLimit() returns a standard webjs middleware: return a Response to
+// short-circuit (the 429), or call next() to continue. Keyed by client IP by
+// default; pass `key` to key by user id, API key, etc.
+import { rateLimit } from '@webjsdev/server';
+
+export default rateLimit({ window: '10s', max: 5, message: 'Slow down: five requests per ten seconds.' });

package/templates/gallery/app/features/rate-limit/ping/route.ts

@@ -0,0 +1,7 @@
+// The rate-limited endpoint. A plain GET route handler: it just reports success.
+// The rateLimit() middleware in this folder runs BEFORE it and stamps the
+// X-RateLimit-* headers onto the response (and returns a 429 once the window is
+// exhausted, so this handler never runs on a limited request).
+export function GET() {
+  return Response.json({ ok: true, at: new Date().toISOString() });
+}

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

@@ -0,0 +1,8 @@
+// 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() });
+}

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

@@ -0,0 +1,13 @@
+// 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';
+
+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>
+  `;
+}

package/templates/gallery/app/features/routing/[id]/page.ts

@@ -0,0 +1,25 @@
+// A dynamic route: `params.id` is the URL segment. The default export is a
+// (possibly async) function receiving { params, searchParams, url }; it runs
+// ONLY on the server. Throw notFound() / redirect() to short-circuit.
+//
+// Type-safe routes: instead of hand-typing `{ params: { id: string } }`, type
+// the props with PageProps<'<route>'>. `webjs types` (run automatically by
+// `webjs dev`) generates .webjs/routes.d.ts with a Route union and per-route
+// 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 type { PageProps } from '@webjsdev/core';
+
+export default function RoutingParam({ params }: PageProps<'/features/routing/[id]'>) {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Route param</h1>
+    <p>The <code>[id]</code> segment is: <strong>${params.id}</strong></p>
+    <p class="text-muted-foreground text-sm mt-3">
+      Typed with <code class="font-mono">PageProps&lt;'/features/routing/[id]'&gt;</code>,
+      so <code class="font-mono">params.id</code> is a checked
+      <code class="font-mono">string</code> from the generated route union.
+    </p>
+    <p class="mt-3"><a class="text-primary" href="/features/routing">Back</a></p>
+  `;
+}

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

@@ -0,0 +1,47 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/routing route), then delete this marker line. webjs check fails while the marker remains.
+// Routing basics: a static page that links to a dynamic route. app/ is routing
+// only; a folder maps to a URL segment, and [id] is a dynamic segment read from
+// `params`. See app/features/routing/[id]/page.ts.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+
+export const metadata: Metadata = { title: 'Routing (dynamic params) | features' };
+
+export default function RoutingExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Routing</h1>
+    <p class="text-muted-foreground mb-4">A folder is a URL segment; a <code>[id]</code> folder is a dynamic param.</p>
+    <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>
+    </ul>
+    <p class="text-muted-foreground text-sm mb-2">
+      Routes are type-safe: <code class="font-mono">webjs types</code> (run by
+      <code class="font-mono">webjs dev</code>) generates a
+      <code class="font-mono">Route</code> union, and the
+      <code class="font-mono">[id]</code> page types its props with
+      <code class="font-mono">PageProps&lt;'/features/routing/[id]'&gt;</code>
+      so <code class="font-mono">params</code> is checked against the real routes.
+    </p>
+    <p class="text-muted-foreground text-sm mb-2">
+      Programmatic navigation is checked too:
+      <code class="font-mono">navigate(url)</code> takes that
+      <code class="font-mono">Route</code> union, so
+      <code class="font-mono">navigate('/random/42')</code> is a compile error in
+      your editor and <code class="font-mono">webjs typecheck</code>. (Plain
+      <code class="font-mono">&lt;a href&gt;</code> strings are not checked, so
+      prefer <code class="font-mono">navigate()</code> for internal links you want
+      verified.)
+    </p>
+    <p class="text-muted-foreground text-sm">
+      Changing route in code, two sides:
+      <code class="font-mono">navigate(url)</code> runs in the browser (a soft,
+      in-place client-router nav from an event handler, no reload), while
+      <code class="font-mono">redirect(url)</code> runs on the server (throw it in
+      a page or an <code class="font-mono">action</code> to bail before render and
+      return an HTTP 3xx). Throw
+      <code class="font-mono">redirect()</code> on the server, call
+      <code class="font-mono">navigate()</code> on the client.
+    </p>
+  `;
+}

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

@@ -0,0 +1,14 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/server-actions route AND modules/server-actions), 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/server-actions/components/greeter.ts';
+
+export const metadata: Metadata = { title: 'Server actions (.server vs use server) | features' };
+
+export default function ServerActionsExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Server actions</h1>
+    <p class="text-muted-foreground mb-4">A 'use server' action is RPC-callable from the client; a plain .server.ts is a server-only utility you never import into a component.</p>
+    <server-greeter></server-greeter>
+  `;
+}

package/templates/gallery/app/features/service-worker/page.ts

@@ -0,0 +1,35 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/service-worker route), then delete this marker line. webjs check fails while the marker remains.
+// Service worker: opt-in progressive enhancement. webjs does NOT register one by
+// default (an active SW caches aggressively and would confuse dev). You opt in
+// by adding public/sw.js and registering it from a component's connectedCallback
+// (browser-only). This page is a guided reference, not an active registration,
+// so the scaffold stays predictable until you deliberately turn it on. See
+// agent-docs/service-worker.md for the full recipe.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+
+export const metadata: Metadata = { title: 'Service worker (opt-in) | features' };
+
+export default function ServiceWorkerExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Service worker</h1>
+    <p class="text-muted-foreground mb-4">
+      Opt-in offline/caching enhancement. Nothing is registered until you add
+      <code class="font-mono">public/sw.js</code> and register it from a
+      browser-only lifecycle hook.
+    </p>
+    <p class="mb-2 text-sm font-medium">Register inside a component (never in a page or layout):</p>
+    <pre class="bg-card border border-border rounded-xl p-4 overflow-x-auto text-sm font-mono mb-4"><code>connectedCallback() {
+  super.connectedCallback();
+  if ('serviceWorker' in navigator) {
+    // Register at the site root so the worker's scope is the whole origin.
+    navigator.serviceWorker.register('/sw.js');
+  }
+}</code></pre>
+    <p class="text-muted-foreground text-sm">
+      Registration lives in a component because it is browser-only work.
+      A page or layout never hydrates, so it is the wrong home for it. Full
+      recipe: <code class="font-mono">agent-docs/service-worker.md</code>.
+    </p>
+  `;
+}

package/templates/gallery/app/features/websockets/echo/route.ts

@@ -0,0 +1,19 @@
+// The WebSocket endpoint for the websockets feature demo. A route.ts is a
+// server-only HTTP file; exporting WS(ws, req, ctx) upgrades it to a WebSocket
+// endpoint. `ws` is a standard ws-library socket: listen with ws.on('message'),
+// reply with ws.send(). In dev the module is re-imported per connection, so keep
+// shared state on globalThis if you need it (this echo endpoint is stateless).
+
+// Structural type for the socket, so the demo needs no `@types/ws` dependency.
+type WSLike = {
+  on(event: 'message' | 'close', cb: (data: Buffer) => void): void;
+  send(msg: string): void;
+};
+
+export function WS(ws: WSLike) {
+  ws.on('message', (data) => {
+    // Echo the text back to just this client. For a fan-out to ALL connected
+    // clients, use broadcast() from '@webjsdev/server' (see the broadcast demo).
+    ws.send('echo: ' + data.toString());
+  });
+}

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

@@ -0,0 +1,25 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/websockets route AND modules/websockets), then delete this marker line. webjs check fails while the marker remains.
+// WebSockets: a route.ts exports WS(ws, req) for the server endpoint, and a
+// component uses connectWS() to talk to it. WebSockets are inherently JS-only
+// (there is no no-JS fallback for a live socket), so the component degrades to a
+// clear "requires JavaScript" note at SSR and enhances on hydration. The echo
+// endpoint lives at app/features/websockets/echo/route.ts (a sibling folder, so
+// it does not collide with this page).
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+import '#modules/websockets/components/ws-echo.ts';
+
+export const metadata: Metadata = { title: 'WebSockets (connectWS + WS) | features' };
+
+export default function WebSocketsExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">WebSockets</h1>
+    <p class="text-muted-foreground mb-4">
+      A <code class="font-mono">WS(ws, req)</code> export in
+      <code class="font-mono">route.ts</code> is the server endpoint;
+      <code class="font-mono">connectWS()</code> (auto-reconnect, JSON
+      encode/decode, queued sends) is the client. This echoes each message back.
+    </p>
+    <ws-echo></ws-echo>
+  `;
+}