@webjsdev/cli 0.10.45 → 0.10.46

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

@@ -1,12 +1,67 @@
 import { html } from '@webjsdev/core';
+import { backLink } from '#lib/utils/ui.ts';
+import '#modules/gallery/components/gallery-nav.ts';
 
-// Shared layout for every gallery feature demo under /features/*. It adds a slim
-// "back to the gallery" link above each demo so a card is never a dead end.
+// 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 }: { children: unknown }) {
+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`
-    <a href="/" class="inline-flex items-center gap-1 text-sm text-muted-foreground hover:text-foreground transition-colors no-underline mb-6">&larr; Gallery</a>
-    ${children}
+    <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>
   `;

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

@@ -14,6 +14,7 @@
 // route literal that does not exist and it is a compile error.
 import { html, notFound } from '@webjsdev/core';
 import type { PageProps } from '@webjsdev/core';
+import { pageHeading } from '#lib/utils/ui.ts';
 
 export default async function RoutingParam({ params }: PageProps<'/features/routing/[id]'>) {
   // The Next-style await also works; `params.id` sync would be identical.
@@ -23,23 +24,23 @@ export default async function RoutingParam({ params }: PageProps<'/features/rout
   // 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>
+    ${pageHeading('Route param')}
     <p>The <code>[id]</code> segment is: <strong>${id}</strong></p>
-    <p class="text-muted-foreground text-sm mt-3">
+    <p class="text-muted-foreground text-sm">
       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.
       <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>
+    <p class="text-muted-foreground text-sm">
+      Throwing wins over rendering: <a class="text-primary underline underline-offset-2" 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
+      <a class="text-primary underline underline-offset-2" 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>
+    <p class="mt-3"><a class="text-primary underline underline-offset-2" href="/features/routing">Back</a></p>
   `;
 }

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

@@ -3,19 +3,20 @@
 // `params`. See app/features/routing/[id]/page.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: '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>
+    ${pageHeading('Routing')}
+    ${lede(html`A folder is a URL segment; a <code>[id]</code> folder is a dynamic param.`)}
     <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>
+      <li><a class="text-primary underline underline-offset-2" href="/features/routing/42">/features/routing/42</a></li>
+      <li><a class="text-primary underline underline-offset-2" href="/features/routing/hello">/features/routing/hello</a></li>
+      <li><a class="text-primary underline underline-offset-2" 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">
+    <p class="text-muted-foreground text-sm">
       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
@@ -23,7 +24,7 @@ export default function RoutingExample() {
       <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">
+    <p class="text-muted-foreground text-sm">
       Programmatic navigation is checked too:
       <code class="font-mono">navigate(url)</code> takes that
       <code class="font-mono">Route</code> union, so
@@ -43,13 +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">
+    <p class="text-muted-foreground text-sm">
       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.
+      <a class="text-primary underline underline-offset-2" href="/features/boundaries">Boundaries</a> demo.
     </p>
   `;
 }

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

@@ -1,23 +1,24 @@
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
+import { pageHeading, lede } from '#lib/utils/ui.ts';
 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>
+    ${pageHeading('Server actions')}
+    ${lede(html`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 class="text-muted-foreground mb-4">
       This action also declares <code class="font-mono">export const middleware</code>: a
       chain that runs around it on every boundary. The auth middleware reads the
-      real signed session (from the <a class="text-primary" href="/features/auth">auth card</a>) and
+      real signed session (from the <a class="text-primary underline underline-offset-2" href="/features/auth">auth card</a>) and
       sets the caller on the request context (read back with <code class="font-mono">actionContext()</code>),
       or 401s before the action runs. The action threads
       <code class="font-mono">actionSignal()</code>, the request AbortSignal, through
       its work so a client disconnect or a superseded render stops it early.
     </p>
-    <p class="text-muted-foreground mb-4 text-sm">Signed out, the greeter returns a real 401. <a class="text-primary" href="/features/auth/login">Sign in</a> first to see it succeed. (This card depends on the auth card; prune both together.)</p>
+    <p class="text-muted-foreground mb-4 text-sm">Signed out, the greeter returns a real 401. <a class="text-primary underline underline-offset-2" href="/features/auth/login">Sign in</a> first to see it succeed. (This card depends on the auth card; prune both together.)</p>
     <server-greeter></server-greeter>
   `;
 }

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

@@ -6,17 +6,18 @@
 // agent-docs/service-worker.md for the full recipe.
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
+import { pageHeading, lede } from '#lib/utils/ui.ts';
 
 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">
+    ${pageHeading('Service worker')}
+    ${lede(html`
       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();

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

@@ -5,14 +5,15 @@
 // browser. See modules/sessions/session-config.server.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: '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>
+    ${pageHeading('Sessions')}
+    ${lede(html`A per-segment <code>middleware.ts</code> applies <code>session()</code>; a <code>route.ts</code> reads it with <code>getSession(req)</code>.`)}
+    <p>GET <a class="text-primary underline underline-offset-2" 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">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/features/stream/page.ts

@@ -18,20 +18,21 @@
 // message applied with renderStream() from a WS handler, see the WebSockets card).
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
+import { pageHeading, lede } from '#lib/utils/ui.ts';
 import '#modules/stream/components/stream-demo.ts';
 
 export const metadata: Metadata = { title: 'Stream updates (webjs-stream) | features' };
 
 export default function StreamExample() {
   return html`
-    <h1 class="text-h2 font-bold mb-4">Stream updates</h1>
-    <p class="text-muted-foreground mb-4">
+    ${pageHeading('Stream updates')}
+    ${lede(html`
       <code class="font-mono">renderStream()</code> applies a
       <code class="font-mono">&lt;webjs-stream action="..." target="..."&gt;</code>
       payload: a surgical, element-level DOM update by id. Each button below mutates
       the live list in place, and the component never re-renders (contrast a frame,
       which swaps a whole region, and the client router, which swaps a whole page).
-    </p>
+    `)}
     <stream-demo></stream-demo>
     <p class="text-muted-foreground text-sm mt-6">
       The same grammar arrives over HTTP (a content-negotiated

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

@@ -7,20 +7,21 @@
 // the typed action mechanism, no hand-written fetch.
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
+import { pageHeading, lede } from '#lib/utils/ui.ts';
 import '#modules/streaming/components/token-stream.ts';
 
 export const metadata: Metadata = { title: 'Streaming actions (for await) | features' };
 
 export default function StreamingExample() {
   return html`
-    <h1 class="text-h2 font-bold mb-4">Streaming actions</h1>
-    <p class="text-muted-foreground mb-4">
+    ${pageHeading('Streaming actions')}
+    ${lede(html`
       A <code class="font-mono">'use server'</code> action that returns an
       <code class="font-mono">async function*</code> streams each
       <code class="font-mono">yield</code> over the single RPC response. The call
       site consumes it with <code class="font-mono">for await (const chunk of await streamTokens())</code>,
       so tokens render as they arrive instead of waiting for the whole result.
-    </p>
+    `)}
     <p class="text-muted-foreground mb-6 text-sm">
       Detection is on the return value (no config export), and a streamed result
       is never cached, ETagged, or seeded. The source generator is cancelled if

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

@@ -8,19 +8,20 @@
 // for fast data); reach for <webjs-suspense> when the data is genuinely slow.
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
+import { pageHeading, lede } from '#lib/utils/ui.ts';
 import '#modules/suspense/components/slow-fact.ts';
 
 export const metadata: Metadata = { title: 'Suspense boundary (<webjs-suspense>) | features' };
 
 export default function SuspenseExample() {
   return html`
-    <h1 class="text-h2 font-bold mb-4">Suspense boundary</h1>
-    <p class="text-muted-foreground mb-4">
+    ${pageHeading('Suspense boundary')}
+    ${lede(html`
       The slow component below is wrapped in
       <code class="font-mono">&lt;webjs-suspense&gt;</code>. Its fallback shows on
       the first byte and the resolved content streams in when the slow await
       settles. Reload to see the fallback, then the fact stream in.
-    </p>
+    `)}
     <p class="text-muted-foreground mb-6 text-sm">
       <code class="font-mono">.fallback</code> is a property hole (unquoted, per
       invariant 4). Contrast with the

package/templates/gallery/app/features/view-transitions/page.ts

@@ -8,6 +8,9 @@
 // across the swap: type into it, navigate, and your text survives the transition.
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
+import { inputClass } from '#components/ui/input.ts';
+import { pageHeading } from '#lib/utils/ui.ts';
 
 export const metadata: Metadata = {
   title: 'View transitions (soft-nav cross-fade) | features',
@@ -16,7 +19,7 @@ export const metadata: Metadata = {
 
 export default function ViewTransitionsExample() {
   return html`
-    <h1 class="text-h2 font-bold mb-4">View transitions</h1>
+    ${pageHeading('View transitions')}
     <div class="rounded-2xl bg-primary/10 border border-primary/30 p-6 mb-6">
       <p class="text-foreground m-0">Page one. Navigate to page two: with the
         <code class="font-mono">&lt;meta name="view-transition"&gt;</code> opt-in,
@@ -26,10 +29,10 @@ export default function ViewTransitionsExample() {
       <span class="text-muted-foreground text-sm">Type here, then navigate. This input is
         <code class="font-mono">data-webjs-permanent</code>, so its value survives the swap:</span>
       <input id="vt-note" data-webjs-permanent type="text" placeholder="type something…"
-        class="mt-2 block w-full max-w-sm rounded-xl border border-border bg-card px-4 py-2 text-foreground" />
+        class=${inputClass('mt-2 block max-w-sm')} />
     </label>
     <div class="flex gap-3 items-center">
-      <a href="/features/view-transitions/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/view-transitions/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">

package/templates/gallery/app/features/view-transitions/second/page.ts

@@ -4,6 +4,8 @@
 // across the swap: the text you typed on page one is still here.
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
+import { inputClass } from '#components/ui/input.ts';
+import { pageHeading } from '#lib/utils/ui.ts';
 
 export const metadata: Metadata = {
   title: 'View transitions: page two | features',
@@ -12,7 +14,7 @@ export const metadata: Metadata = {
 
 export default function ViewTransitionsSecond() {
   return html`
-    <h1 class="text-h2 font-bold mb-4">Page two</h1>
+    ${pageHeading('Page two')}
     <div class="rounded-2xl bg-foreground/5 border border-border p-6 mb-6">
       <p class="text-foreground m-0">You arrived with a cross-fade, no full
         reload. The input below is the same node from page one, regrafted across
@@ -21,7 +23,7 @@ export default function ViewTransitionsSecond() {
     <label class="block mb-6">
       <span class="text-muted-foreground text-sm">Its value persisted across the transition:</span>
       <input id="vt-note" data-webjs-permanent type="text" placeholder="type something…"
-        class="mt-2 block w-full max-w-sm rounded-xl border border-border bg-card px-4 py-2 text-foreground" />
+        class=${inputClass('mt-2 block max-w-sm')} />
     </label>
     <a href="/features/view-transitions" class="text-primary no-underline font-medium">&larr; Back to page one</a>
   `;

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

@@ -6,19 +6,20 @@
 // it does not collide with this page).
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
+import { pageHeading, lede } from '#lib/utils/ui.ts';
 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">
+    ${pageHeading('WebSockets')}
+    ${lede(html`
       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>
   `;
 }

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

@@ -1,6 +1,3 @@
-// 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
@@ -29,9 +26,9 @@ export default function GlobalError({ error }: { error: Error }) {
         <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; }
+          body { font: 16px/1.6 system-ui, sans-serif; margin: 0; display: grid; place-items: center; min-height: 100vh; background: #1e2226; color: #dee2e6; }
           main { max-width: 32rem; padding: 2rem; text-align: center; }
-          a { color: #ff8a3d; }
+          a { color: #94989c; }
         </style>
       </head>
       <body>

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

@@ -1,6 +1,3 @@
-// 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
@@ -8,14 +5,15 @@
 // 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';
+import { buttonClass } from '#components/ui/button.ts';
 
 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>
+      <p class="text-sm font-semibold uppercase tracking-wide text-primary">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>
+      <p class="mt-4 text-muted-foreground">We could not find the page you were looking for.</p>
+      <a href="/" class="${buttonClass()} mt-8 inline-block no-underline">Back to home</a>
     </main>
   `;
 }

package/templates/gallery/app/icon.ts

@@ -1,6 +1,3 @@
-// (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
@@ -9,8 +6,8 @@
 // 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>
+    <rect width="32" height="32" rx="7" fill="#1e2226"/>
+    <text x="16" y="22" font-family="system-ui, sans-serif" font-size="18" font-weight="700" fill="#94989c" 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

@@ -1,6 +1,3 @@
-// (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
@@ -13,7 +10,7 @@ export default function Manifest() {
     start_url: '/',
     display: 'standalone',
     background_color: '#ffffff',
-    theme_color: '#1c1613',
+    theme_color: '#1e2226',
     icons: [
       { src: '/favicon.svg', sizes: 'any', type: 'image/svg+xml' },
     ],

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

@@ -1,6 +1,3 @@
-// (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
@@ -9,9 +6,9 @@
 // `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>
+    <rect width="1200" height="630" fill="#1e2226"/>
+    <text x="80" y="330" font-family="system-ui, sans-serif" font-size="88" font-weight="700" fill="#dee2e6">My App</text>
+    <text x="80" y="410" font-family="system-ui, sans-serif" font-size="36" fill="#94989c">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' },