@webjsdev/cli 0.10.44 → 0.10.46

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

@@ -16,47 +16,48 @@
 //   /features/boundaries/private throws unauthorized() -> private/unauthorized.ts
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
+import { pageHeading, lede } from '#lib/utils/ui.ts';
 
 export const metadata: Metadata = { title: 'Boundaries (throws + boundary files) | features' };
 
 export default function BoundariesExample() {
   return html`
-    <h1 class="text-h2 font-bold mb-4">Boundaries</h1>
-    <p class="text-muted-foreground mb-4">
+    ${pageHeading('Boundaries')}
+    ${lede(html`
       Throw a control-flow function from a page (or a page
       <code class="font-mono">action</code>) to short-circuit the render. The
       framework catches it and renders the nearest matching boundary file in the
       route's chain, innermost wins.
-    </p>
+    `)}
     <ul class="list-disc pl-5 mb-4">
       <li>
-        <a class="text-primary" href="/features/boundaries/gated">/features/boundaries/gated</a>
+        <a class="text-primary underline underline-offset-2" href="/features/boundaries/gated">/features/boundaries/gated</a>
         throws <code class="font-mono">forbidden()</code>, caught by
         <code class="font-mono">gated/forbidden.ts</code> (403).
       </li>
       <li>
-        <a class="text-primary" href="/features/boundaries/private">/features/boundaries/private</a>
+        <a class="text-primary underline underline-offset-2" href="/features/boundaries/private">/features/boundaries/private</a>
         throws <code class="font-mono">unauthorized()</code>, caught by
         <code class="font-mono">private/unauthorized.ts</code> (401).
       </li>
       <li>
-        <a class="text-primary" href="/features/boundaries/crash">/features/boundaries/crash</a>
+        <a class="text-primary underline underline-offset-2" href="/features/boundaries/crash">/features/boundaries/crash</a>
         throws a render error, caught by this segment's
         <code class="font-mono">error.ts</code> (500).
       </li>
       <li>
-        <a class="text-primary" href="/features/boundaries/does-not-exist">/features/boundaries/does-not-exist</a>
+        <a class="text-primary underline underline-offset-2" href="/features/boundaries/does-not-exist">/features/boundaries/does-not-exist</a>
         matches nothing, caught by the nearest
         <code class="font-mono">not-found.ts</code> (404).
       </li>
     </ul>
-    <p class="text-muted-foreground text-sm mb-2">
+    <p class="text-muted-foreground text-sm">
       <code class="font-mono">forbidden()</code> is for an authenticated user who
       lacks permission (403); <code class="font-mono">unauthorized()</code> is for
       a request that is not authenticated at all (401). Both import from
       <code class="font-mono">@webjsdev/core</code> and are thrown, never returned.
     </p>
-    <p class="text-muted-foreground text-sm mb-2">
+    <p class="text-muted-foreground text-sm">
       Same throw model as <code class="font-mono">notFound()</code> (renders the
       nearest <code class="font-mono">not-found.ts</code>) and
       <code class="font-mono">redirect(url)</code> (sends an HTTP 3xx). Inside a
@@ -71,6 +72,6 @@ export default function BoundariesExample() {
       and <code class="font-mono">app/global-not-found.ts</code> (a 404 for a URL
       that matches nothing anywhere).
     </p>
-    <p class="mt-3"><a class="text-primary" href="/">Back to the gallery</a></p>
+    <p class="mt-3"><a class="text-primary underline underline-offset-2" href="/">Back to the gallery</a></p>
   `;
 }

package/templates/gallery/app/features/boundaries/private/unauthorized.ts

@@ -3,15 +3,16 @@
 // in place of the page that threw. Nearest wins: this one (inside private/) beats
 // any unauthorized.ts higher up the tree. A real one usually links to sign-in.
 import { html } from '@webjsdev/core';
+import { pageHeading, lede } from '#lib/utils/ui.ts';
 
 export default function Unauthorized() {
   return html`
-    <h1 class="text-h2 font-bold mb-4">401 Unauthorized</h1>
-    <p class="text-muted-foreground mb-4">
+    ${pageHeading('401 Unauthorized')}
+    ${lede(html`
       You need to sign in to view this page. This is the nearest
       <code class="font-mono">unauthorized.ts</code> boundary, rendered because the
       page threw <code class="font-mono">unauthorized()</code>.
-    </p>
-    <p><a class="text-primary" href="/features/boundaries">Back to boundaries</a></p>
+    `)}
+    <p><a class="text-primary underline underline-offset-2" href="/features/boundaries">Back to boundaries</a></p>
   `;
 }

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

@@ -5,19 +5,20 @@
 // Open this page in two browser tabs and send: both see every message.
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
+import { pageHeading, lede } from '#lib/utils/ui.ts';
 import '#modules/broadcast/components/broadcast-feed.ts';
 
 export const metadata: Metadata = { title: 'Broadcast (fan-out to all clients) | features' };
 
 export default function BroadcastExample() {
   return html`
-    <h1 class="text-h2 font-bold mb-4">Broadcast</h1>
-    <p class="text-muted-foreground mb-4">
+    ${pageHeading('Broadcast')}
+    ${lede(html`
       Every message is fanned out to all connected clients via
       <code class="font-mono">broadcast()</code>. Open this page in a second tab
       and watch messages appear in both. Single-instance by default; wire Redis
       to scale across processes.
-    </p>
+    `)}
     <broadcast-feed></broadcast-feed>
   `;
 }

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

@@ -7,6 +7,7 @@
 // use HTTP Cache-Control + ETag (conditional GET).
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
+import { pageHeading, lede } from '#lib/utils/ui.ts';
 import '#modules/caching/components/cache-buster.ts';
 
 export const metadata: Metadata = { title: 'Caching (revalidate) | features' };
@@ -19,11 +20,11 @@ export default function CachingExample() {
   // seconds, so this value is frozen until the window elapses.
   const renderedAt = new Date().toLocaleTimeString('en-US', { hour12: false });
   return html`
-    <h1 class="text-h2 font-bold mb-4">Caching</h1>
-    <p class="text-muted-foreground mb-4">
+    ${pageHeading('Caching')}
+    ${lede(html`
       This page sets <code>export const revalidate = 10</code>, so its
       server-rendered HTML is cached per URL for ten seconds.
-    </p>
+    `)}
     <p class="mb-4">
       Rendered at
       <code class="font-mono text-primary">${renderedAt}</code>.
@@ -35,7 +36,7 @@ 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">
+    <p class="text-muted-foreground text-sm">
       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

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

@@ -7,24 +7,26 @@
 // JS off, every link is a normal full-page navigation.
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
+import { pageHeading, lede } from '#lib/utils/ui.ts';
 import '#modules/client-router/components/router-controls.ts';
 
 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">
+    ${pageHeading('Client router')}
+    ${lede(html`
       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="/features/client-router/second" class="${buttonClass()} no-underline">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 mb-2">Or drive it from JS with <code class="font-mono">navigate()</code> / <code class="font-mono">revalidate()</code>:</p>
+    <p class="text-muted-foreground text-sm mt-6">Or drive it from JS with <code class="font-mono">navigate()</code> / <code class="font-mono">revalidate()</code>:</p>
     <router-controls></router-controls>
     <p class="text-muted-foreground text-sm mt-6">
       Opt out app-wide with <code class="font-mono">{ "webjs": { "clientRouter": false } }</code>,

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

@@ -3,17 +3,18 @@
 // its scroll position from the client-router snapshot cache.
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
+import { pageHeading, lede } from '#lib/utils/ui.ts';
 
 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">
+    ${pageHeading('Page two')}
+    ${lede(html`
       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

@@ -1,5 +1,6 @@
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
+import { pageHeading, lede } from '#lib/utils/ui.ts';
 import '#modules/components/components/counter-card.ts';
 import '#modules/components/components/reactive-meter.ts';
 import '#modules/components/components/theme-context.ts';
@@ -9,8 +10,8 @@ export const metadata: Metadata = { title: 'Components (signals + slots) | featu
 
 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>
+    ${pageHeading('Components')}
+    ${lede(html`The WebComponent factory, a reactive prop, an instance signal, and a slot.`)}
     <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>

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

@@ -1,13 +1,14 @@
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
+import { pageHeading, lede } from '#lib/utils/ui.ts';
 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>
+    ${pageHeading('Directives')}
+    ${lede(html`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.`)}
     <directive-demo></directive-demo>
   `;
 }

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

@@ -6,6 +6,7 @@
 // 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';
+import { pageHeading, lede } from '#lib/utils/ui.ts';
 
 export const metadata: Metadata = { title: 'Env vars (public vs server) | features' };
 
@@ -16,11 +17,11 @@ export default function EnvExample() {
   // 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">
+    ${pageHeading('Environment variables')}
+    ${lede(html`
       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>

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

@@ -5,6 +5,9 @@
 // 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 { buttonClass } from '#components/ui/button.ts';
+import { cardClass } from '#components/ui/card.ts';
+import { pageHeading, lede } from '#lib/utils/ui.ts';
 import type { Metadata } from '@webjsdev/core';
 import { storeUpload } from '#modules/file-storage/actions/store-upload.server.ts';
 
@@ -33,25 +36,25 @@ export default function FileStorageExample({
   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">
+    ${pageHeading('File storage')}
+    ${lede(html`
       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 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>
+        class=${buttonClass()}>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">
+        <div class="${cardClass('rounded-xl')} px-4 py-3 text-sm">
           Stored <span class="text-foreground font-medium">${name}</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>

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

@@ -6,6 +6,10 @@
 // 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 { cardClass } from '#components/ui/card.ts';
+import { inputClass } from '#components/ui/input.ts';
+import { buttonClass } from '#components/ui/button.ts';
+import { pageHeading } from '#lib/utils/ui.ts';
 import type { Metadata } from '@webjsdev/core';
 
 export const metadata: Metadata = { title: 'Forms (no-JS PE) | features' };
@@ -25,18 +29,18 @@ 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';
+const inputCls = inputClass();
 
 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">
+      ${pageHeading('Forms')}
+      <div class="${cardClass()} max-w-[460px] grid gap-3 p-6 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>
+        <p class="m-0 text-sm text-muted-foreground">Thanks, we got it. <a class="text-primary underline underline-offset-2" href="/features/forms">Send another</a>.</p>
       </div>
     `;
   }
@@ -45,11 +49,11 @@ export default function FormsFeature({ searchParams, actionData }: { searchParam
   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">
+    <form method="post" action="" class="${cardClass()} max-w-[460px] grid gap-4 p-5">
       ${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>
+      <button type="submit" class="${buttonClass()} justify-self-start">Send message</button>
     </form>
   `;
 }

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

@@ -2,7 +2,13 @@
 // link targeting its id, shipping zero component JS. It is WebJs's take on Turbo
 // Frames. Unlike the client router (which swaps the whole page's children when
 // you navigate to a DIFFERENT url), a frame refreshes just ONE sub-region in
-// place. The filter links below live INSIDE the frame, so a click walks
+// place. It is also NOT a layout: a layout (layout.ts) is server-rendered chrome
+// that WRAPS a route subtree via ${children} and re-renders only as part of a
+// navigation, so it answers "what structure wraps these routes". A frame answers
+// "which region updates itself in place", with no navigation at all. Use a layout
+// for shared chrome across routes; use a frame when one region (a filtered list,
+// a paginated table, a tab panel) must refresh on its own without navigating.
+// The filter links below live INSIDE the frame, so a click walks
 // closest('webjs-frame'), refetches THIS same page with the new ?status, and the
 // server returns ONLY the <webjs-frame id="tasks"> subtree (open the network tab
 // to see it). The router swaps that subtree in; everything outside the frame,
@@ -14,6 +20,10 @@
 // requirement. The frame element itself upgrades because the root layout ships a
 // component (the theme toggle), so @webjsdev/core and the router load app-wide.
 import { html } from '@webjsdev/core';
+import { cardClass } from '#components/ui/card.ts';
+import { buttonClass } from '#components/ui/button.ts';
+import { cn } from '#lib/utils/cn.ts';
+import { pageHeading, lede } from '#lib/utils/ui.ts';
 import type { Metadata } from '@webjsdev/core';
 import { filterTasks, normalizeStatus, type Status } from '#modules/frames/utils/tasks.ts';
 
@@ -24,10 +34,14 @@ export const metadata: Metadata = { title: 'Frames (webjs-frame partial swap) |
 // link OUTSIDE the frame would drive it from anywhere via data-webjs-frame="tasks".
 function filterTab(current: Status, status: Status, label: string) {
   const active = current === status;
-  const base = 'px-3 py-1.5 rounded-lg font-semibold text-sm no-underline transition-colors';
-  const cls = active
-    ? base + ' bg-primary text-primary-foreground'
-    : base + ' bg-card border border-border text-foreground font-medium hover:border-border-strong';
+  // A segmented control: keep ONE variant (constant weight, border, padding) so
+  // toggling the active tab never reflows the row, overriding only the active
+  // colors with cn().
+  const cls = cn(
+    buttonClass({ variant: 'secondary', size: 'sm' }),
+    'no-underline',
+    active && 'bg-primary text-primary-foreground border-primary hover:border-primary',
+  );
   return html`<a href="/features/frames?status=${status}" class=${cls}>${label}</a>`;
 }
 
@@ -35,14 +49,16 @@ export default function FramesExample({ searchParams }: { searchParams: Record<s
   const status = normalizeStatus(searchParams?.status);
   const tasks = filterTasks(status);
   return html`
-    <h1 class="text-h2 font-bold mb-4">Frames</h1>
-    <p class="text-muted-foreground mb-4">
+    ${pageHeading('Frames')}
+    ${lede(html`
       Filter the list. With JS on, only the framed region swaps (the response is
       just the frame's subtree, not the whole page) and the heading above never
       re-renders. With JS off, the same links do full-page navigations. It is one
-      region refreshing independently of a navigation, which a page cannot express.
-    </p>
-    <webjs-frame id="tasks" class="block p-4 rounded-2xl bg-card border border-border">
+      region refreshing independently of a navigation, which neither a page nor a
+      layout can express: a layout wraps routes with shared chrome and only
+      re-renders when you navigate, while a frame updates one region in place.
+    `)}
+    <webjs-frame id="tasks" class="${cardClass()} block p-4">
       <div class="flex gap-2 mb-4">
         ${filterTab(status, 'all', 'All')}
         ${filterTab(status, 'active', 'Active')}

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

@@ -0,0 +1,67 @@
+import { html } from '@webjsdev/core';
+import { backLink } from '#lib/utils/ui.ts';
+import '#modules/gallery/components/gallery-nav.ts';
+
+// A subtle, hover-revealed scrollbar for the sidebar (macOS overlay feel): the
+// track + thumb are transparent while idle (no bar), and fade in on hover /
+// keyboard focus, then fade out again. A layout may interpolate CSS into a
+// <style> (it never hydrates, unlike a component), so this is legitimate here.
+const SIDENAV_CSS = `
+  .gallery-sidenav { scrollbar-width: thin; scrollbar-color: transparent transparent; transition: scrollbar-color .2s ease; }
+  .gallery-sidenav:hover, .gallery-sidenav:focus-within { scrollbar-color: color-mix(in oklch, var(--foreground) 22%, transparent) transparent; }
+  .gallery-sidenav::-webkit-scrollbar { width: 8px; }
+  .gallery-sidenav::-webkit-scrollbar-track { background: transparent; }
+  .gallery-sidenav::-webkit-scrollbar-thumb { background-color: transparent; border-radius: 999px; border: 2px solid transparent; background-clip: padding-box; transition: background-color .2s ease; }
+  .gallery-sidenav:hover::-webkit-scrollbar-thumb, .gallery-sidenav:focus-within::-webkit-scrollbar-thumb { background-color: color-mix(in oklch, var(--foreground) 22%, transparent); }
+  .gallery-sidenav::-webkit-scrollbar-thumb:hover { background-color: color-mix(in oklch, var(--foreground) 40%, transparent); }
+`;
+
+// Section rhythm: ONE uniform gap between every top-level block of a demo
+// (heading, lede, paragraph, component, list, anything), so spacing stays
+// consistent with NO per-element margins. This is the single place that controls
+// demo spacing. A flex column with `gap` does it WITHOUT touching each child's
+// own display: a `grid`/`flex` child (like the forms card) keeps its layout, a
+// shadow-DOM host (inline by default) is blockified as a flex item so it honours
+// the gap, a display:contents <webjs-suspense> is replaced by its children (which
+// become the flex items and get the gap), and a display:none streaming
+// <script>/<template> is not an item at all (no phantom gap).
+const STACK_CSS = `
+  .demo-stack {
+    --section-gap: 1.5rem;
+    display: flex;
+    flex-direction: column;
+    gap: var(--section-gap);
+  }
+  /* Zero any BLOCK-axis margins so ONLY the flex gap spaces sections. Block
+     axis only: this style is unlayered so it beats Tailwind's layered
+     utilities, and a full margin: 0 would also kill mx-auto (an auth card's
+     horizontal centering). */
+  .demo-stack > * { margin-block: 0; }
+`;
+
+// Shared layout for every gallery feature demo under /features/*. A docs-style
+// two-column shell: a grouped sidebar (the <gallery-nav> component, which tracks
+// the active demo across soft navigation) plus the demo content. On mobile the
+// sidebar is hidden, so a slim back link keeps a demo from being a dead end.
+// Nested layouts (like the auth dashboard's sub-nav) render inside ${children}.
+// A non-root layout, so it never writes the document shell (the framework does).
+export default function FeaturesLayout({ children, url }: { children: unknown; url: URL | string }) {
+  const path = typeof url === 'string' ? new URL(url, 'http://x').pathname : url.pathname;
+  return html`
+    <style>${SIDENAV_CSS}${STACK_CSS}</style>
+    <div class="lg:hidden mb-6">${backLink('/', html`&larr; Gallery`)}</div>
+    <div class="grid lg:grid-cols-[190px_1fr] gap-8 lg:gap-12">
+      <!-- The sidebar caps at the viewport minus the root chrome (the h-14 navbar
+           = 3.5rem plus the root <main>'s py-8 = 4rem, so 7.5rem) and scrolls
+           internally, so a short demo never forces a page scrollbar. -->
+      <aside class="hidden lg:flex lg:flex-col sticky top-6 self-start max-h-[calc(100dvh-7.5rem)] text-sm">
+        <!-- Pinned header: stays put while the demo list below scrolls. -->
+        <a href="/" class="shrink-0 block px-3 py-1.5 mb-4 rounded-lg no-underline text-muted-foreground hover:text-foreground transition-colors">&larr; Gallery</a>
+        <div class="gallery-sidenav min-h-0 overflow-y-auto overflow-x-hidden -mr-2 pr-2">
+          <gallery-nav current=${path}></gallery-nav>
+        </div>
+      </aside>
+      <div class="min-w-0 demo-stack">${children}</div>
+    </div>
+  `;
+}

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

@@ -6,6 +6,7 @@
 // (sitemap.ts, robots.ts, opengraph-image.ts, ...) live at the app root.
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
+import { pageHeading, lede } from '#lib/utils/ui.ts';
 
 // 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;
@@ -31,20 +32,20 @@ export default function MetadataExample({
 }) {
   const topic = (searchParams.topic || '').trim();
   return html`
-    <h1 class="text-h2 font-bold mb-4">Metadata</h1>
-    <p class="text-muted-foreground mb-4">
+    ${pageHeading('Metadata')}
+    ${lede(html`
       <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>
+      <li><a class="text-primary underline underline-offset-2" href="/features/metadata?topic=webjs">?topic=webjs</a></li>
+      <li><a class="text-primary underline underline-offset-2" href="/features/metadata?topic=Routing">?topic=Routing</a></li>
+      <li><a class="text-primary underline underline-offset-2" 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

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

@@ -1,13 +1,14 @@
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
+import { pageHeading, lede } from '#lib/utils/ui.ts';
 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>
+    ${pageHeading('Optimistic UI')}
+    ${lede(html`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 underline underline-offset-2" href="/examples/todo">/examples/todo</a>.`)}
     <like-button></like-button>
   `;
 }

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

@@ -5,23 +5,24 @@
 // default; point the store at Redis to share the window across instances.
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
+import { pageHeading, lede } from '#lib/utils/ui.ts';
 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">
+    ${pageHeading('Rate limiting')}
+    ${lede(html`
       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">
+    <p class="text-muted-foreground text-sm">
       With JavaScript off, hit
-      <a class="text-primary" href="/features/rate-limit/ping" data-no-router>/features/rate-limit/ping</a>
+      <a class="text-primary underline underline-offset-2" 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/page.ts

@@ -1,14 +1,15 @@
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
+import { pageHeading, lede } from '#lib/utils/ui.ts';
 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>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>
+    ${pageHeading('Route handlers')}
+    ${lede(html`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>GET <a class="text-primary underline underline-offset-2" 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>
   `;