From b5b65faad4dc3d126192c0149e89a4beda87d5fd Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 11:54:07 +0530
Subject: [PATCH 01/73] feat: ship @webjsdev/ui class-helper primitives into
 the gallery scaffold

Add components/ui/{button,card,input,textarea,badge}.ts (the ui tier-1 class
helpers buttonClass/cardClass/inputClass/textareaClass/badgeClass) to the
gallery template, with the cn import rewritten to the scaffold's #lib/utils/cn.ts
alias. First step of the gallery design-system refactor (#1059).
---
 .../templates/gallery/components/ui/badge.ts  | 46 ++++++++++
 .../templates/gallery/components/ui/button.ts | 80 +++++++++++++++++
 .../templates/gallery/components/ui/card.ts   | 90 +++++++++++++++++++
 .../templates/gallery/components/ui/input.ts  | 38 ++++++++
 .../gallery/components/ui/textarea.ts         | 29 ++++++
 5 files changed, 283 insertions(+)
 create mode 100644 packages/cli/templates/gallery/components/ui/badge.ts
 create mode 100644 packages/cli/templates/gallery/components/ui/button.ts
 create mode 100644 packages/cli/templates/gallery/components/ui/card.ts
 create mode 100644 packages/cli/templates/gallery/components/ui/input.ts
 create mode 100644 packages/cli/templates/gallery/components/ui/textarea.ts

diff --git a/packages/cli/templates/gallery/components/ui/badge.ts b/packages/cli/templates/gallery/components/ui/badge.ts
new file mode 100644
index 000000000..894c222d5
--- /dev/null
+++ b/packages/cli/templates/gallery/components/ui/badge.ts
@@ -0,0 +1,46 @@
+/**
+ * Badge: small visual label. Tier-1 class helper; compose with any
+ * inline element (commonly `<span>` or `<a>` for linked badges).
+ *
+ * shadcn parity:
+ *   Badge (variant: default | secondary | destructive | outline | ghost | link)
+ *                                  → badgeClass({ variant })
+ *
+ * The `[a&]:hover:...` hover styles only apply when the element is an `<a>`,
+ * so a static `<span>` doesn't pick up an unwanted hover.
+ *
+ * A11y (required for accessible output): render a static badge as a plain
+ * <span> (not focusable, no tabindex). Only an interactive badge (an <a>
+ * or <button>) is focusable, and an icon-only one needs an aria-label.
+ *
+ * Design tokens used: --primary, --secondary, --destructive, --foreground,
+ * --accent, --border, --ring.
+ *
+ * @example
+ * ```html
+ * <span class=${badgeClass()}>New</span>
+ * <span class=${badgeClass({ variant: 'destructive' })}>Error</span>
+ * <a class=${badgeClass({ variant: 'link' })} href="/profile">@vivek</a>
+ * ```
+ */
+import { cn } from '#lib/utils/cn.ts';
+
+const BASE =
+  'inline-flex w-fit shrink-0 items-center justify-center gap-1 overflow-hidden rounded-full border border-transparent px-2 py-0.5 text-xs font-medium whitespace-nowrap transition-[color,box-shadow] focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 [&>svg]:pointer-events-none [&>svg]:size-3';
+
+const VARIANTS = {
+  default: 'bg-primary text-primary-foreground [a&]:hover:bg-primary/90',
+  secondary: 'bg-secondary text-secondary-foreground [a&]:hover:bg-secondary/90',
+  destructive:
+    'bg-destructive text-white focus-visible:ring-destructive/20 dark:bg-destructive/60 dark:focus-visible:ring-destructive/40 [a&]:hover:bg-destructive/90',
+  outline:
+    'border-border text-foreground [a&]:hover:bg-accent [a&]:hover:text-accent-foreground',
+  ghost: '[a&]:hover:bg-accent [a&]:hover:text-accent-foreground',
+  link: 'text-primary underline-offset-4 [a&]:hover:underline',
+} as const;
+
+export type BadgeVariant = keyof typeof VARIANTS;
+
+export function badgeClass(opts: { variant?: BadgeVariant } = {}): string {
+  return cn(BASE, VARIANTS[opts.variant ?? 'default']);
+}
diff --git a/packages/cli/templates/gallery/components/ui/button.ts b/packages/cli/templates/gallery/components/ui/button.ts
new file mode 100644
index 000000000..37e91431c
--- /dev/null
+++ b/packages/cli/templates/gallery/components/ui/button.ts
@@ -0,0 +1,80 @@
+/**
+ * Button: styled native `<button>`. Tier-1 class helper. Compose with a
+ * real `<button>` (or `<a>` for link-styled buttons) so form submission,
+ * focus, keyboard activation, and screen-reader semantics all "just work".
+ *
+ * shadcn parity:
+ *   Button (variant: default | destructive | outline | secondary | ghost | link)
+ *         (size:    default | xs | sm | lg | icon | icon-xs | icon-sm | icon-lg)
+ *                                            → buttonClass({ variant, size })
+ *
+ * shadcn React's `asChild` (Slot) prop has no equivalent here: just call
+ * `buttonClass(...)` and spread the classes onto whatever element you want.
+ *
+ * A11y (required for accessible output): an icon-only button (the `icon`,
+ * `icon-xs`, `icon-sm`, `icon-lg` sizes) has no visible text, so it MUST
+ * carry an accessible name via aria-label (or aria-labelledby). A button
+ * that opens an overlay should also set aria-haspopup and aria-expanded.
+ * Native <button> focus and keyboard activation are already correct.
+ *
+ * Design tokens used: --primary, --primary-foreground, --destructive,
+ * --secondary, --secondary-foreground, --accent, --accent-foreground,
+ * --background, --input, --ring.
+ *
+ * @example
+ * ```html
+ * <button class=${buttonClass()} type="submit">Save</button>
+ * <button class=${buttonClass({ variant: 'outline', size: 'sm' })}>Cancel</button>
+ * <button class=${buttonClass({ size: 'icon' })} aria-label="Settings">⚙</button>
+ * <a class=${buttonClass({ variant: 'link' })} href="/about">About</a>
+ * ```
+ */
+import { cn } from '#lib/utils/cn.ts';
+
+// cursor-pointer is on the BASE so every variant (default, outline,
+// ghost, link, …) gets the right hover affordance. Native <button>
+// defaults to the OS arrow cursor in Chromium and Firefox: fine for
+// native chrome but unusual for app buttons; shadcn's modern Button
+// has long since gravitated toward an explicit cursor-pointer in the
+// real world (see the open issue shadcn-ui/ui#1791). disabled:pointer-
+// events-none below already suppresses cursor on disabled buttons by
+// virtue of the element not receiving pointer events at all.
+const BASE =
+  "inline-flex shrink-0 cursor-pointer items-center justify-center gap-2 rounded-md text-sm font-medium whitespace-nowrap transition-all outline-none focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4";
+
+const VARIANTS = {
+  default: 'bg-primary text-primary-foreground hover:bg-primary/90',
+  destructive:
+    'bg-destructive text-white hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:bg-destructive/60 dark:focus-visible:ring-destructive/40',
+  outline:
+    'border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:border-input dark:bg-input/30 dark:hover:bg-input/50',
+  secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
+  ghost: 'hover:bg-accent hover:text-accent-foreground dark:hover:bg-accent/50',
+  link: 'text-primary underline-offset-4 hover:underline',
+} as const;
+
+const SIZES = {
+  default: 'h-9 px-4 py-2 has-[>svg]:px-3',
+  xs: "h-6 gap-1 rounded-md px-2 text-xs has-[>svg]:px-1.5 [&_svg:not([class*='size-'])]:size-3",
+  sm: 'h-8 gap-1.5 rounded-md px-3 has-[>svg]:px-2.5',
+  lg: 'h-10 rounded-md px-6 has-[>svg]:px-4',
+  icon: 'size-9',
+  'icon-xs': "size-6 rounded-md [&_svg:not([class*='size-'])]:size-3",
+  'icon-sm': 'size-8',
+  'icon-lg': 'size-10',
+} as const;
+
+export type ButtonVariant = keyof typeof VARIANTS;
+export type ButtonSize = keyof typeof SIZES;
+
+export interface ButtonClassOptions {
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+}
+
+/** Compose Tailwind classes for a button. Stable shape: object-arg, both optional. */
+export function buttonClass(opts: ButtonClassOptions = {}): string {
+  const variant = opts.variant ?? 'default';
+  const size = opts.size ?? 'default';
+  return cn(BASE, VARIANTS[variant], SIZES[size]);
+}
diff --git a/packages/cli/templates/gallery/components/ui/card.ts b/packages/cli/templates/gallery/components/ui/card.ts
new file mode 100644
index 000000000..b63e38a20
--- /dev/null
+++ b/packages/cli/templates/gallery/components/ui/card.ts
@@ -0,0 +1,90 @@
+/**
+ * Card: visual container. Tier-1 class helpers; compose with `<div>`
+ * (or any element) for each subpart.
+ *
+ * shadcn parity:
+ *   Card (size: default | sm)  → cardClass({ size })
+ *   CardHeader                 → cardHeaderClass()
+ *   CardTitle                  → cardTitleClass()
+ *   CardDescription            → cardDescriptionClass()
+ *   CardAction                 → cardActionClass()
+ *   CardContent                → cardContentClass()
+ *   CardFooter                 → cardFooterClass()
+ *
+ * Design tokens used: --card, --card-foreground, --muted-foreground, --border.
+ *
+ * @example
+ * ```html
+ * <div class=${cardClass()}>
+ *   <div class=${cardHeaderClass()}>
+ *     <div class=${cardTitleClass()}>Notifications</div>
+ *     <div class=${cardDescriptionClass()}>You have 3 unread messages.</div>
+ *     <div class=${cardActionClass()}>
+ *       <button class=${buttonClass({ variant: 'ghost', size: 'sm' })}>Mark all read</button>
+ *     </div>
+ *   </div>
+ *   <div class=${cardContentClass()}>
+ *     <p class="text-sm">Your weekly digest is ready to review.</p>
+ *   </div>
+ *   <div class=${cardFooterClass()}>
+ *     <button class=${buttonClass()}>Save</button>
+ *   </div>
+ * </div>
+ * ```
+ */
+
+export type CardSize = 'default' | 'sm';
+
+/**
+ * Card root. shadcn ships `size?: "default" | "sm"` on Card across
+ * 14/15 style families (only new-york-v4 omits it). The class string
+ * uses `group/card` so the header / title / content / footer helpers
+ * can read the parent card's data-size and adjust their own padding
+ * + gap.
+ *
+ * USAGE: pass size to cardClass AND set data-size="<size>" on the
+ * same host element so the group-data-[size=...]/card child rules
+ * fire. Set `data-slot="card"` for shadcn parity.
+ *
+ *   <div class=${cardClass({ size: 'sm' })} data-slot="card" data-size="sm">
+ *     <div class=${cardHeaderClass()}>...</div>
+ *     ...
+ *   </div>
+ *
+ * Sizes:
+ *   default: gap-6 / py-6 (shadcn new-york-v4 default)
+ *   sm:     gap-3 / py-3 (shadcn radix-nova + base-* defaults)
+ */
+export const cardClass = (opts: { size?: CardSize } = {}): string => {
+  const size = opts.size ?? 'default';
+  const base =
+    'group/card flex flex-col rounded-xl border bg-card text-card-foreground shadow-sm';
+  return size === 'sm' ? base + ' gap-3 py-3' : base + ' gap-6 py-6';
+};
+
+/**
+ * Card header: supports an optional `CardAction` slot via grid layout.
+ * group-data-[size=sm]/card rules pick up the compact layout when the
+ * root card carries data-size="sm".
+ */
+export const cardHeaderClass = (): string =>
+  '@container/card-header grid auto-rows-min grid-rows-[auto_auto] items-start gap-2 px-6 has-data-[slot=card-action]:grid-cols-[1fr_auto] [.border-b]:pb-6 group-data-[size=sm]/card:px-4 group-data-[size=sm]/card:gap-1 group-data-[size=sm]/card:[.border-b]:pb-3';
+
+/** Card title: heading text within the header. Smaller when card is data-size="sm". */
+export const cardTitleClass = (): string =>
+  'leading-none font-semibold group-data-[size=sm]/card:text-sm';
+
+/** Card description: subdued caption beneath the title. */
+export const cardDescriptionClass = (): string => 'text-sm text-muted-foreground';
+
+/** Card action: right-aligned controls inside the header (matches shadcn CardAction). */
+export const cardActionClass = (): string =>
+  'col-start-2 row-span-2 row-start-1 self-start justify-self-end';
+
+/** Card content: the main body region. Tighter padding when card is data-size="sm". */
+export const cardContentClass = (): string =>
+  'px-6 group-data-[size=sm]/card:px-4';
+
+/** Card footer: trailing controls or actions. Tighter padding when card is data-size="sm". */
+export const cardFooterClass = (): string =>
+  'flex items-center px-6 [.border-t]:pt-6 group-data-[size=sm]/card:px-4 group-data-[size=sm]/card:[.border-t]:pt-3';
diff --git a/packages/cli/templates/gallery/components/ui/input.ts b/packages/cli/templates/gallery/components/ui/input.ts
new file mode 100644
index 000000000..e8cf541ec
--- /dev/null
+++ b/packages/cli/templates/gallery/components/ui/input.ts
@@ -0,0 +1,38 @@
+/**
+ * Input: styled native `<input>`. Tier-1 class helper. Works with every
+ * input type (text, email, password, number, search, tel, url, date,
+ * time, file, color, …). Form submission, autocomplete, browser
+ * validation, and password managers all work because it IS the native
+ * input.
+ *
+ * shadcn parity:
+ *   Input  → inputClass()
+ *
+ * Pair with `<label class=${labelClass()} for="...">` and a hint paragraph
+ * (`<p class=${hintClass()} id="...-hint">`). Wrap all three in
+ * `<div class=${fieldClass()}>` for the canonical field rhythm.
+ *
+ * Design tokens used: --input, --background, --primary, --primary-foreground,
+ * --muted-foreground, --foreground, --ring, --destructive.
+ *
+ * @example
+ * ```html
+ * <input class=${inputClass()} type="email" name="email" id="email" required
+ *        aria-describedby="email-hint">
+ * ```
+ */
+import { cn } from '#lib/utils/cn.ts';
+
+const INPUT_BASE =
+  'h-9 w-full min-w-0 rounded-md border border-input bg-transparent px-3 py-1 text-base shadow-xs transition-[color,box-shadow] outline-none selection:bg-primary selection:text-primary-foreground file:inline-flex file:h-7 file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground placeholder:text-muted-foreground disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 md:text-sm dark:bg-input/30';
+
+const INPUT_FOCUS =
+  'focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50';
+
+const INPUT_INVALID =
+  'aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40';
+
+/** Compose Tailwind classes for a native `<input>`. */
+export function inputClass(): string {
+  return cn(INPUT_BASE, INPUT_FOCUS, INPUT_INVALID);
+}
diff --git a/packages/cli/templates/gallery/components/ui/textarea.ts b/packages/cli/templates/gallery/components/ui/textarea.ts
new file mode 100644
index 000000000..a5794a35b
--- /dev/null
+++ b/packages/cli/templates/gallery/components/ui/textarea.ts
@@ -0,0 +1,29 @@
+/**
+ * Textarea: styled native `<textarea>`. Tier-1 class helper. Real
+ * multi-line input: form submission, autosize via `field-sizing:
+ * content`, and native validation all work.
+ *
+ * shadcn parity:
+ *   Textarea  → textareaClass()
+ *
+ * Pair with `<label class=${labelClass()} for="...">` and wrap in
+ * `<div class=${fieldClass()}>` for the canonical field rhythm.
+ *
+ * Design tokens used: --input, --background, --muted-foreground, --ring,
+ * --destructive.
+ *
+ * @example
+ * ```html
+ * <textarea class=${textareaClass()} name="message" rows="4" placeholder="Your message">
+ * </textarea>
+ * ```
+ */
+import { cn } from '#lib/utils/cn.ts';
+
+const TEXTAREA_BASE =
+  'flex field-sizing-content min-h-16 w-full rounded-md border border-input bg-transparent px-3 py-2 text-base shadow-xs transition-[color,box-shadow] outline-none placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 md:text-sm dark:bg-input/30 dark:aria-invalid:ring-destructive/40';
+
+/** Compose Tailwind classes for a native `<textarea>`. */
+export function textareaClass(): string {
+  return cn(TEXTAREA_BASE);
+}

From 7bc33aadce6adaf08fdccdece93ca53b8f2e0d86 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 12:05:31 +0530
Subject: [PATCH 02/73] feat: theme the gallery button helper and convert every
 demo button

Rewrite components/ui/button.ts into the gallery's themed design token (the
own-and-theme @webjsdev/ui model): a variant scale (default/secondary/ghost/
link) + size scale (default/sm/xs/none) whose class values reproduce the
gallery's existing look (rounded-xl primary, card-surfaced secondary, muted
link), with dense teaching comments on WHY a class helper (no indirection, one
source of truth, the #1057 cursor gap becomes impossible) and HOW to theme it.

Convert every light-DOM gallery button (~25 sites across 15 files, plus the
stream-demo shared const) from hand-rolled inline Tailwind to
buttonClass({ variant, size }). Bespoke toggles (todo checkbox/delete, the
like pill) and shadow-DOM demos are left as-is. All feature pages render and
webjs check passes.
---
 .../app/features/auth/dashboard/layout.ts     |  3 +-
 .../gallery/app/features/auth/login/page.ts   |  3 +-
 .../gallery/app/features/auth/signup/page.ts  |  3 +-
 .../gallery/app/features/file-storage/page.ts |  3 +-
 .../gallery/app/features/forms/page.ts        |  3 +-
 .../templates/gallery/components/ui/button.ts | 99 +++++++++----------
 .../broadcast/components/broadcast-feed.ts    |  3 +-
 .../caching/components/cache-buster.ts        |  3 +-
 .../components/router-controls.ts             |  7 +-
 .../components/components/counter-card.ts     |  3 +-
 .../components/components/task-loader.ts      |  3 +-
 .../components/components/theme-context.ts    |  5 +-
 .../directives/components/directive-demo.ts   | 19 ++--
 .../rate-limit/components/rate-probe.ts       |  3 +-
 .../route-handler/components/rich-data.ts     |  3 +-
 .../server-actions/components/greeter.ts      |  3 +-
 .../modules/stream/components/stream-demo.ts  |  3 +-
 .../streaming/components/token-stream.ts      |  3 +-
 .../modules/todo/components/todo-app.ts       |  3 +-
 .../modules/websockets/components/ws-echo.ts  |  5 +-
 20 files changed, 99 insertions(+), 81 deletions(-)

diff --git a/packages/cli/templates/gallery/app/features/auth/dashboard/layout.ts b/packages/cli/templates/gallery/app/features/auth/dashboard/layout.ts
index 7b4263af6..47da8bbb9 100644
--- a/packages/cli/templates/gallery/app/features/auth/dashboard/layout.ts
+++ b/packages/cli/templates/gallery/app/features/auth/dashboard/layout.ts
@@ -1,4 +1,5 @@
 import { html } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
 
 // Nested layout for the protected dashboard subtree. Logout is a plain
 // <form method="POST"> posting to the createAuth signout route: it clears the
@@ -12,7 +13,7 @@ export default function DashboardLayout({ children }: { children: unknown }) {
       <a href="/features/auth/dashboard" class="text-sm font-medium text-foreground hover:underline">Dashboard</a>
       <a href="/features/auth/dashboard/settings" class="text-sm font-medium text-foreground hover:underline">Settings</a>
       <form method="POST" action="/api/auth/signout" class="ml-auto">
-        <button type="submit" class="px-3 py-1.5 rounded-lg border border-border text-sm text-foreground bg-transparent cursor-pointer transition-colors hover:bg-accent">Log out</button>
+        <button type="submit" class=${buttonClass({ variant: 'secondary', size: 'sm' })}>Log out</button>
       </form>
     </nav>
     ${children}
diff --git a/packages/cli/templates/gallery/app/features/auth/login/page.ts b/packages/cli/templates/gallery/app/features/auth/login/page.ts
index b74ab9ae0..2c247da19 100644
--- a/packages/cli/templates/gallery/app/features/auth/login/page.ts
+++ b/packages/cli/templates/gallery/app/features/auth/login/page.ts
@@ -1,4 +1,5 @@
 import { html } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
 
 export const metadata = { title: 'Log in' };
 
@@ -32,7 +33,7 @@ export default function LoginPage({ searchParams }: { searchParams: { error?: st
           <label for="password" class="text-[13px] font-medium text-muted-foreground">Password</label>
           <input id="password" name="password" type="password" required class=${inputCls} />
         </div>
-        <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]">Sign in</button>
+        <button type="submit" class="${buttonClass()} justify-self-start">Sign in</button>
       </form>
       <p class="text-sm text-muted-foreground mt-4">Don't have an account? <a href="/features/auth/signup" class="text-primary">Sign up</a></p>
     </div>
diff --git a/packages/cli/templates/gallery/app/features/auth/signup/page.ts b/packages/cli/templates/gallery/app/features/auth/signup/page.ts
index 4ad1597db..b969d0f0f 100644
--- a/packages/cli/templates/gallery/app/features/auth/signup/page.ts
+++ b/packages/cli/templates/gallery/app/features/auth/signup/page.ts
@@ -1,4 +1,5 @@
 import { html } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
 import { signup } from '#modules/auth/actions/signup.server.ts';
 
 export const metadata = { title: 'Sign up' };
@@ -50,7 +51,7 @@ export default function SignupPage({ actionData }: { actionData?: { fieldErrors?
           <input id="password" name="password" type="password" minlength="8" required class=${inputCls} />
           ${errors.password ? html`<p class="m-0 text-[12.5px] text-destructive">${errors.password}</p>` : ''}
         </div>
-        <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]">Create account</button>
+        <button type="submit" class="${buttonClass()} justify-self-start">Create account</button>
       </form>
       <p class="text-sm text-muted-foreground mt-4">Already have an account? <a href="/features/auth/login" class="text-primary">Log in</a></p>
     </div>
diff --git a/packages/cli/templates/gallery/app/features/file-storage/page.ts b/packages/cli/templates/gallery/app/features/file-storage/page.ts
index 5e1d2db2e..ce85850da 100644
--- a/packages/cli/templates/gallery/app/features/file-storage/page.ts
+++ b/packages/cli/templates/gallery/app/features/file-storage/page.ts
@@ -5,6 +5,7 @@
 // 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 type { Metadata } from '@webjsdev/core';
 import { storeUpload } from '#modules/file-storage/actions/store-upload.server.ts';
 
@@ -44,7 +45,7 @@ export default function FileStorageExample({
       <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>`
diff --git a/packages/cli/templates/gallery/app/features/forms/page.ts b/packages/cli/templates/gallery/app/features/forms/page.ts
index 940ccbaa8..4c56a7b48 100644
--- a/packages/cli/templates/gallery/app/features/forms/page.ts
+++ b/packages/cli/templates/gallery/app/features/forms/page.ts
@@ -6,6 +6,7 @@
 // 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 { buttonClass } from '#components/ui/button.ts';
 import type { Metadata } from '@webjsdev/core';
 
 export const metadata: Metadata = { title: 'Forms (no-JS PE) | features' };
@@ -49,7 +50,7 @@ export default function FormsFeature({ searchParams, actionData }: { searchParam
       ${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>
   `;
 }
diff --git a/packages/cli/templates/gallery/components/ui/button.ts b/packages/cli/templates/gallery/components/ui/button.ts
index 37e91431c..28e323920 100644
--- a/packages/cli/templates/gallery/components/ui/button.ts
+++ b/packages/cli/templates/gallery/components/ui/button.ts
@@ -1,67 +1,62 @@
 /**
- * Button: styled native `<button>`. Tier-1 class helper. Compose with a
- * real `<button>` (or `<a>` for link-styled buttons) so form submission,
- * focus, keyboard activation, and screen-reader semantics all "just work".
+ * buttonClass: the gallery's button design token, built on @webjsdev/ui.
  *
- * shadcn parity:
- *   Button (variant: default | destructive | outline | secondary | ghost | link)
- *         (size:    default | xs | sm | lg | icon | icon-xs | icon-sm | icon-lg)
- *                                            → buttonClass({ variant, size })
+ * This is a `@webjsdev/ui` tier-1 CLASS HELPER (the shadcn model): instead of a
+ * `<ui-button>` wrapper element, it returns a Tailwind class string you spread
+ * onto a NATIVE `<button>` (or `<a>` for a link-styled button). Native markup
+ * means form submission, focus, keyboard activation, and screen-reader
+ * semantics all work with no extra wiring:
  *
- * shadcn React's `asChild` (Slot) prop has no equivalent here: just call
- * `buttonClass(...)` and spread the classes onto whatever element you want.
+ *   <button class=${buttonClass()} @click=${...}>Save</button>
+ *   <button class=${buttonClass({ variant: 'secondary', size: 'sm' })}>Cancel</button>
+ *   <a      class=${buttonClass({ variant: 'link', size: 'none' })} href="/x">More</a>
  *
- * A11y (required for accessible output): an icon-only button (the `icon`,
- * `icon-xs`, `icon-sm`, `icon-lg` sizes) has no visible text, so it MUST
- * carry an accessible name via aria-label (or aria-labelledby). A button
- * that opens an overlay should also set aria-haspopup and aria-expanded.
- * Native <button> focus and keyboard activation are already correct.
+ * WHY a helper and not a component: the class helper adds NO indirection, so a
+ * demo's real markup (the `@click`, the `?disabled`, the concept it teaches)
+ * stays fully visible, while every button in the gallery shares one source of
+ * truth for its look. That is also why the #1057-style "one button forgot
+ * cursor-pointer" gap cannot happen: `cursor-pointer` lives on BASE.
  *
- * Design tokens used: --primary, --primary-foreground, --destructive,
- * --secondary, --secondary-foreground, --accent, --accent-foreground,
- * --background, --input, --ring.
+ * OWN-AND-THEME your copy: this file is `webjs ui add button` output THEMED to
+ * this scaffold's look (rounded-xl, the primary / card / muted-link styles the
+ * gallery uses). That is the intended `@webjsdev/ui` workflow: you own the
+ * component file and tune its class values to your brand. Run
+ * `webjs ui add button` (or edit here) to change the button system app-wide.
  *
- * @example
- * ```html
- * <button class=${buttonClass()} type="submit">Save</button>
- * <button class=${buttonClass({ variant: 'outline', size: 'sm' })}>Cancel</button>
- * <button class=${buttonClass({ size: 'icon' })} aria-label="Settings">⚙</button>
- * <a class=${buttonClass({ variant: 'link' })} href="/about">About</a>
- * ```
+ * A11y: an icon-only button has no visible text, so give it an `aria-label`.
+ * Native `<button>` focus + keyboard activation are already correct.
+ *
+ * Design tokens used (defined in app/layout.ts): --color-primary,
+ * --color-primary-foreground, --color-card, --color-border, --color-foreground,
+ * --color-muted-foreground, --color-accent, --color-ring.
  */
 import { cn } from '#lib/utils/cn.ts';
 
-// cursor-pointer is on the BASE so every variant (default, outline,
-// ghost, link, …) gets the right hover affordance. Native <button>
-// defaults to the OS arrow cursor in Chromium and Firefox: fine for
-// native chrome but unusual for app buttons; shadcn's modern Button
-// has long since gravitated toward an explicit cursor-pointer in the
-// real world (see the open issue shadcn-ui/ui#1791). disabled:pointer-
-// events-none below already suppresses cursor on disabled buttons by
-// virtue of the element not receiving pointer events at all.
+// BASE: shared by every variant + size, so a fix here (e.g. the focus ring, or
+// cursor-pointer) applies to the whole button system at once.
 const BASE =
-  "inline-flex shrink-0 cursor-pointer items-center justify-center gap-2 rounded-md text-sm font-medium whitespace-nowrap transition-all outline-none focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4";
+  'inline-flex shrink-0 cursor-pointer items-center justify-center gap-2 whitespace-nowrap text-sm transition-all outline-none focus-visible:ring-2 focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-60';
 
+// VARIANTS carry COLOR + weight + hover (what the button IS). Add a variant here
+// and it is instantly available to every demo.
 const VARIANTS = {
-  default: 'bg-primary text-primary-foreground hover:bg-primary/90',
-  destructive:
-    'bg-destructive text-white hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:bg-destructive/60 dark:focus-visible:ring-destructive/40',
-  outline:
-    'border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:border-input dark:bg-input/30 dark:hover:bg-input/50',
-  secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
-  ghost: 'hover:bg-accent hover:text-accent-foreground dark:hover:bg-accent/50',
-  link: 'text-primary underline-offset-4 hover:underline',
+  // The filled call-to-action (Send, Upload, Stream tokens, Greet).
+  default: 'bg-primary text-primary-foreground font-semibold hover:bg-primary/90 active:scale-[0.97]',
+  // The quieter card-surfaced action (Reset, Read once, secondary controls).
+  secondary: 'bg-card border border-border text-foreground font-medium hover:border-border-strong',
+  // Transparent until hovered (a toolbar / menu action, e.g. Log out).
+  ghost: 'bg-transparent text-foreground font-medium hover:bg-accent',
+  // A button that reads as an inline text link (navigate, toggle, reveal).
+  link: 'text-muted-foreground font-medium underline decoration-dotted underline-offset-4 hover:text-foreground',
 } as const;
 
+// SIZES carry SHAPE (padding + radius). `none` is for the link variant, which
+// is inline text and takes no box padding.
 const SIZES = {
-  default: 'h-9 px-4 py-2 has-[>svg]:px-3',
-  xs: "h-6 gap-1 rounded-md px-2 text-xs has-[>svg]:px-1.5 [&_svg:not([class*='size-'])]:size-3",
-  sm: 'h-8 gap-1.5 rounded-md px-3 has-[>svg]:px-2.5',
-  lg: 'h-10 rounded-md px-6 has-[>svg]:px-4',
-  icon: 'size-9',
-  'icon-xs': "size-6 rounded-md [&_svg:not([class*='size-'])]:size-3",
-  'icon-sm': 'size-8',
-  'icon-lg': 'size-10',
+  default: 'px-4 py-2 rounded-xl',
+  sm: 'px-3.5 py-1.5 rounded-xl',
+  xs: 'px-3 py-1 rounded-lg',
+  none: '',
 } as const;
 
 export type ButtonVariant = keyof typeof VARIANTS;
@@ -72,7 +67,11 @@ export interface ButtonClassOptions {
   size?: ButtonSize;
 }
 
-/** Compose Tailwind classes for a button. Stable shape: object-arg, both optional. */
+/**
+ * Compose the Tailwind classes for a button. Both options are optional
+ * (`buttonClass()` is the primary call-to-action). `cn` de-duplicates, so you
+ * can append your own layout classes: `class="${buttonClass()} w-full"`.
+ */
 export function buttonClass(opts: ButtonClassOptions = {}): string {
   const variant = opts.variant ?? 'default';
   const size = opts.size ?? 'default';
diff --git a/packages/cli/templates/gallery/modules/broadcast/components/broadcast-feed.ts b/packages/cli/templates/gallery/modules/broadcast/components/broadcast-feed.ts
index de6aae69c..620c57543 100644
--- a/packages/cli/templates/gallery/modules/broadcast/components/broadcast-feed.ts
+++ b/packages/cli/templates/gallery/modules/broadcast/components/broadcast-feed.ts
@@ -4,6 +4,7 @@
 // closes in disconnectedCallback. At SSR it renders the disconnected state, so
 // the page still reads with JS off (a live feed has no no-JS equivalent).
 import { WebComponent, signal, html, connectWS } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
 
 export class BroadcastFeed extends WebComponent {
   private connected = signal(false);
@@ -47,7 +48,7 @@ export class BroadcastFeed extends WebComponent {
           <input name="msg" autocomplete="off" placeholder="Message everyone"
             class="flex-1 px-3 py-2 rounded-xl bg-card border border-border text-foreground text-sm outline-none focus:border-border-strong" />
           <button type="submit"
-            class="px-3.5 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</button>
+            class=${buttonClass({ size: 'sm' })}>Send</button>
         </form>
         <ul class="grid gap-1.5 list-none m-0 p-0">
           ${this.lines.get().map((line) => html`
diff --git a/packages/cli/templates/gallery/modules/caching/components/cache-buster.ts b/packages/cli/templates/gallery/modules/caching/components/cache-buster.ts
index f9ab22991..7f1c37933 100644
--- a/packages/cli/templates/gallery/modules/caching/components/cache-buster.ts
+++ b/packages/cli/templates/gallery/modules/caching/components/cache-buster.ts
@@ -3,6 +3,7 @@
 // button is inert (cache eviction there happens as a side effect of the write
 // action that changed the data).
 import { WebComponent, signal, html } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
 import { bustCaches } from '#modules/caching/actions/bust-caches.server.ts';
 
 export class CacheBuster extends WebComponent {
@@ -21,7 +22,7 @@ export class CacheBuster extends WebComponent {
     return html`
       <div class="flex items-center gap-3 text-[15px]">
         <button @click=${() => this.bust()}
-          class="px-3.5 py-1.5 rounded-xl bg-card border border-border text-foreground text-sm cursor-pointer transition-colors hover:border-border-strong">revalidate this page</button>
+          class=${buttonClass({ variant: 'secondary', size: 'sm' })}>revalidate this page</button>
         <span class="text-muted-foreground">${this.status.get()}</span>
       </div>
     `;
diff --git a/packages/cli/templates/gallery/modules/client-router/components/router-controls.ts b/packages/cli/templates/gallery/modules/client-router/components/router-controls.ts
index f04a1cec4..1528016d8 100644
--- a/packages/cli/templates/gallery/modules/client-router/components/router-controls.ts
+++ b/packages/cli/templates/gallery/modules/client-router/components/router-controls.ts
@@ -12,6 +12,7 @@
 // home; a page/layout never hydrates. With JS off the plain link still works
 // (progressive enhancement), while the buttons are inert.
 import { WebComponent, html, signal, navigate, revalidate, disableClientRouter, enableClientRouter } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
 
 export class RouterControls extends WebComponent {
   // Instance signal mirroring whether soft navigation is currently on.
@@ -30,13 +31,13 @@ export class RouterControls extends WebComponent {
         <div class="flex flex-wrap gap-3 items-center">
           <button
             @click=${() => navigate('/features/client-router/second')}
-            class="inline-flex items-center px-4 py-2 rounded-xl bg-card border border-border text-foreground font-medium text-sm cursor-pointer transition-colors hover:border-border-strong">navigate() to page two</button>
+            class=${buttonClass({ variant: 'secondary' })}>navigate() to page two</button>
           <button
             @click=${() => revalidate()}
-            class="text-muted-foreground font-medium text-sm cursor-pointer transition-colors hover:text-foreground underline decoration-dotted underline-offset-4">revalidate() the snapshot cache</button>
+            class=${buttonClass({ variant: 'link', size: 'none' })}>revalidate() the snapshot cache</button>
           <button
             @click=${() => this.toggleRouter()}
-            class="text-muted-foreground font-medium text-sm cursor-pointer transition-colors hover:text-foreground underline decoration-dotted underline-offset-4">${soft ? 'disableClientRouter()' : 'enableClientRouter()'} (soft nav: ${soft ? 'on' : 'off'})</button>
+            class=${buttonClass({ variant: 'link', size: 'none' })}>${soft ? 'disableClientRouter()' : 'enableClientRouter()'} (soft nav: ${soft ? 'on' : 'off'})</button>
         </div>
         <p class="text-sm text-muted-foreground">
           Plain link:
diff --git a/packages/cli/templates/gallery/modules/components/components/counter-card.ts b/packages/cli/templates/gallery/modules/components/components/counter-card.ts
index 394120470..4633253d0 100644
--- a/packages/cli/templates/gallery/modules/components/components/counter-card.ts
+++ b/packages/cli/templates/gallery/modules/components/components/counter-card.ts
@@ -4,6 +4,7 @@
 // component authoring shape. Styling is crafted Tailwind on the app's design
 // tokens so it stays visually coherent with the rest of the app.
 import { WebComponent, prop, signal, html } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
 
 export class CounterCard extends WebComponent({
   // A reactive prop rides an HTML attribute / SSR hydration. Declared ONLY here
@@ -27,7 +28,7 @@ export class CounterCard extends WebComponent({
           <span class="text-sm text-muted-foreground">${this.label}</span>
         </div>
         <button @click=${() => this.count.set(this.count.get() + 1)}
-          class="w-fit 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]">Increment</button>
+          class="${buttonClass()} w-fit">Increment</button>
       </div>
     `;
   }
diff --git a/packages/cli/templates/gallery/modules/components/components/task-loader.ts b/packages/cli/templates/gallery/modules/components/components/task-loader.ts
index 9fcb04ffc..2e41f0f8b 100644
--- a/packages/cli/templates/gallery/modules/components/components/task-loader.ts
+++ b/packages/cli/templates/gallery/modules/components/components/task-loader.ts
@@ -6,6 +6,7 @@
 // `async render()` instead, which blocks SSR so the data is server-rendered;
 // a Task shows its PENDING state at SSR, so the value is not in the first paint.
 import { WebComponent, html } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
 import { Task, TaskStatus } from '@webjsdev/core/task';
 
 export class TaskLoader extends WebComponent {
@@ -39,7 +40,7 @@ export class TaskLoader extends WebComponent {
     return html`
       <div class="flex items-center gap-3 text-[15px]">
         <button @click=${() => this.reload()}
-          class="px-3.5 py-1.5 rounded-xl bg-card border border-border text-foreground text-sm cursor-pointer transition-colors hover:border-border-strong">reload</button>
+          class=${buttonClass({ variant: 'secondary', size: 'sm' })}>reload</button>
         ${body}
       </div>
     `;
diff --git a/packages/cli/templates/gallery/modules/components/components/theme-context.ts b/packages/cli/templates/gallery/modules/components/components/theme-context.ts
index bb356a691..5c6995c6e 100644
--- a/packages/cli/templates/gallery/modules/components/components/theme-context.ts
+++ b/packages/cli/templates/gallery/modules/components/components/theme-context.ts
@@ -7,6 +7,7 @@
 // controllers automate. All light DOM, so the provider's <slot> projects its
 // children normally.
 import { WebComponent, html, signal } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
 import { createContext, ContextProvider, ContextConsumer, ContextRequestEvent } from '@webjsdev/core/context';
 
 type Theme = 'light' | 'dark';
@@ -28,7 +29,7 @@ export class ThemeProvider extends WebComponent {
     return html`
       <div class="grid gap-3 p-3 rounded-xl bg-card border border-border max-w-[420px]">
         <button @click=${() => this.toggle()}
-          class="w-fit px-3.5 py-1.5 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]">
+          class="${buttonClass({ size: 'sm' })} w-fit">
           provider theme: ${this.provider.value} (toggle)
         </button>
         <slot></slot>
@@ -58,7 +59,7 @@ export class ThemeConsumer extends WebComponent {
       <div class="flex items-center gap-3 text-[15px] text-foreground">
         <span>child sees: <strong>${theme}</strong></span>
         <button @click=${() => this.readOnce()}
-          class="px-3 py-1 rounded-lg text-sm bg-card border border-border text-foreground cursor-pointer transition-colors hover:border-border-strong">read once</button>
+          class=${buttonClass({ variant: 'secondary', size: 'xs' })}>read once</button>
         <span class="text-muted-foreground text-sm">last one-shot: ${this.lastRead.get()}</span>
       </div>
     `;
diff --git a/packages/cli/templates/gallery/modules/directives/components/directive-demo.ts b/packages/cli/templates/gallery/modules/directives/components/directive-demo.ts
index 6e8a33366..3e3537555 100644
--- a/packages/cli/templates/gallery/modules/directives/components/directive-demo.ts
+++ b/packages/cli/templates/gallery/modules/directives/components/directive-demo.ts
@@ -12,6 +12,7 @@
 // HTML), and `asyncAppend` / `asyncReplace` (stream values from an async
 // iterable, appending each or replacing with the latest).
 import { WebComponent, signal, html } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
 import { repeat, watch, live, until, keyed, unsafeHTML, ref, createRef, guard, cache, templateContent, asyncAppend, asyncReplace } from '@webjsdev/core/directives';
 
 interface Item { id: number; label: string }
@@ -107,9 +108,9 @@ export class DirectiveDemo extends WebComponent {
         <div class="grid gap-4">
           <div class="flex gap-2">
             <button @click=${() => this.reverse()}
-              class="px-3.5 py-1.5 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]">Reverse</button>
+              class=${buttonClass({ size: 'sm' })}>Reverse</button>
             <button @click=${() => this.add()}
-              class="px-3.5 py-1.5 rounded-xl bg-card border border-border text-foreground font-medium text-sm cursor-pointer transition-colors hover:border-border-strong">Add</button>
+              class=${buttonClass({ variant: 'secondary', size: 'sm' })}>Add</button>
           </div>
           <!-- repeat keyed by item.id: reversing reuses the existing <li> nodes. -->
           <ul class="grid gap-2 list-none m-0 p-0">
@@ -121,7 +122,7 @@ export class DirectiveDemo extends WebComponent {
           </ul>
           <!-- watch(signal) swaps only this node when ticks changes. -->
           <button @click=${() => this.ticks.set(this.ticks.get() + 1)}
-            class="w-fit text-sm text-muted-foreground cursor-pointer transition-colors hover:text-foreground underline decoration-dotted underline-offset-4">ticks: ${watch(this.ticks)}</button>
+            class="${buttonClass({ variant: 'link', size: 'none' })} w-fit">ticks: ${watch(this.ticks)}</button>
         </div>
 
         <div class="grid gap-3 border-t border-border pt-4">
@@ -136,14 +137,14 @@ export class DirectiveDemo extends WebComponent {
               .value=${live(this.text.get())}
               @input=${(e: Event) => this.text.set((e.target as HTMLInputElement).value)}>
             <button @click=${() => this.focusInput()}
-              class="px-3.5 py-1.5 rounded-xl bg-card border border-border text-foreground text-sm cursor-pointer transition-colors hover:border-border-strong">Focus</button>
+              class=${buttonClass({ variant: 'secondary', size: 'sm' })}>Focus</button>
           </div>
           <!-- until shows the fallback until the promise resolves. -->
           <p class="text-sm text-muted-foreground">async: ${until(this.asyncValue, 'loading...')}</p>
           <!-- keyed discards and rebuilds this subtree when the key changes;
                unsafeHTML injects trusted, author-written HTML (NEVER user input). -->
           <button @click=${() => this.variant.set(variant + 1)}
-            class="w-fit text-sm text-muted-foreground cursor-pointer transition-colors hover:text-foreground underline decoration-dotted underline-offset-4">rekey</button>
+            class="${buttonClass({ variant: 'link', size: 'none' })} w-fit">rekey</button>
           ${keyed(variant, html`<div class="text-[15px] text-foreground">${unsafeHTML('<em>fresh subtree</em>')} #${variant}</div>`)}
         </div>
 
@@ -152,16 +153,16 @@ export class DirectiveDemo extends WebComponent {
                guard counter re-renders it; the OTHER counter (ticks above) does
                not, so the guarded value stays put. -->
           <button @click=${() => this.guardBumps.set(this.guardBumps.get() + 1)}
-            class="w-fit text-sm text-muted-foreground cursor-pointer transition-colors hover:text-foreground underline decoration-dotted underline-offset-4">bump guard dep</button>
+            class="${buttonClass({ variant: 'link', size: 'none' })} w-fit">bump guard dep</button>
           <p class="text-sm text-foreground">guarded: ${guard([this.guardBumps.get()], () => html`computed at bump #${this.guardBumps.get()}`)}</p>
 
           <!-- cache(value) keeps the inactive tab's DOM alive while you toggle,
                so switching back is instant and preserves any element state. -->
           <div class="flex gap-2">
             <button @click=${() => this.tab.set('a')}
-              class="px-3 py-1 rounded-lg text-sm border cursor-pointer transition-colors ${this.tab.get() === 'a' ? 'bg-primary text-primary-foreground border-transparent' : 'bg-card border-border text-foreground hover:border-border-strong'}">Tab A</button>
+              class=${buttonClass({ variant: this.tab.get() === 'a' ? 'default' : 'secondary', size: 'xs' })}>Tab A</button>
             <button @click=${() => this.tab.set('b')}
-              class="px-3 py-1 rounded-lg text-sm border cursor-pointer transition-colors ${this.tab.get() === 'b' ? 'bg-primary text-primary-foreground border-transparent' : 'bg-card border-border text-foreground hover:border-border-strong'}">Tab B</button>
+              class=${buttonClass({ variant: this.tab.get() === 'b' ? 'default' : 'secondary', size: 'xs' })}>Tab B</button>
           </div>
           <div class="text-[15px] text-foreground">${cache(
             this.tab.get() === 'a'
@@ -181,7 +182,7 @@ export class DirectiveDemo extends WebComponent {
                you can watch them replay. The run counter forces the re-render. -->
           <div class="flex items-center gap-3">
             <button @click=${() => this.restartStreams()}
-              class="w-fit px-3.5 py-1.5 rounded-xl bg-card border border-border text-foreground text-sm cursor-pointer transition-colors hover:border-border-strong">restart streams</button>
+              class="${buttonClass({ variant: 'secondary', size: 'sm' })} w-fit">restart streams</button>
             <span class="text-sm text-muted-foreground">run #${this.streamRun.get()}</span>
           </div>
           <div class="text-sm text-muted-foreground">log (asyncAppend, one row per value):</div>
diff --git a/packages/cli/templates/gallery/modules/rate-limit/components/rate-probe.ts b/packages/cli/templates/gallery/modules/rate-limit/components/rate-probe.ts
index 945079dd1..9fd2dbba3 100644
--- a/packages/cli/templates/gallery/modules/rate-limit/components/rate-probe.ts
+++ b/packages/cli/templates/gallery/modules/rate-limit/components/rate-probe.ts
@@ -5,6 +5,7 @@
 // import and call instead). The button is the interactivity signal, so this
 // component ships and hydrates.
 import { WebComponent, signal, html } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
 
 interface Probe { n: number; status: number; remaining: string }
 
@@ -32,7 +33,7 @@ export class RateProbe extends WebComponent {
     return html`
       <div class="grid gap-4 max-w-[420px]">
         <button @click=${() => this.ping()}
-          class="w-fit px-3.5 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]">Ping the endpoint</button>
+          class="${buttonClass({ size: 'sm' })} w-fit">Ping the endpoint</button>
         <ul class="grid gap-1.5 list-none m-0 p-0">
           ${this.log.get().map((p) => html`
             <li class="flex items-center justify-between px-3 py-2 rounded-xl bg-card border border-border text-sm">
diff --git a/packages/cli/templates/gallery/modules/route-handler/components/rich-data.ts b/packages/cli/templates/gallery/modules/route-handler/components/rich-data.ts
index 0ba2a336d..d4ee67726 100644
--- a/packages/cli/templates/gallery/modules/route-handler/components/rich-data.ts
+++ b/packages/cli/templates/gallery/modules/route-handler/components/rich-data.ts
@@ -6,6 +6,7 @@
 // (it runs in the browser), so it lives in a component; with JS off this button
 // is inert and the page still reads.
 import { WebComponent, signal, html, richFetch } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
 
 interface RichPayload { at: Date; ip: string; requestId: string; cookieCount: number }
 
@@ -22,7 +23,7 @@ export class RichData extends WebComponent {
     return html`
       <div class="flex items-center gap-3 text-[15px]">
         <button @click=${() => this.load()}
-          class="px-3.5 py-1.5 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]">richFetch() the route</button>
+          class=${buttonClass({ size: 'sm' })}>richFetch() the route</button>
         <span class="text-muted-foreground">${this.line.get()}</span>
       </div>
     `;
diff --git a/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts b/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts
index 3f6a89471..c63eb81ef 100644
--- a/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts
+++ b/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts
@@ -1,6 +1,7 @@
 // Calls the 'use server' action via a normal import (the RPC stub). Never
 // hand-write fetch(); importing the action IS the API.
 import { WebComponent, signal, html } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
 import { greet } from '../actions/greet.server.ts';
 
 export class Greeter extends WebComponent {
@@ -25,7 +26,7 @@ export class Greeter extends WebComponent {
           <input name="name" placeholder="your name" autocomplete="off"
             class="flex-1 min-w-0 bg-transparent border-0 outline-none text-foreground text-[15px] placeholder:text-muted-foreground py-1.5" />
           <button type="submit"
-            class="shrink-0 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]">Greet</button>
+            class="${buttonClass()} shrink-0">Greet</button>
         </form>
         <p class="m-0 text-sm text-muted-foreground">The action is gated by requireAuth. <a class="text-primary" href="/features/auth/login">Sign in</a> to greet; signed out returns a real 401.</p>
         ${this.msg.get() ? html`<p class="m-0 font-semibold text-foreground">${this.msg.get()}</p>` : ''}
diff --git a/packages/cli/templates/gallery/modules/stream/components/stream-demo.ts b/packages/cli/templates/gallery/modules/stream/components/stream-demo.ts
index 5f8f567f3..63a471e92 100644
--- a/packages/cli/templates/gallery/modules/stream/components/stream-demo.ts
+++ b/packages/cli/templates/gallery/modules/stream/components/stream-demo.ts
@@ -12,6 +12,7 @@
 // That is the whole point: out-of-band updates that a signal re-render or a frame
 // region-swap would clobber.
 import { WebComponent, html, renderStream } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
 
 // Build a <webjs-stream> payload string. It is a plain string (NOT an html``
 // template), so interpolating the row markup here is fine. `remove` needs no
@@ -53,7 +54,7 @@ export class StreamDemo extends WebComponent {
   }
 
   render() {
-    const btn = 'px-3 py-1.5 rounded-lg bg-card border border-border text-sm font-medium text-foreground cursor-pointer transition-colors hover:border-border-strong';
+    const btn = buttonClass({ variant: 'secondary', size: 'xs' });
     return html`
       <div class="grid gap-4 max-w-[460px]">
         <div class="flex flex-wrap gap-2">
diff --git a/packages/cli/templates/gallery/modules/streaming/components/token-stream.ts b/packages/cli/templates/gallery/modules/streaming/components/token-stream.ts
index b733b86db..304c4bf9b 100644
--- a/packages/cli/templates/gallery/modules/streaming/components/token-stream.ts
+++ b/packages/cli/templates/gallery/modules/streaming/components/token-stream.ts
@@ -6,6 +6,7 @@
 // the button is inert and the empty output renders (streaming is inherently a
 // JS behaviour), so nothing here breaks the no-JS first paint.
 import { WebComponent, signal, html } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
 import { streamTokens } from '../actions/stream-tokens.server.ts';
 
 export class TokenStream extends WebComponent {
@@ -34,7 +35,7 @@ export class TokenStream extends WebComponent {
         <button
           @click=${() => this.run()}
           ?disabled=${busy}
-          class="inline-flex items-center px-4 py-2 rounded-xl bg-primary text-primary-foreground font-semibold text-sm cursor-pointer transition-all hover:bg-primary/90 active:scale-[0.97] disabled:opacity-60"
+          class=${buttonClass()}
         >
           ${busy ? 'streaming…' : 'Stream tokens'}
         </button>
diff --git a/packages/cli/templates/gallery/modules/todo/components/todo-app.ts b/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
index 3bdf0dd31..a107271b1 100644
--- a/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
+++ b/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
@@ -10,6 +10,7 @@
 // one coherent theme. Prefer these tokens (and opacity modifiers like
 // bg-primary/90) over ad-hoc colors.
 import { WebComponent, prop, optimistic, html } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
 import { createTodo } from '../actions/create-todo.server.ts';
 import { toggleTodo } from '../actions/toggle-todo.server.ts';
 import { deleteTodo } from '../actions/delete-todo.server.ts';
@@ -99,7 +100,7 @@ export class TodoApp extends WebComponent({
           <input name="title" required maxlength="280" autocomplete="off" placeholder="What needs doing?"
             class="flex-1 min-w-0 bg-transparent border-0 outline-none text-foreground text-[15px] placeholder:text-muted-foreground py-1.5" />
           <button type="submit"
-            class="shrink-0 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]">Add</button>
+            class="${buttonClass()} shrink-0">Add</button>
         </form>
 
         <ul class="list-none m-0 p-0 grid gap-2">
diff --git a/packages/cli/templates/gallery/modules/websockets/components/ws-echo.ts b/packages/cli/templates/gallery/modules/websockets/components/ws-echo.ts
index bbc45a900..fa1dc4049 100644
--- a/packages/cli/templates/gallery/modules/websockets/components/ws-echo.ts
+++ b/packages/cli/templates/gallery/modules/websockets/components/ws-echo.ts
@@ -5,6 +5,7 @@
 // component renders its disconnected state, so with JS off the page still reads
 // (a live socket has no no-JS equivalent, which is the honest fallback here).
 import { WebComponent, signal, html, connectWS, renderStream } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
 
 export class WsEcho extends WebComponent {
   private connected = signal(false);
@@ -61,7 +62,7 @@ export class WsEcho extends WebComponent {
           <input name="msg" autocomplete="off" placeholder="Say something"
             class="flex-1 px-3 py-2 rounded-xl bg-card border border-border text-foreground text-sm outline-none focus:border-border-strong" />
           <button type="submit"
-            class="px-3.5 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</button>
+            class=${buttonClass({ size: 'sm' })}>Send</button>
         </form>
         <ul class="grid gap-1.5 list-none m-0 p-0">
           ${this.lines.get().map((line) => html`
@@ -70,7 +71,7 @@ export class WsEcho extends WebComponent {
         </ul>
         <div class="grid gap-2 border-t border-border pt-4">
           <button @click=${() => this.applyStreamUpdate()}
-            class="w-fit px-3.5 py-1.5 rounded-xl bg-card border border-border text-foreground text-sm cursor-pointer transition-colors hover:border-border-strong">renderStream() an element-level update</button>
+            class="${buttonClass({ variant: 'secondary', size: 'sm' })} w-fit">renderStream() an element-level update</button>
           <ul id="ws-stream-log" class="grid gap-1.5 list-none m-0 p-0"></ul>
         </div>
       </div>

From 419e2e6d1ca4749409601b215b752f246fbb4a46 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 12:09:38 +0530
Subject: [PATCH 03/73] feat: theme card + input helpers, convert
 panels/fields, drop unused helpers

- components/ui/card.ts: themed cardClass() to the gallery panel surface
  (rounded-2xl border bg-card), surface-only so per-panel padding/layout stays
  on the call site; convert every light-DOM demo panel to cardClass().
- components/ui/input.ts: themed inputClass() to the gallery field look; convert
  the shared inputCls consts (forms + auth) to it (one style for input AND
  textarea, matching the app's intent).
- Drop the unused textarea.ts + badge.ts rather than ship dead files.
- Dense teaching comments on each: WHY a class helper, WHY surface-vs-layout,
  and the own-and-theme workflow, so an agent reading the scaffold learns to
  build and theme a design system for its own app.

All pages render, webjs check passes.
---
 .../app/features/auth/dashboard/page.ts       |   3 +-
 .../features/auth/dashboard/settings/page.ts  |   3 +-
 .../gallery/app/features/auth/login/page.ts   |   6 +-
 .../gallery/app/features/auth/signup/page.ts  |   6 +-
 .../gallery/app/features/forms/page.ts        |   8 +-
 .../gallery/app/features/frames/page.ts       |   3 +-
 .../templates/gallery/components/ui/badge.ts  |  46 --------
 .../templates/gallery/components/ui/card.ts   | 108 +++++-------------
 .../templates/gallery/components/ui/input.ts  |  55 +++++----
 .../gallery/components/ui/textarea.ts         |  29 -----
 .../components/components/counter-card.ts     |   3 +-
 .../server-actions/components/greeter.ts      |   3 +-
 .../streaming/components/token-stream.ts      |   3 +-
 .../modules/suspense/components/slow-fact.ts  |   3 +-
 .../modules/todo/components/todo-app.ts       |   3 +-
 15 files changed, 83 insertions(+), 199 deletions(-)
 delete mode 100644 packages/cli/templates/gallery/components/ui/badge.ts
 delete mode 100644 packages/cli/templates/gallery/components/ui/textarea.ts

diff --git a/packages/cli/templates/gallery/app/features/auth/dashboard/page.ts b/packages/cli/templates/gallery/app/features/auth/dashboard/page.ts
index dd68314e9..2c7f5feea 100644
--- a/packages/cli/templates/gallery/app/features/auth/dashboard/page.ts
+++ b/packages/cli/templates/gallery/app/features/auth/dashboard/page.ts
@@ -1,4 +1,5 @@
 import { html } from '@webjsdev/core';
+import { cardClass } from '#components/ui/card.ts';
 import { currentUser } from '#modules/auth/queries/current-user.server.ts';
 
 export const metadata = { title: 'Dashboard' };
@@ -10,7 +11,7 @@ export default async function Dashboard() {
       <h1 class="text-2xl font-semibold">Dashboard</h1>
       <span class="text-xs font-medium rounded-full bg-primary/15 text-primary px-2.5 py-1">Signed in</span>
     </div>
-    <div class="p-6 rounded-2xl bg-card border border-border">
+    <div class="${cardClass()} p-6">
       <h2 class="text-lg font-semibold text-foreground m-0 mb-1">Welcome, ${user?.name || user?.email}!</h2>
       <p class="text-sm text-muted-foreground m-0">This route is gated by middleware.ts. Promote it into your product, or drop the whole auth card with gallery:clear.</p>
     </div>
diff --git a/packages/cli/templates/gallery/app/features/auth/dashboard/settings/page.ts b/packages/cli/templates/gallery/app/features/auth/dashboard/settings/page.ts
index 60b37486e..0e46cf8a0 100644
--- a/packages/cli/templates/gallery/app/features/auth/dashboard/settings/page.ts
+++ b/packages/cli/templates/gallery/app/features/auth/dashboard/settings/page.ts
@@ -1,4 +1,5 @@
 import { html } from '@webjsdev/core';
+import { cardClass } from '#components/ui/card.ts';
 import { currentUser } from '#modules/auth/queries/current-user.server.ts';
 
 export const metadata = { title: 'Settings' };
@@ -7,7 +8,7 @@ export default async function Settings() {
   const user = await currentUser();
   return html`
     <h1 class="text-2xl font-semibold mb-6">Settings</h1>
-    <div class="p-6 rounded-2xl bg-card border border-border">
+    <div class="${cardClass()} p-6">
       <h2 class="text-lg font-semibold text-foreground m-0 mb-1">Account</h2>
       <p class="text-sm text-muted-foreground m-0 mb-4">Your basic profile information.</p>
       <dl class="grid grid-cols-[max-content_1fr] gap-x-6 gap-y-2 text-sm">
diff --git a/packages/cli/templates/gallery/app/features/auth/login/page.ts b/packages/cli/templates/gallery/app/features/auth/login/page.ts
index 2c247da19..91e1a21d3 100644
--- a/packages/cli/templates/gallery/app/features/auth/login/page.ts
+++ b/packages/cli/templates/gallery/app/features/auth/login/page.ts
@@ -1,9 +1,11 @@
 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';
 
 export const metadata = { title: 'Log in' };
 
-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();
 
 // A failed sign-in 302s back here with ?error=... (createAuth is configured with
 // pages.error: '/features/auth/login' in modules/auth/auth.server.ts). Map the
@@ -22,7 +24,7 @@ export default function LoginPage({ searchParams }: { searchParams: { error?: st
       <h1 class="text-h2 font-bold mb-2">Sign in</h1>
       <p class="text-muted-foreground mb-5">Welcome back: log in to continue.</p>
       ${error ? html`<p role="alert" class="mb-4 text-sm text-destructive">${error}</p>` : ''}
-      <form method="POST" action="/api/auth/signin/credentials" class="grid gap-4 p-5 rounded-2xl bg-card border border-border">
+      <form method="POST" action="/api/auth/signin/credentials" class="${cardClass()} grid gap-4 p-5">
         <!-- createAuth reads redirectTo from the posted form and 302s there after a successful signin. -->
         <input type="hidden" name="redirectTo" value="/features/auth/dashboard">
         <div class="grid gap-1.5">
diff --git a/packages/cli/templates/gallery/app/features/auth/signup/page.ts b/packages/cli/templates/gallery/app/features/auth/signup/page.ts
index b969d0f0f..998c7c146 100644
--- a/packages/cli/templates/gallery/app/features/auth/signup/page.ts
+++ b/packages/cli/templates/gallery/app/features/auth/signup/page.ts
@@ -1,10 +1,12 @@
 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 { signup } from '#modules/auth/actions/signup.server.ts';
 
 export const metadata = { title: 'Sign up' };
 
-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();
 
 // Page server action: handles the POST from the form below. With JS disabled this
 // is a plain <form> round-trip; with JS the client router swaps the 422 re-render
@@ -35,7 +37,7 @@ export default function SignupPage({ actionData }: { actionData?: { fieldErrors?
     <div class="max-w-[420px] mx-auto">
       <h1 class="text-h2 font-bold mb-2">Create an account</h1>
       <p class="text-muted-foreground mb-5">Get started with your new workspace.</p>
-      <form method="POST" class="grid gap-4 p-5 rounded-2xl bg-card border border-border">
+      <form method="POST" class="${cardClass()} grid gap-4 p-5">
         <div class="grid gap-1.5">
           <label for="name" class="text-[13px] font-medium text-muted-foreground">Name</label>
           <input id="name" name="name" type="text" value=${values.name || ''} required class=${inputCls} placeholder="Ada Lovelace" />
diff --git a/packages/cli/templates/gallery/app/features/forms/page.ts b/packages/cli/templates/gallery/app/features/forms/page.ts
index 4c56a7b48..4c9dbf0e1 100644
--- a/packages/cli/templates/gallery/app/features/forms/page.ts
+++ b/packages/cli/templates/gallery/app/features/forms/page.ts
@@ -6,6 +6,8 @@
 // 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 type { Metadata } from '@webjsdev/core';
 
@@ -26,13 +28,13 @@ 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">
+      <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>
@@ -46,7 +48,7 @@ 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)}
diff --git a/packages/cli/templates/gallery/app/features/frames/page.ts b/packages/cli/templates/gallery/app/features/frames/page.ts
index 2dba2a802..05669f8c7 100644
--- a/packages/cli/templates/gallery/app/features/frames/page.ts
+++ b/packages/cli/templates/gallery/app/features/frames/page.ts
@@ -20,6 +20,7 @@
 // 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 type { Metadata } from '@webjsdev/core';
 import { filterTasks, normalizeStatus, type Status } from '#modules/frames/utils/tasks.ts';
 
@@ -50,7 +51,7 @@ export default function FramesExample({ searchParams }: { searchParams: Record<s
       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.
     </p>
-    <webjs-frame id="tasks" class="block p-4 rounded-2xl bg-card border border-border">
+    <webjs-frame id="tasks" class="${cardClass()} block p-4">
       <div class="flex gap-2 mb-4">
         ${filterTab(status, 'all', 'All')}
         ${filterTab(status, 'active', 'Active')}
diff --git a/packages/cli/templates/gallery/components/ui/badge.ts b/packages/cli/templates/gallery/components/ui/badge.ts
deleted file mode 100644
index 894c222d5..000000000
--- a/packages/cli/templates/gallery/components/ui/badge.ts
+++ /dev/null
@@ -1,46 +0,0 @@
-/**
- * Badge: small visual label. Tier-1 class helper; compose with any
- * inline element (commonly `<span>` or `<a>` for linked badges).
- *
- * shadcn parity:
- *   Badge (variant: default | secondary | destructive | outline | ghost | link)
- *                                  → badgeClass({ variant })
- *
- * The `[a&]:hover:...` hover styles only apply when the element is an `<a>`,
- * so a static `<span>` doesn't pick up an unwanted hover.
- *
- * A11y (required for accessible output): render a static badge as a plain
- * <span> (not focusable, no tabindex). Only an interactive badge (an <a>
- * or <button>) is focusable, and an icon-only one needs an aria-label.
- *
- * Design tokens used: --primary, --secondary, --destructive, --foreground,
- * --accent, --border, --ring.
- *
- * @example
- * ```html
- * <span class=${badgeClass()}>New</span>
- * <span class=${badgeClass({ variant: 'destructive' })}>Error</span>
- * <a class=${badgeClass({ variant: 'link' })} href="/profile">@vivek</a>
- * ```
- */
-import { cn } from '#lib/utils/cn.ts';
-
-const BASE =
-  'inline-flex w-fit shrink-0 items-center justify-center gap-1 overflow-hidden rounded-full border border-transparent px-2 py-0.5 text-xs font-medium whitespace-nowrap transition-[color,box-shadow] focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 [&>svg]:pointer-events-none [&>svg]:size-3';
-
-const VARIANTS = {
-  default: 'bg-primary text-primary-foreground [a&]:hover:bg-primary/90',
-  secondary: 'bg-secondary text-secondary-foreground [a&]:hover:bg-secondary/90',
-  destructive:
-    'bg-destructive text-white focus-visible:ring-destructive/20 dark:bg-destructive/60 dark:focus-visible:ring-destructive/40 [a&]:hover:bg-destructive/90',
-  outline:
-    'border-border text-foreground [a&]:hover:bg-accent [a&]:hover:text-accent-foreground',
-  ghost: '[a&]:hover:bg-accent [a&]:hover:text-accent-foreground',
-  link: 'text-primary underline-offset-4 [a&]:hover:underline',
-} as const;
-
-export type BadgeVariant = keyof typeof VARIANTS;
-
-export function badgeClass(opts: { variant?: BadgeVariant } = {}): string {
-  return cn(BASE, VARIANTS[opts.variant ?? 'default']);
-}
diff --git a/packages/cli/templates/gallery/components/ui/card.ts b/packages/cli/templates/gallery/components/ui/card.ts
index b63e38a20..2f903fcc2 100644
--- a/packages/cli/templates/gallery/components/ui/card.ts
+++ b/packages/cli/templates/gallery/components/ui/card.ts
@@ -1,90 +1,36 @@
 /**
- * Card: visual container. Tier-1 class helpers; compose with `<div>`
- * (or any element) for each subpart.
+ * cardClass: the gallery's panel-surface design token, built on @webjsdev/ui.
  *
- * shadcn parity:
- *   Card (size: default | sm)  → cardClass({ size })
- *   CardHeader                 → cardHeaderClass()
- *   CardTitle                  → cardTitleClass()
- *   CardDescription            → cardDescriptionClass()
- *   CardAction                 → cardActionClass()
- *   CardContent                → cardContentClass()
- *   CardFooter                 → cardFooterClass()
+ * A `@webjsdev/ui` tier-1 CLASS HELPER for the "card" surface every demo panel
+ * sits on. It owns only the SURFACE (radius, border, background), NOT the
+ * padding or inner layout, because those genuinely differ per panel (a form
+ * grid, a centered card, a tight toolbar). So you compose:
  *
- * Design tokens used: --card, --card-foreground, --muted-foreground, --border.
+ *   <div class="${cardClass()} p-5 grid gap-4">...</div>
+ *   <div class="${cardClass()} p-2 flex items-center gap-2">...</div>
  *
- * @example
- * ```html
- * <div class=${cardClass()}>
- *   <div class=${cardHeaderClass()}>
- *     <div class=${cardTitleClass()}>Notifications</div>
- *     <div class=${cardDescriptionClass()}>You have 3 unread messages.</div>
- *     <div class=${cardActionClass()}>
- *       <button class=${buttonClass({ variant: 'ghost', size: 'sm' })}>Mark all read</button>
- *     </div>
- *   </div>
- *   <div class=${cardContentClass()}>
- *     <p class="text-sm">Your weekly digest is ready to review.</p>
- *   </div>
- *   <div class=${cardFooterClass()}>
- *     <button class=${buttonClass()}>Save</button>
- *   </div>
- * </div>
- * ```
- */
-
-export type CardSize = 'default' | 'sm';
-
-/**
- * Card root. shadcn ships `size?: "default" | "sm"` on Card across
- * 14/15 style families (only new-york-v4 omits it). The class string
- * uses `group/card` so the header / title / content / footer helpers
- * can read the parent card's data-size and adjust their own padding
- * + gap.
- *
- * USAGE: pass size to cardClass AND set data-size="<size>" on the
- * same host element so the group-data-[size=...]/card child rules
- * fire. Set `data-slot="card"` for shadcn parity.
- *
- *   <div class=${cardClass({ size: 'sm' })} data-slot="card" data-size="sm">
- *     <div class=${cardHeaderClass()}>...</div>
- *     ...
- *   </div>
+ * WHY split surface from layout: the surface is the thing that MUST be identical
+ * everywhere (so all panels read as one system), while padding and layout are a
+ * per-panel decision. Centralizing only the surface gives consistency without
+ * flattening intentional layout differences. Contrast the fuller shadcn Card
+ * (header / title / content / footer subparts) that `webjs ui add card` ships:
+ * this scaffold's panels are simple containers, so it keeps only what it uses.
  *
- * Sizes:
- *   default: gap-6 / py-6 (shadcn new-york-v4 default)
- *   sm:     gap-3 / py-3 (shadcn radix-nova + base-* defaults)
+ * OWN-AND-THEME: this is `@webjsdev/ui`'s card THEMED to this scaffold (a
+ * `rounded-2xl` panel on `bg-card` with a hairline border). Change the surface
+ * here and every panel updates at once. When you build a real app on
+ * `@webjsdev/ui`, do the same: pull the primitive, keep the parts you use, and
+ * theme it to your brand.
  */
-export const cardClass = (opts: { size?: CardSize } = {}): string => {
-  const size = opts.size ?? 'default';
-  const base =
-    'group/card flex flex-col rounded-xl border bg-card text-card-foreground shadow-sm';
-  return size === 'sm' ? base + ' gap-3 py-3' : base + ' gap-6 py-6';
-};
+import { cn } from '#lib/utils/cn.ts';
+
+// The shared panel surface. Padding + inner layout stay on the call site.
+const SURFACE = 'rounded-2xl border border-border bg-card';
 
 /**
- * Card header: supports an optional `CardAction` slot via grid layout.
- * group-data-[size=sm]/card rules pick up the compact layout when the
- * root card carries data-size="sm".
+ * Compose the Tailwind classes for a card/panel surface. Append the panel's own
+ * padding + layout: `class="${cardClass()} p-5 grid gap-4 max-w-[460px]"`.
  */
-export const cardHeaderClass = (): string =>
-  '@container/card-header grid auto-rows-min grid-rows-[auto_auto] items-start gap-2 px-6 has-data-[slot=card-action]:grid-cols-[1fr_auto] [.border-b]:pb-6 group-data-[size=sm]/card:px-4 group-data-[size=sm]/card:gap-1 group-data-[size=sm]/card:[.border-b]:pb-3';
-
-/** Card title: heading text within the header. Smaller when card is data-size="sm". */
-export const cardTitleClass = (): string =>
-  'leading-none font-semibold group-data-[size=sm]/card:text-sm';
-
-/** Card description: subdued caption beneath the title. */
-export const cardDescriptionClass = (): string => 'text-sm text-muted-foreground';
-
-/** Card action: right-aligned controls inside the header (matches shadcn CardAction). */
-export const cardActionClass = (): string =>
-  'col-start-2 row-span-2 row-start-1 self-start justify-self-end';
-
-/** Card content: the main body region. Tighter padding when card is data-size="sm". */
-export const cardContentClass = (): string =>
-  'px-6 group-data-[size=sm]/card:px-4';
-
-/** Card footer: trailing controls or actions. Tighter padding when card is data-size="sm". */
-export const cardFooterClass = (): string =>
-  'flex items-center px-6 [.border-t]:pt-6 group-data-[size=sm]/card:px-4 group-data-[size=sm]/card:[.border-t]:pt-3';
+export function cardClass(extra?: string): string {
+  return cn(SURFACE, extra);
+}
diff --git a/packages/cli/templates/gallery/components/ui/input.ts b/packages/cli/templates/gallery/components/ui/input.ts
index e8cf541ec..c8def4b50 100644
--- a/packages/cli/templates/gallery/components/ui/input.ts
+++ b/packages/cli/templates/gallery/components/ui/input.ts
@@ -1,38 +1,37 @@
 /**
- * Input: styled native `<input>`. Tier-1 class helper. Works with every
- * input type (text, email, password, number, search, tel, url, date,
- * time, file, color, …). Form submission, autocomplete, browser
- * validation, and password managers all work because it IS the native
- * input.
+ * inputClass: the gallery's text-field design token, built on @webjsdev/ui.
  *
- * shadcn parity:
- *   Input  → inputClass()
+ * Like buttonClass, this is a `@webjsdev/ui` tier-1 CLASS HELPER: it returns a
+ * Tailwind class string you spread onto a NATIVE `<input>` or `<textarea>`, so
+ * the browser's built-in form behaviour, validation, and accessibility all work
+ * with nothing extra:
  *
- * Pair with `<label class=${labelClass()} for="...">` and a hint paragraph
- * (`<p class=${hintClass()} id="...-hint">`). Wrap all three in
- * `<div class=${fieldClass()}>` for the canonical field rhythm.
+ *   <input class=${inputClass()} name="email" type="email" />
+ *   <textarea class=${inputClass()} name="message" rows="3"></textarea>
  *
- * Design tokens used: --input, --background, --primary, --primary-foreground,
- * --muted-foreground, --foreground, --ring, --destructive.
+ * The same helper styles inputs AND textareas here, because this app wants them
+ * to look identical. That is the point of a design token: one place decides how
+ * every field looks, so they cannot drift apart. If you later want a distinct
+ * textarea look, add a `textareaClass` alongside this and theme it separately
+ * (that is exactly how `webjs ui add textarea` would give you one).
  *
- * @example
- * ```html
- * <input class=${inputClass()} type="email" name="email" id="email" required
- *        aria-describedby="email-hint">
- * ```
+ * OWN-AND-THEME: this is `@webjsdev/ui`'s input, THEMED to this scaffold's look
+ * (a filled `bg-background` field, `rounded-xl`, a primary focus border). You
+ * own this file: change the class values here and every field in the app
+ * updates at once. This is the intended workflow when building on `@webjsdev/ui`
+ * for a real app: pull the primitive, then make it yours.
  */
 import { cn } from '#lib/utils/cn.ts';
 
-const INPUT_BASE =
-  'h-9 w-full min-w-0 rounded-md border border-input bg-transparent px-3 py-1 text-base shadow-xs transition-[color,box-shadow] outline-none selection:bg-primary selection:text-primary-foreground file:inline-flex file:h-7 file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground placeholder:text-muted-foreground disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 md:text-sm dark:bg-input/30';
+// One surface for every text field. `focus:border-primary` is the whole focus
+// affordance (no ring), to match this app's quiet, token-driven chrome.
+const BASE =
+  '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 disabled:cursor-not-allowed disabled:opacity-60';
 
-const INPUT_FOCUS =
-  'focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50';
-
-const INPUT_INVALID =
-  'aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40';
-
-/** Compose Tailwind classes for a native `<input>`. */
-export function inputClass(): string {
-  return cn(INPUT_BASE, INPUT_FOCUS, INPUT_INVALID);
+/**
+ * Compose the Tailwind classes for a text input or textarea. Append your own
+ * layout classes as needed: `class="${inputClass()} max-w-sm"`.
+ */
+export function inputClass(extra?: string): string {
+  return cn(BASE, extra);
 }
diff --git a/packages/cli/templates/gallery/components/ui/textarea.ts b/packages/cli/templates/gallery/components/ui/textarea.ts
deleted file mode 100644
index a5794a35b..000000000
--- a/packages/cli/templates/gallery/components/ui/textarea.ts
+++ /dev/null
@@ -1,29 +0,0 @@
-/**
- * Textarea: styled native `<textarea>`. Tier-1 class helper. Real
- * multi-line input: form submission, autosize via `field-sizing:
- * content`, and native validation all work.
- *
- * shadcn parity:
- *   Textarea  → textareaClass()
- *
- * Pair with `<label class=${labelClass()} for="...">` and wrap in
- * `<div class=${fieldClass()}>` for the canonical field rhythm.
- *
- * Design tokens used: --input, --background, --muted-foreground, --ring,
- * --destructive.
- *
- * @example
- * ```html
- * <textarea class=${textareaClass()} name="message" rows="4" placeholder="Your message">
- * </textarea>
- * ```
- */
-import { cn } from '#lib/utils/cn.ts';
-
-const TEXTAREA_BASE =
-  'flex field-sizing-content min-h-16 w-full rounded-md border border-input bg-transparent px-3 py-2 text-base shadow-xs transition-[color,box-shadow] outline-none placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 md:text-sm dark:bg-input/30 dark:aria-invalid:ring-destructive/40';
-
-/** Compose Tailwind classes for a native `<textarea>`. */
-export function textareaClass(): string {
-  return cn(TEXTAREA_BASE);
-}
diff --git a/packages/cli/templates/gallery/modules/components/components/counter-card.ts b/packages/cli/templates/gallery/modules/components/components/counter-card.ts
index 4633253d0..9989f61ca 100644
--- a/packages/cli/templates/gallery/modules/components/components/counter-card.ts
+++ b/packages/cli/templates/gallery/modules/components/components/counter-card.ts
@@ -4,6 +4,7 @@
 // component authoring shape. Styling is crafted Tailwind on the app's design
 // tokens so it stays visually coherent with the rest of the app.
 import { WebComponent, prop, signal, html } from '@webjsdev/core';
+import { cardClass } from '#components/ui/card.ts';
 import { buttonClass } from '#components/ui/button.ts';
 
 export class CounterCard extends WebComponent({
@@ -21,7 +22,7 @@ export class CounterCard extends WebComponent({
 
   render() {
     return html`
-      <div class="grid gap-4 p-5 rounded-2xl bg-card border border-border max-w-[320px]">
+      <div class="${cardClass()} grid gap-4 p-5 max-w-[320px]">
         <slot></slot>
         <div class="flex items-baseline gap-2">
           <span class="text-[2.5rem] font-bold tabular-nums leading-none text-foreground">${this.count.get()}</span>
diff --git a/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts b/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts
index c63eb81ef..eb9fcfbb2 100644
--- a/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts
+++ b/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts
@@ -1,6 +1,7 @@
 // Calls the 'use server' action via a normal import (the RPC stub). Never
 // hand-write fetch(); importing the action IS the API.
 import { WebComponent, signal, html } from '@webjsdev/core';
+import { cardClass } from '#components/ui/card.ts';
 import { buttonClass } from '#components/ui/button.ts';
 import { greet } from '../actions/greet.server.ts';
 
@@ -22,7 +23,7 @@ export class Greeter extends WebComponent {
     return html`
       <div class="grid gap-3 max-w-[420px]">
         <form @submit=${(e: SubmitEvent) => this.run(e)}
-          class="flex items-center gap-2 p-2 pl-4 rounded-2xl bg-card border border-border">
+          class="${cardClass()} flex items-center gap-2 p-2 pl-4">
           <input name="name" placeholder="your name" autocomplete="off"
             class="flex-1 min-w-0 bg-transparent border-0 outline-none text-foreground text-[15px] placeholder:text-muted-foreground py-1.5" />
           <button type="submit"
diff --git a/packages/cli/templates/gallery/modules/streaming/components/token-stream.ts b/packages/cli/templates/gallery/modules/streaming/components/token-stream.ts
index 304c4bf9b..6fabdaab7 100644
--- a/packages/cli/templates/gallery/modules/streaming/components/token-stream.ts
+++ b/packages/cli/templates/gallery/modules/streaming/components/token-stream.ts
@@ -6,6 +6,7 @@
 // the button is inert and the empty output renders (streaming is inherently a
 // JS behaviour), so nothing here breaks the no-JS first paint.
 import { WebComponent, signal, html } from '@webjsdev/core';
+import { cardClass } from '#components/ui/card.ts';
 import { buttonClass } from '#components/ui/button.ts';
 import { streamTokens } from '../actions/stream-tokens.server.ts';
 
@@ -31,7 +32,7 @@ export class TokenStream extends WebComponent {
   render() {
     const busy = this.busy.get();
     return html`
-      <div class="rounded-2xl border border-border bg-card p-5">
+      <div class="${cardClass()} p-5">
         <button
           @click=${() => this.run()}
           ?disabled=${busy}
diff --git a/packages/cli/templates/gallery/modules/suspense/components/slow-fact.ts b/packages/cli/templates/gallery/modules/suspense/components/slow-fact.ts
index 48c332a8d..a73b773d0 100644
--- a/packages/cli/templates/gallery/modules/suspense/components/slow-fact.ts
+++ b/packages/cli/templates/gallery/modules/suspense/components/slow-fact.ts
@@ -7,11 +7,12 @@
 // navigation too). Same component either way; the boundary is what changes the
 // SSR behaviour from block to stream.
 import { WebComponent, html } from '@webjsdev/core';
+import { cardClass } from '#components/ui/card.ts';
 
 export class SlowFact extends WebComponent {
   async render() {
     await new Promise((r) => setTimeout(r, 900));
-    return html`<p class="rounded-2xl border border-border bg-card p-5 text-foreground">
+    return html`<p class="${cardClass()} p-5 text-foreground">
       The answer, after a slow lookup, is <strong>42</strong>.
     </p>`;
   }
diff --git a/packages/cli/templates/gallery/modules/todo/components/todo-app.ts b/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
index a107271b1..67528649b 100644
--- a/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
+++ b/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
@@ -10,6 +10,7 @@
 // one coherent theme. Prefer these tokens (and opacity modifiers like
 // bg-primary/90) over ad-hoc colors.
 import { WebComponent, prop, optimistic, html } from '@webjsdev/core';
+import { cardClass } from '#components/ui/card.ts';
 import { buttonClass } from '#components/ui/button.ts';
 import { createTodo } from '../actions/create-todo.server.ts';
 import { toggleTodo } from '../actions/toggle-todo.server.ts';
@@ -95,7 +96,7 @@ export class TodoApp extends WebComponent({
         <!-- Add: a real <form> so it works with JS off (posts to the page action);
              with JS, @submit intercepts and runs the optimistic path. -->
         <form method="post" action="" @submit=${(e: SubmitEvent) => this.add(e)}
-          class="flex items-center gap-2 p-2 pl-4 rounded-2xl bg-card border border-border shadow-[0_1px_0_0_color-mix(in_oklch,var(--foreground)_5%,transparent)]">
+          class="${cardClass()} flex items-center gap-2 p-2 pl-4 shadow-[0_1px_0_0_color-mix(in_oklch,var(--foreground)_5%,transparent)]">
           <input type="hidden" name="intent" value="create" />
           <input name="title" required maxlength="280" autocomplete="off" placeholder="What needs doing?"
             class="flex-1 min-w-0 bg-transparent border-0 outline-none text-foreground text-[15px] placeholder:text-muted-foreground py-1.5" />

From 7ed18edd69511d899ade84f782a0a18b10c6df6e Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 12:11:19 +0530
Subject: [PATCH 04/73] docs: teach the class-helper design-system pattern in
 the styling reference

Add a 'design system for repeated primitives' subsection: use a class helper
(buttonClass/cardClass/inputClass built on @webjsdev/ui) for a themed primitive
with variants, vs a lib/utils/ui.ts html-fragment helper for a repeated markup
chunk. Teaches the own-and-theme workflow the gallery now demonstrates, so an
agent gathering context from the scaffold learns to build a themed design
system for its own app.
---
 .agents/skills/webjs/references/styling.md | 25 ++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/.agents/skills/webjs/references/styling.md b/.agents/skills/webjs/references/styling.md
index 2a2924433..69a019a5a 100644
--- a/.agents/skills/webjs/references/styling.md
+++ b/.agents/skills/webjs/references/styling.md
@@ -67,6 +67,31 @@ export default function Post({ params }) {
 
 Avoid `@apply`: it hides which utilities a class uses and creates a second source of truth. A JS helper keeps the bundle visible at the definition site, composes with conditional classes and active states, and runs at SSR time.
 
+### A design system for repeated PRIMITIVES: class helpers built on `@webjsdev/ui`
+
+An `html`-fragment helper is right for a repeated CHUNK of markup (the rubric above). For a repeated UI PRIMITIVE (button, input, card, badge) that needs variants and sizes, use a class helper instead: a function that returns a Tailwind class STRING you spread onto a native element. That is exactly what `@webjsdev/ui` ships (`buttonClass({ variant, size })`, `cardClass()`, `inputClass()`), and it is what the scaffold gallery uses in `components/ui/`.
+
+```ts
+// components/ui/button.ts  (webjs ui add button, themed to your app)
+import { cn } from '#lib/utils/cn.ts';
+const BASE = 'inline-flex cursor-pointer items-center justify-center ...';
+const VARIANTS = { default: 'bg-primary text-primary-foreground ...', secondary: '...' } as const;
+const SIZES = { default: 'px-4 py-2 rounded-xl', sm: '...' } as const;
+export function buttonClass(o: { variant?: keyof typeof VARIANTS; size?: keyof typeof SIZES } = {}) {
+  return cn(BASE, VARIANTS[o.variant ?? 'default'], SIZES[o.size ?? 'default']);
+}
+```
+
+```ts
+// a page or component
+import { buttonClass } from '#components/ui/button.ts';
+html`<button class=${buttonClass({ variant: 'secondary', size: 'sm' })} @click=${...}>Reset</button>`;
+```
+
+Why a class helper (not a `<ui-button>` wrapper): it adds NO indirection, so the element stays native (`@click`, `?disabled`, form submission, focus, a11y all just work) and the markup stays readable, while every button shares one source of truth (so no button can forget `cursor-pointer` or drift). Put the affordance every variant needs (like `cursor-pointer`) on the shared BASE.
+
+**Own and theme your copy.** `webjs ui add <name>` copies the primitive INTO your `components/ui/`, so you own it. Theme it to YOUR app: change the class values so the helper produces YOUR look, rather than bending your app to the kit's defaults. Keep only the parts you use (the gallery's `cardClass` is surface-only, since its panels vary their own padding and layout). Reserve `lib/utils/ui.ts` `html`-fragment helpers for repeated markup chunks; reserve `components/ui/*` class helpers for themed primitives with variants.
+
 ## Design tokens
 
 The default stack is a static compiled Tailwind stylesheet (`css:build` compiles `public/input.css` to the linked `public/tailwind.css`, so it works with JS off) plus `@theme` design tokens (palette, fonts, fluid type, motion durations) declared once in the root layout. Consume them as utility classes (`text-foreground`, `bg-card`, `font-serif`, `duration-fast`). If you wire your own theme switch, drive BOTH signals on `<html>` (the `data-theme` attribute for the app palette blocks AND the `.dark` class for the `@webjsdev/ui` kit), or half the UI renders stale tokens. Verify dark mode in a real browser, light mode passing proves nothing about dark.

From ecd0ef3273bd18135357cb499f07f00d92b3a9ea Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 12:12:44 +0530
Subject: [PATCH 05/73] chore: keep components/ui design system across
 gallery:clear (make explicit)

The design system in components/ui/ (buttonClass/cardClass/inputClass + cn) is
infrastructure a real app keeps importing after the reset, not demo cruft. It
already survives (never in the removal list), but state that intent explicitly
in the header + closing message so it is not accidentally added later. This is
the durable home for the design-system pattern (skill + surviving helpers),
while the demos are the disposable runnable illustration.
---
 packages/cli/templates/scripts/clear-gallery.mjs | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/packages/cli/templates/scripts/clear-gallery.mjs b/packages/cli/templates/scripts/clear-gallery.mjs
index 3f0601dcf..2a4412fec 100644
--- a/packages/cli/templates/scripts/clear-gallery.mjs
+++ b/packages/cli/templates/scripts/clear-gallery.mjs
@@ -12,10 +12,16 @@
 // It removes the gallery routes + modules + demo metadata routes, resets
 // app/page.ts to a minimal home, and drops the demo `todos` table plus the auth
 // card's `passwordHash` column from the schema. It KEEPS the agent skill
-// (.agents/skills/webjs/), the layout, the database wiring, the theme toggle, and
-// the example `users` table. It is a one-time reset: if the gallery is already
-// gone (no app/features/) it does nothing, so a rerun never clobbers an app you
-// built.
+// (.agents/skills/webjs/), the layout, the database wiring, the theme toggle,
+// the example `users` table, AND the design system in `components/ui/` (the
+// `buttonClass` / `cardClass` / `inputClass` helpers + `lib/utils/cn.ts`). The
+// design system is INFRASTRUCTURE, not a demo: a real app built after this reset
+// still imports those helpers, and their teaching comments plus the styling
+// reference are where the "own and theme your @webjsdev/ui primitives" pattern
+// lives durably (the demos are just the disposable runnable illustration). So
+// do NOT add `components/ui` to the removal list below. It is a one-time reset:
+// if the gallery is already gone (no app/features/) it does nothing, so a rerun
+// never clobbers an app you built.
 import { rmSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
@@ -76,7 +82,7 @@ if (existsSync(schemaPath)) {
 rm('db/migrations');
 for (const f of ['db/dev.db', 'db/dev.db-shm', 'db/dev.db-wal']) rm(f);
 
-console.log(`Gallery cleared (${removed} paths removed). The agent skill and your database wiring are kept.`);
+console.log(`Gallery cleared (${removed} paths removed). The agent skill, your database wiring, and the components/ui/ design system are kept.`);
 console.log('Next: regenerate the database (db:generate then db:migrate), then start the dev server and build your app in app/ and modules/.');
 
 function MINIMAL_PAGE() {

From e8428054bbf923c2dc73801cca6529867a738ce7 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 12:13:40 +0530
Subject: [PATCH 06/73] fix: copy the gallery components/ (design system) into
 scaffolded apps

copyGallery only copied {app,modules,test}, so a fresh webjs create shipped
demos importing #components/ui/button.ts with no components/ui present, a broken
scaffold. Add components to the copied subdirs so the design-system helpers land
in every new app (and gallery:clear keeps them).
---
 packages/cli/lib/create.js | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
index 4dfb96d93..6bb44dd71 100644
--- a/packages/cli/lib/create.js
+++ b/packages/cli/lib/create.js
@@ -124,7 +124,11 @@ async function copyGallery(appDir) {
   const galleryDir = join(TEMPLATES, 'gallery');
   // `test` carries the auth card's real request-pipeline test (test/auth); it
   // ships with the gallery and is pruned by gallery:clear alongside the card.
-  for (const sub of ['app', 'modules', 'test']) {
+  // `components` carries the design system (components/ui/ class helpers) the
+  // demos import; it is INFRASTRUCTURE that gallery:clear KEEPS (a real app goes
+  // on importing buttonClass/cardClass/inputClass), so it merges into the app's
+  // components/ alongside the separately-written theme toggle.
+  for (const sub of ['app', 'modules', 'test', 'components']) {
     await cp(join(galleryDir, sub), join(appDir, sub), { recursive: true });
   }
 }

From 36a36bf9c3a09de41236344c4a0893eb8858ee02 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 12:17:11 +0530
Subject: [PATCH 07/73] chore: remove the example design system on
 gallery:clear (blank slate)

Reverse course: gallery:clear now REMOVES components/ui/ (the gallery's example
design system) so the reset app is a barebones blank slate. Keeping it would
nudge the implementing agent to lean on the gallery's buttons instead of
building the app's own. The durable knowledge is the PATTERN, which lives in the
skill (.agents/skills/webjs/references/styling.md, re-read every session); cn.ts
is kept as the webjs ui add prerequisite, so after clear the agent runs
webjs ui add and themes its own components/ui/. Verified: clear removes
components/ui, keeps cn + skill, cleared app boots.
---
 .../cli/templates/scripts/clear-gallery.mjs   | 35 +++++++++++--------
 1 file changed, 21 insertions(+), 14 deletions(-)

diff --git a/packages/cli/templates/scripts/clear-gallery.mjs b/packages/cli/templates/scripts/clear-gallery.mjs
index 2a4412fec..dcafdbe06 100644
--- a/packages/cli/templates/scripts/clear-gallery.mjs
+++ b/packages/cli/templates/scripts/clear-gallery.mjs
@@ -9,19 +9,22 @@
 // same patterns and SURVIVES this reset, so nothing is lost), then run this
 // once to shed the gallery, then grow the app in place.
 //
-// It removes the gallery routes + modules + demo metadata routes, resets
-// app/page.ts to a minimal home, and drops the demo `todos` table plus the auth
-// card's `passwordHash` column from the schema. It KEEPS the agent skill
-// (.agents/skills/webjs/), the layout, the database wiring, the theme toggle,
-// the example `users` table, AND the design system in `components/ui/` (the
-// `buttonClass` / `cardClass` / `inputClass` helpers + `lib/utils/cn.ts`). The
-// design system is INFRASTRUCTURE, not a demo: a real app built after this reset
-// still imports those helpers, and their teaching comments plus the styling
-// reference are where the "own and theme your @webjsdev/ui primitives" pattern
-// lives durably (the demos are just the disposable runnable illustration). So
-// do NOT add `components/ui` to the removal list below. It is a one-time reset:
-// if the gallery is already gone (no app/features/) it does nothing, so a rerun
-// never clobbers an app you built.
+// It removes the gallery routes + modules + demo metadata routes + the gallery's
+// example design system (components/ui/), resets app/page.ts to a minimal home,
+// and drops the demo `todos` table plus the auth card's `passwordHash` column
+// from the schema. It KEEPS the agent skill (.agents/skills/webjs/), the layout,
+// the database wiring, the theme toggle, the example `users` table, and
+// `lib/utils/cn.ts` (the `webjs ui add` prerequisite).
+//
+// Why remove components/ui: the gallery's design system is an EXAMPLE of the
+// pattern, not a base to inherit. Keeping it would nudge the agent to lean on
+// the gallery's buttons instead of building the app's OWN. The DURABLE knowledge
+// is the pattern itself, which lives in the skill
+// (.agents/skills/webjs/references/styling.md, re-read every session): learn it
+// from the gallery here, then after this reset run `webjs ui add <name>` (cn.ts
+// is kept for it) and theme your own components/ui/ to your app. It is a
+// one-time reset: if the gallery is already gone (no app/features/) it does
+// nothing, so a rerun never clobbers an app you built.
 import { rmSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
@@ -46,6 +49,10 @@ const galleryPaths = [
   'app/icon.ts', 'app/apple-icon.ts', 'app/manifest.ts', 'app/opengraph-image.ts',
   'app/twitter-image.ts', 'app/robots.ts', 'app/sitemap.ts',
   'app/global-error.ts', 'app/global-not-found.ts',
+  // The gallery's EXAMPLE design system. Removed so the reset app is a blank
+  // slate: the agent builds its own components/ui/ (run `webjs ui add`, cn.ts is
+  // kept), learning the pattern from the skill, not inheriting the gallery's.
+  'components/ui',
 ];
 // 2) The gallery's feature modules (by name). `auth` is the auth card's server
 // modules (createAuth config, password hashing, signup action, current-user
@@ -82,7 +89,7 @@ if (existsSync(schemaPath)) {
 rm('db/migrations');
 for (const f of ['db/dev.db', 'db/dev.db-shm', 'db/dev.db-wal']) rm(f);
 
-console.log(`Gallery cleared (${removed} paths removed). The agent skill, your database wiring, and the components/ui/ design system are kept.`);
+console.log(`Gallery cleared (${removed} paths removed). The agent skill and your database wiring are kept. Build your own design system: run \`npx webjsdev ui add <name>\` and theme it (see .agents/skills/webjs/references/styling.md).`);
 console.log('Next: regenerate the database (db:generate then db:migrate), then start the dev server and build your app in app/ and modules/.');
 
 function MINIMAL_PAGE() {

From dc21c54b6944c7ff6ca39c841a5ed84416213b5e Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 12:32:23 +0530
Subject: [PATCH 08/73] chore: make gallery:clear a truly barebones blank slate

Per direction, gallery:clear now strips the app to a minimal buildable base
rather than 'base scaffold minus gallery'. Beyond the gallery + components/ui, it
also removes the example theme-toggle component (and strips its registration
import from the layout + its widget from the reset home), the example test suite
(test/hello/), and every empty leftover dir (app/api after its lone auth handler,
test/unit, test/e2e, test/). Kept: the skill, the layout (with OS-preference dark
mode + tokens, minus the toggle button), db wiring, cn.ts, and empty
components/ + modules/ as build targets. Verified: cleared app boots, no dangling
theme-toggle refs, dark mode still honoured, webjs check passes.
---
 .../cli/templates/scripts/clear-gallery.mjs   | 68 +++++++++++++------
 1 file changed, 49 insertions(+), 19 deletions(-)

diff --git a/packages/cli/templates/scripts/clear-gallery.mjs b/packages/cli/templates/scripts/clear-gallery.mjs
index dcafdbe06..b88e84339 100644
--- a/packages/cli/templates/scripts/clear-gallery.mjs
+++ b/packages/cli/templates/scripts/clear-gallery.mjs
@@ -9,27 +9,35 @@
 // same patterns and SURVIVES this reset, so nothing is lost), then run this
 // once to shed the gallery, then grow the app in place.
 //
-// It removes the gallery routes + modules + demo metadata routes + the gallery's
-// example design system (components/ui/), resets app/page.ts to a minimal home,
-// and drops the demo `todos` table plus the auth card's `passwordHash` column
-// from the schema. It KEEPS the agent skill (.agents/skills/webjs/), the layout,
-// the database wiring, the theme toggle, the example `users` table, and
-// `lib/utils/cn.ts` (the `webjs ui add` prerequisite).
+// It strips the app down to a TRULY BAREBONES blank slate: it removes the
+// gallery routes + modules + demo metadata routes, the gallery's example design
+// system (components/ui/), the example theme-toggle component + its wiring, the
+// example test suite (test/hello/), and every empty leftover dir, then resets
+// app/page.ts to a minimal home and drops the demo `todos` table plus the auth
+// card's `passwordHash` column from the schema. It KEEPS only the buildable
+// base: the agent skill (.agents/skills/webjs/), the root layout (with its
+// design-token palette + OS-preference dark mode, minus the toggle widget), the
+// database wiring, the example `users` table, and `lib/utils/cn.ts` (the
+// `webjs ui add` prerequisite).
 //
-// Why remove components/ui: the gallery's design system is an EXAMPLE of the
-// pattern, not a base to inherit. Keeping it would nudge the agent to lean on
-// the gallery's buttons instead of building the app's OWN. The DURABLE knowledge
-// is the pattern itself, which lives in the skill
-// (.agents/skills/webjs/references/styling.md, re-read every session): learn it
-// from the gallery here, then after this reset run `webjs ui add <name>` (cn.ts
-// is kept for it) and theme your own components/ui/ to your app. It is a
-// one-time reset: if the gallery is already gone (no app/features/) it does
-// nothing, so a rerun never clobbers an app you built.
-import { rmSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+// Why strip so much: the demos, the design system, and the example component /
+// tests are all EXAMPLES to learn FROM, not a base to inherit. Leaving them
+// nudges the implementing agent to lean on the scaffold's choices instead of
+// building the app's own. The DURABLE knowledge is the pattern itself, which
+// lives in the skill (.agents/skills/webjs/, re-read every session): learn it
+// from the gallery here, then after this reset build your own (run
+// `webjs ui add <name>` for UI primitives, cn.ts is kept for it) themed to your
+// app. It is a one-time reset: if the gallery is already gone (no app/features/)
+// it does nothing, so a rerun never clobbers an app you built.
+import { rmSync, rmdirSync, existsSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 
 const root = process.cwd();
 const rm = (p) => { if (existsSync(join(root, p))) { rmSync(join(root, p), { recursive: true, force: true }); return true; } return false; };
+// Remove a directory ONLY if it exists and is empty (used to clean the empty
+// parents a partial gallery removal leaves behind, e.g. app/api after its lone
+// auth handler is gone). Never touches a dir that still holds files.
+const pruneEmpty = (p) => { const abs = join(root, p); if (existsSync(abs) && readdirSync(abs).length === 0) { rmdirSync(abs); return true; } return false; };
 
 // Guard: the gallery is identified by app/features/. If it is absent, the gallery
 // was already cleared (or this is not a gallery scaffold), so exit before any
@@ -53,6 +61,11 @@ const galleryPaths = [
   // slate: the agent builds its own components/ui/ (run `webjs ui add`, cn.ts is
   // kept), learning the pattern from the skill, not inheriting the gallery's.
   'components/ui',
+  // Example scaffold artifacts (invariant 2): the theme-toggle component and the
+  // example test suite are things to learn from, not the agent's app. Removed
+  // for a true blank slate; the layout's theme import is stripped separately
+  // below. The agent writes its own tests + components for the real app.
+  'components/theme-toggle.ts', 'test/hello',
 ];
 // 2) The gallery's feature modules (by name). `auth` is the auth card's server
 // modules (createAuth config, password hashing, signup action, current-user
@@ -84,17 +97,35 @@ if (existsSync(schemaPath)) {
   writeFileSync(schemaPath, s);
 }
 
-// 5) Drop generated migrations + the dev database so the next db:generate is
+// 5) Strip the example theme-toggle from the root layout. The component file was
+// removed above; here the layout's registration import is removed so it does not
+// reference a missing module. The OS-preference dark-mode inline script + the
+// design tokens STAY (they need no component and work with JS off), so the app
+// still honours light/dark, just without the manual toggle button.
+const layoutPath = join(root, 'app/layout.ts');
+if (existsSync(layoutPath)) {
+  const l = readFileSync(layoutPath, 'utf8').replace(/^import '#components\/theme-toggle\.ts';\n/m, '');
+  writeFileSync(layoutPath, l);
+}
+
+// 6) Drop generated migrations + the dev database so the next db:generate is
 // clean against the reset schema (safe: the scaffold has no real data yet).
 rm('db/migrations');
 for (const f of ['db/dev.db', 'db/dev.db-shm', 'db/dev.db-wal']) rm(f);
 
+// 7) Prune the empty leftover dirs a partial removal left behind, so the reset
+// tree is a clean blank slate: app/api (held only the gallery auth handler),
+// test/unit + test/e2e (empty base placeholders), and test/ itself once its
+// example suites are gone. modules/ + components/ are kept as empty build
+// targets (the reset home + `webjs ui add` land there). Order matters: prune the
+// children before test/ so it reads as empty.
+for (const d of ['app/api', 'test/unit', 'test/e2e', 'test']) if (pruneEmpty(d)) removed++;
+
 console.log(`Gallery cleared (${removed} paths removed). The agent skill and your database wiring are kept. Build your own design system: run \`npx webjsdev ui add <name>\` and theme it (see .agents/skills/webjs/references/styling.md).`);
 console.log('Next: regenerate the database (db:generate then db:migrate), then start the dev server and build your app in app/ and modules/.');
 
 function MINIMAL_PAGE() {
   return `import { html } from '@webjsdev/core';
-import '#components/theme-toggle.ts';
 
 export const metadata = {
   title: 'Home',
@@ -102,7 +133,6 @@ export const metadata = {
 
 export default function Home() {
   return html\`
-    <div class="fixed top-4 right-4 z-10"><theme-toggle></theme-toggle></div>
     <div class="max-w-2xl mx-auto px-6 py-24 flex flex-col items-center text-center gap-6">
       <h1 class="text-4xl font-bold tracking-tight m-0">Your app</h1>
       <p class="text-base text-muted-foreground leading-relaxed m-0">

From f384216826d26e4bb1a1fe836a4ed29199d1d187 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 12:40:32 +0530
Subject: [PATCH 09/73] chore: make scaffold-sync enforce the skill as a
 durable teacher

Now that gallery:clear strips the gallery to a blank slate, the agent skill
.agents/skills/webjs/ is the ONLY teaching surface that survives, so a feature
the skill does not teach is lost the moment an agent clears the gallery. Elevate
the skill to a co-primary teaching surface alongside the gallery:

- require-scaffold-with-src.sh now counts .agents/skills/webjs/ as a satisfying
  teaching surface (a feature-source commit is satisfied by the gallery OR the
  skill), and names the skill in its block message.
- webjs-scaffold-sync SKILL.md adds the skill as surface 1 (the durable teacher),
  a change-type row requiring BOTH skill + demo, a skill-vs-gallery coverage
  sweep in audit mode, and the clear-gallery removal list as a synced surface.

The per-surface judgment (did you update both where needed) stays the skill's
manual walk; the hook is the commit-time floor.
---
 .claude/hooks/require-scaffold-with-src.sh  | 38 ++++++---
 .claude/skills/webjs-scaffold-sync/SKILL.md | 89 ++++++++++++++++-----
 2 files changed, 94 insertions(+), 33 deletions(-)

diff --git a/.claude/hooks/require-scaffold-with-src.sh b/.claude/hooks/require-scaffold-with-src.sh
index e4fd1f3b0..985851536 100755
--- a/.claude/hooks/require-scaffold-with-src.sh
+++ b/.claude/hooks/require-scaffold-with-src.sh
@@ -35,9 +35,16 @@
 # CLI packages' src, packages/(core|server|cli)/src/**. Editor plugins, the
 # MCP, and intellisense do not shape the scaffold, so they are excluded.
 #
-# Satisfying surface: the scaffold itself, packages/cli/templates/** (the
-# template files + per-agent rule files) OR packages/cli/lib/** (the
-# create.js / saas-template.js / api-gallery.js generators).
+# Satisfying surface: either of the scaffold's TWO primary teaching surfaces.
+# (1) the scaffold itself, packages/cli/templates/** (the template files +
+# per-agent rule files) OR packages/cli/lib/** (the generators); and (2) the
+# agent skill at the repo-root .agents/skills/webjs/** (SKILL.md + references/),
+# which is bundled into every scaffold at prepack and is the DURABLE teacher:
+# `gallery:clear` removes the gallery, so the skill is the only teaching surface
+# that survives, and a feature it does not teach is lost the moment an agent
+# clears the gallery. So a feature-source commit must move the gallery OR the
+# skill (per-surface judgment on whether BOTH are needed is the skill's manual
+# walk + the CI coverage gate).
 #
 # Allowed (exit 0): commits touching no feature src; commits that stage a
 # scaffold surface alongside the source; and a change that genuinely needs
@@ -71,9 +78,11 @@ if [ -z "$staged" ]; then exit 0; fi
 src_touched=$(printf '%s\n' "$staged" | grep -E '^packages/(core|server|cli)/src/' || true)
 if [ -z "$src_touched" ]; then exit 0; fi
 
-# Any scaffold surface staged in the same commit? The scaffold is the
-# templates (files + per-agent rule files) and the generators (cli/lib).
-scaffold_staged=$(printf '%s\n' "$staged" | grep -E '^packages/cli/(templates|lib)/' || true)
+# Any scaffold teaching surface staged in the same commit? Either the scaffold
+# templates/generators (the gallery, runnable but disposable via gallery:clear)
+# OR the agent skill at .agents/skills/webjs/ (the durable teacher bundled into
+# every scaffold, the only surface that survives gallery:clear).
+scaffold_staged=$(printf '%s\n' "$staged" | grep -E '^packages/cli/(templates|lib)/|^\.agents/skills/webjs/' || true)
 if [ -n "$scaffold_staged" ]; then exit 0; fi
 
 cat >&2 <<'EOF'
@@ -85,18 +94,21 @@ for AI agents (they learn the framework by reading the generated
 gallery/showcase, then build the real app by adapting it), so a task is NOT
 done until the scaffold that teaches the changed feature is in sync too.
 
-If this added or changed a webjs FEATURE an agent should learn from the
+If this added or changed a WebJs FEATURE an agent should learn from the
 scaffold (a new export/API, an html hole, a lifecycle hook, a server-action
-capability, a config key, a CLI behaviour), invoke the webjs-scaffold-sync
-skill, then `git add` the scaffold surface(s) and commit again:
-  packages/cli/templates/gallery/         a UI feature-gallery demo (full-stack + saas)
+capability, a config key, a CLI behaviour), invoke the `webjs-scaffold-sync`
+skill, then `git add` the teaching surface(s) and commit again:
+  `.agents/skills/webjs/`                  the DURABLE teacher (SKILL.md + references/),
+                                          survives `gallery:clear` so it MUST teach the feature
+  packages/cli/templates/gallery/         a UI feature-gallery demo (runnable, disposable)
   packages/cli/lib/api-gallery.js         an api backend-showcase endpoint
   packages/cli/lib/{create,saas-template}.js  the generators (home, theme, schema, wiring)
   packages/cli/templates/ (AGENTS/CONVENTIONS/.cursorrules/...)  scaffold rules in lockstep
   test/scaffolds/**                       the scaffold assertions for the above
-The skill walks every surface AND runs the mandatory generate + boot +
-`webjs check` verification (the generators emit strings, so escaping bugs
-only show in a freshly generated app).
+A feature usually needs BOTH: a gallery demo (learn by running) AND skill
+coverage (the pattern that survives the clear). The skill walks every surface
+AND runs the mandatory generate + boot + `webjs check` verification (the
+generators emit strings, so escaping bugs only show in a freshly generated app).
 
 Change that genuinely needs no scaffold update (a bug fix, an internal
 refactor, a tweak to an already-demoed feature)? Re-run with
diff --git a/.claude/skills/webjs-scaffold-sync/SKILL.md b/.claude/skills/webjs-scaffold-sync/SKILL.md
index 1d6e88ffa..57f5d46d3 100644
--- a/.claude/skills/webjs-scaffold-sync/SKILL.md
+++ b/.claude/skills/webjs-scaffold-sync/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: webjs-scaffold-sync
-description: Use this skill whenever a change affects what `webjs create` GENERATES (a new or changed gallery/showcase demo, a new template, a changed generated file like the layout/home/theme/schema, a new convention that belongs in generated apps, a new scaffold-shipped config/hook) OR when the user asks to sync the scaffold, "update all three templates", check the scaffold is consistent, or teach agents how to use webjs through the scaffold. The scaffold is webjs's PRIMARY teaching surface for AI agents, so a change to it must propagate in lockstep across the generators, the per-agent rule files, the scaffold tests, the framework docs that describe the scaffold, and the preview/example apps. This skill is the authoritative map of every scaffold surface plus the change-type to surface mapping, and the mandatory "generate + boot + check" verification, so no surface is silently skipped. Complements webjs-doc-sync (which owns framework API/behaviour docs); this skill owns what the scaffold emits.
+description: Use this skill whenever a change affects what `webjs create` GENERATES (a new or changed gallery/showcase demo, a new template, a changed generated file like the layout/home/theme/schema, a new convention that belongs in generated apps, a new scaffold-shipped config/hook) OR what the agent skill `.agents/skills/webjs/` (SKILL.md + references/) TEACHES, OR when the user asks to sync the scaffold or the skill, "update all three templates", check the scaffold is consistent, keep the skill in sync with framework features, or teach agents how to use WebJs. The scaffold teaches AI agents through TWO surfaces that must stay in sync with the framework: the agent skill `.agents/skills/webjs/` (the DURABLE teacher, the only surface that survives `gallery:clear`) and the runnable gallery (DISPOSABLE, removed by `gallery:clear`). A feature change usually needs BOTH. A change to either must propagate in lockstep across the skill, the generators, the per-agent rule files, the scaffold tests, the framework docs that describe the scaffold, and the preview/example apps. This skill is the authoritative map of every surface plus the change-type to surface mapping, and the mandatory "generate + boot + check" verification, so no surface is silently skipped. Complements webjs-doc-sync (which owns framework API/behaviour docs); this skill owns what the scaffold and the skill teach.
 when_to_use: |
   Examples that should trigger this skill:
     "add a new demo to the feature gallery"
@@ -8,9 +8,13 @@ when_to_use: |
     "update all three scaffold templates with this"
     "add a backend-features showcase to the api template"
     "make sure the scaffold teaches agents how to do X"
+    "does the skill teach everything the gallery demonstrates?"
+    "keep .agents/skills/webjs/ in sync with this feature"
+    "the gallery demoes X but the skill does not mention it"
     "did we keep the scaffold rule files in sync?"
     "the saas home / theme / schema changed, sync everything"
-    finishing any change to what `webjs create` generates
+    finishing any change to what `webjs create` generates OR what the
+    agent skill `.agents/skills/webjs/` teaches
   Do NOT trigger for: a framework API/behaviour change with no scaffold
   impact (use webjs-doc-sync), or a pure-internal refactor of the CLI
   that does not change generated output.
@@ -18,11 +22,25 @@ when_to_use: |
 
 # Keep every scaffold surface in sync with what `webjs create` generates
 
-The scaffold is the **primary way AI agents learn webjs**: an agent reads the
-generated gallery/showcase and its comments to learn the idioms, then builds the
-real app by adapting them. So a change to what `webjs create` emits is a
-first-class change with MANY surfaces, and the recurring failure is updating one
-(usually a template file) while the per-agent rule files, the scaffold tests, the
+The scaffold is the **primary way AI agents learn WebJs**, through TWO teaching
+surfaces that must stay in sync with the framework:
+
+1. **The agent skill `.agents/skills/webjs/`** (SKILL.md + references/): the
+   DURABLE teacher. It is the ONE canonical source (bundled into every scaffold
+   at prepack via `scripts/sync-scaffold-skill.mjs`, and the repo's own agent
+   guide). Crucially, `gallery:clear` strips the whole gallery to a blank slate,
+   so the skill is the ONLY teaching surface that SURVIVES, and after a clear it
+   is the agent's sole reference. A feature the skill does not teach is lost the
+   moment an agent clears the gallery.
+2. **The gallery** (`packages/cli/templates/gallery/**`): runnable, densely
+   commented demos an agent learns the idioms from by reading and running, then
+   adapts. It is DISPOSABLE (removed by `gallery:clear` before real work begins).
+
+So a change to a WebJs FEATURE usually needs BOTH: the skill updated (the durable
+pattern) AND a gallery demo (the runnable illustration). A change to what
+`webjs create` emits is a first-class change with MANY surfaces, and the
+recurring failure is updating one (usually a template file, or the gallery but
+not the skill) while the skill, the per-agent rule files, the scaffold tests, the
 framework docs, and the preview apps drift behind. This skill closes that gap.
 
 It is the sibling of `webjs-doc-sync`. Division of labour:
@@ -41,11 +59,14 @@ commit-time floor plus an un-skippable CI gate):
 
 - **Tier 1, the commit floor.** `.claude/hooks/require-scaffold-with-src.sh`
   BLOCKS a commit that stages framework-feature source (`packages/(core|server|cli)/src`)
-  with no scaffold surface (`packages/cli/templates` or `packages/cli/lib`) in the
-  same commit (escape hatch `WEBJS_NO_SCAFFOLD_GATE=1`). Like the test commit
-  gate, it only proves you *touched* a scaffold file; it cannot tell a real demo
-  from a doc bullet, which is exactly how #848 slipped (forbidden()/unauthorized()
-  staged doc bullets, shipped no gallery demo).
+  with no teaching surface in the same commit (escape hatch
+  `WEBJS_NO_SCAFFOLD_GATE=1`). A teaching surface is EITHER the scaffold
+  (`packages/cli/templates` or `packages/cli/lib`) OR the agent skill
+  (`.agents/skills/webjs/`), since the skill is the durable half of the teaching
+  pair. Like the test commit gate, it only proves you *touched* a teaching file;
+  it cannot tell a real demo from a doc bullet, nor that you updated BOTH the
+  gallery and the skill where both were needed, which is exactly how #848 slipped
+  (forbidden()/unauthorized() staged doc bullets, shipped no gallery demo).
 
 - **Tier 2, the CI coverage gate.** `test/scaffolds/gallery-coverage.test.js`
   reconciles the LIVE framework surface against the hand-curated
@@ -72,20 +93,40 @@ verification that neither tier can automate.
 Treat this as the universe. For any scaffold change, decide per surface whether
 it applies, then update or consciously skip each.
 
-1. **The generators** (the code that writes the app):
+1. **The agent skill `.agents/skills/webjs/`** (the DURABLE teacher, canonical at
+   the repo root, bundled into every scaffold at prepack). It is the surface most
+   likely to be forgotten and the most important to keep current, because it is
+   the ONLY teaching surface that survives `gallery:clear`. A new feature, export,
+   idiom, or convention MUST be taught here so an agent building AFTER a clear
+   still learns it:
+   - `.agents/skills/webjs/SKILL.md` (the router: add the concept to the right
+     "what this covers" line and route to the reference).
+   - `.agents/skills/webjs/references/*.md` (the focused reference the feature
+     belongs to, e.g. `data-and-actions.md`, `client-router-and-streaming.md`,
+     `components.md`, `styling.md`, `built-ins.md`). Add the API + the idiom +
+     the gotcha, matching the depth of the sibling entries.
+   - Edit the repo-root copy; `scripts/sync-scaffold-skill.mjs` bundles it into
+     `templates/` at prepack (do NOT hand-edit a bundled copy).
+2. **The generators** (the code that writes the app):
    - `packages/cli/lib/create.js` (the main generator: layout, home page, the
      theme block, db/schema, the full-stack gallery wiring, the per-template
      gates like `isApi` / `isFullStack` / `!isApi`).
    - `packages/cli/lib/api-gallery.js` (the api backend-features showcase). Auth
      is a full-stack GALLERY card now (`templates/gallery/{app/features/auth,
      modules/auth}`), pruned by `gallery:clear`, not a separate template.
+   - `packages/cli/templates/scripts/clear-gallery.mjs` (the `gallery:clear`
+     reset). It strips the app to a barebones blank slate (the gallery, the
+     example design system `components/ui/`, the example theme-toggle + its
+     layout wiring, the example tests, empty leftover dirs), keeping only the
+     buildable base + the skill. A NEW gallery route/module/example-artifact must
+     be added to its removal list, or `gallery:clear` will leave it behind.
    - Any future `*-template.js` / `*-gallery.js` split out for escaping sanity.
-2. **The verbatim template files** copied into every app:
+3. **The verbatim template files** copied into every app:
    - `packages/cli/templates/gallery/**` (the UI feature gallery + example app,
      shipped in full-stack AND saas).
    - `packages/cli/templates/**` (everything else copied per app: `lib/utils/ui.ts`,
      `public/`, `tsconfig.json`, `gitignore`, `.hooks/`, the metadata/route stubs).
-3. **The per-agent rule files** (LOCKSTEP: all carry the SAME rules in each
+4. **The per-agent rule files** (LOCKSTEP: all carry the SAME rules in each
    agent's format, the #134/#136 divergence lesson). A convention/workflow change
    for generated apps must land in ALL of them together:
    - `packages/cli/templates/AGENTS.md`
@@ -96,17 +137,17 @@ it applies, then update or consciously skip each.
    - `packages/cli/templates/.agents/rules/workflow.md`
    - `packages/cli/templates/.gemini/**`, `.opencode/**`, `.claude/**` (whatever
      per-agent rule files the scaffold currently ships; enumerate, do not assume)
-4. **The scaffold tests**: `test/scaffolds/*.test.js` (e.g. `scaffold-gallery`,
+5. **The scaffold tests**: `test/scaffolds/*.test.js` (e.g. `scaffold-gallery`,
    `scaffold-ui-integration`). A new demo/template/generated-file assertion goes
    here, including the counterfactual (a per-template exclusion test).
-5. **The framework docs that DESCRIBE the scaffold** (shared with doc-sync):
+6. **The framework docs that DESCRIBE the scaffold** (shared with doc-sync):
    - Root `AGENTS.md` "Scaffolding" section.
    - The docs site: `docs/app/docs/getting-started/page.ts` (+ `backend-only`,
      `ai-first`, `conventions` where they describe generated structure).
    - `README.md` (the template matrix + the "scaffold is the tutorial" note).
-6. **The CLI surface**: `packages/cli/` `--template` validation + `--help`/usage
+7. **The CLI surface**: `packages/cli/` `--template` validation + `--help`/usage
    text when a template or flag is added or renamed.
-7. **The preview / example / dogfood apps**: `examples/blog/` and any in-repo
+8. **The preview / example / dogfood apps**: `examples/blog/` and any in-repo
    apps, plus the local preview apps the user tests, when a convention they
    demonstrate changes.
 
@@ -114,7 +155,8 @@ it applies, then update or consciously skip each.
 
 | Change | Surfaces that MUST be checked |
 |---|---|
-| New / changed **gallery or showcase demo** | the template file(s) or generator strings for the demo + the home-page `features`/index array + the scaffold AGENTS.md gallery list + `test/scaffolds/*` FEATURES/assertions + **generate + boot the affected template** |
+| New / changed **WebJs feature, export, idiom, or convention** an agent must know | **the agent skill** `.agents/skills/webjs/` FIRST (SKILL.md routing line + the right `references/*.md`), the DURABLE teacher that survives `gallery:clear`, THEN a gallery demo (surface 2/3). Skill-without-demo means no runnable example; demo-without-skill means the pattern is LOST the moment an agent clears the gallery. A feature needs BOTH. |
+| New / changed **gallery or showcase demo** | the template file(s) or generator strings for the demo + the home-page `features`/index array + the scaffold AGENTS.md gallery list + the `gallery:clear` removal list (`templates/scripts/clear-gallery.mjs`, so the new demo/module is stripped to a blank slate) + `test/scaffolds/*` FEATURES/assertions + **generate + boot the affected template** |
 | New / removed **template** | the `create.js` template branch (+ a `*-template.js` if large) + the "only N templates exist" list in EVERY per-agent rule file + the framework `AGENTS.md`/getting-started/README template matrix + the CLI `--template` validation + `--help` + `test/scaffolds/*` |
 | New **control-flow throw or routing boundary file** (`notFound` / `redirect` / `forbidden` / `unauthorized` and their `not-found` / `forbidden` / `unauthorized` / `error` / `loading` / `global-error` / `global-not-found` boundary files) | a runnable **gallery demo** that exercises it (a route that throws it plus the nearest boundary file), NOT just an app-tree bullet in the rule files + the home-page `features` array + `test/scaffolds/*` FEATURES/boundary-file asserts + **generate + boot + hit the route**. A doc bullet in `AGENTS.md` / `CONVENTIONS.md` is necessary but NOT sufficient: the gallery is the primary teaching surface, so an undemoed thrower is invisible to a scaffolding agent (the #848 gap). Carve-out: a **root-only** boundary (`global-error` / `global-not-found`) cannot mount under `app/features/` without clashing with the generated app root, so teach those in the demo's PROSE rather than as a live route. |
 | New / renamed **public `@webjsdev/core` or `@webjsdev/server` export, or a new routing convention file** the router parses | `test/scaffolds/gallery-coverage.json` MUST classify it (a `{ demo }` / `{ demoed: true }`, or `{ exempt }` with an `internal:` / `deferred:` reason) or the tier-2 CI gate (`gallery-coverage.test.js`) FAILS. Prefer a real demo; `deferred:` is a conscious, reviewer-visible exemption tracked for later. This is the coverage-gate teeth described above. |
@@ -168,6 +210,13 @@ it applies, then update or consciously skip each.
    describes stale behaviour there (a classic gap: a demo added to the full-stack
    home but missing from the saas home, or a scoping phrase updated in one rule
    file but not the other five).
+   - **Skill-vs-gallery coverage sweep** (the highest-value audit now that
+     `gallery:clear` strips the gallery): for EACH gallery demo
+     (`app/features/<x>` + its `modules/<x>`), confirm the concept it teaches is
+     also taught in `.agents/skills/webjs/references/*.md`. A concept the gallery
+     demonstrates but the skill omits is a GAP, because it vanishes at
+     `gallery:clear` and the agent building the real app never sees it. Fill it in
+     the matching reference at the depth of its siblings.
 4. For a bulk audit, file a grounded follow-up via **webjs-file-issue** per gap
    (title `scaffold: <surface> missing <thing>`); for a single in-flight change,
    just fix all surfaces on the same PR.

From c52b1ddb76307648461d5abfc7b9596e0577cd2b Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 12:43:35 +0530
Subject: [PATCH 10/73] test: cover the truly-minimal gallery:clear blank slate

Assert gallery:clear strips the gallery + example design system + example
theme-toggle (and its layout/home wiring) + example tests + empty leftover dirs,
while keeping the skill, layout, db wiring, and cn.ts. Pre-clear existence asserts
are the counterfactual. No full-stack clear test existed before.
---
 test/scaffolds/scaffold-gallery.test.js | 68 +++++++++++++++++++++++++
 1 file changed, 68 insertions(+)

diff --git a/test/scaffolds/scaffold-gallery.test.js b/test/scaffolds/scaffold-gallery.test.js
index dad5f2fd5..99bbf91e7 100644
--- a/test/scaffolds/scaffold-gallery.test.js
+++ b/test/scaffolds/scaffold-gallery.test.js
@@ -159,6 +159,74 @@ test('todo query uses rc.3 object-form orderBy (regression guard)', async () =>
   }
 });
 
+test('full-stack gallery:clear strips the app to a barebones blank slate', async () => {
+  // gallery:clear must leave a minimal buildable base, not "the scaffold minus
+  // the gallery". It removes the gallery, the example design system, the example
+  // theme-toggle (+ its layout/home wiring), the example tests, and every empty
+  // leftover dir; it keeps the durable skill, the layout, db wiring, and cn.ts.
+  // The pre-clear existence asserts are the counterfactual (they prove each thing
+  // was really there to remove).
+  const cwd = await tempCwd();
+  try {
+    await scaffoldApp('demo', cwd, { template: 'full-stack', install: false });
+    const appDir = join(cwd, 'demo');
+    const has = (...p) => existsSync(join(appDir, ...p));
+
+    // Counterfactual: everything gallery:clear should strip is present first.
+    assert.ok(has('app', 'features'), 'pre: app/features exists');
+    assert.ok(has('app', 'examples'), 'pre: app/examples exists');
+    assert.ok(has('modules', 'todo'), 'pre: modules/todo exists');
+    assert.ok(has('components', 'ui', 'button.ts'), 'pre: components/ui design system exists');
+    assert.ok(has('components', 'theme-toggle.ts'), 'pre: example theme-toggle exists');
+    assert.ok(has('test', 'hello'), 'pre: example test suite exists');
+    assert.ok(has('app', 'api', 'auth'), 'pre: gallery auth handler under app/api exists');
+    assert.match(await readFile(join(appDir, 'app', 'layout.ts'), 'utf8'), /theme-toggle/, 'pre: layout imports theme-toggle');
+
+    execFileSync(process.execPath, ['scripts/clear-gallery.mjs'], { cwd: appDir, stdio: 'ignore' });
+
+    // Removed: the gallery + example design system + example artifacts.
+    assert.equal(has('app', 'features'), false, 'app/features removed');
+    assert.equal(has('app', 'examples'), false, 'app/examples removed');
+    assert.equal(has('modules', 'todo'), false, 'demo module removed');
+    assert.equal(has('modules', 'auth'), false, 'auth demo module removed');
+    assert.equal(has('components', 'ui'), false, 'components/ui design system removed');
+    assert.equal(has('components', 'theme-toggle.ts'), false, 'example theme-toggle removed');
+    assert.equal(has('test', 'hello'), false, 'example test suite removed');
+    // Empty leftover dirs pruned to a true blank slate.
+    assert.equal(has('app', 'api'), false, 'empty app/api pruned');
+    assert.equal(has('test', 'unit'), false, 'empty test/unit pruned');
+    assert.equal(has('test', 'e2e'), false, 'empty test/e2e pruned');
+    assert.equal(has('test'), false, 'empty test/ pruned');
+
+    // Kept: the buildable base.
+    assert.ok(has('.agents', 'skills', 'webjs', 'SKILL.md'), 'the durable agent skill is kept');
+    assert.ok(has('lib', 'utils', 'cn.ts'), 'cn.ts kept (webjs ui add prerequisite)');
+    assert.ok(has('db', 'connection.server.ts'), 'db wiring kept');
+    assert.ok(has('components'), 'components/ kept as an (empty) build target');
+    assert.ok(has('modules'), 'modules/ kept as an (empty) build target');
+    assert.ok(has('app', 'layout.ts'), 'root layout kept');
+
+    // The layout no longer references the removed theme-toggle, but keeps its
+    // OS-preference dark-mode script (works with no component, JS off).
+    const layout = await readFile(join(appDir, 'app', 'layout.ts'), 'utf8');
+    assert.doesNotMatch(layout, /theme-toggle/, 'layout theme-toggle import stripped');
+    assert.match(layout, /prefers-color-scheme/, 'layout keeps OS-preference dark mode');
+
+    // The reset home is minimal: no <theme-toggle>, no gallery links.
+    const home = await readFile(join(appDir, 'app', 'page.ts'), 'utf8');
+    assert.doesNotMatch(home, /theme-toggle/, 'reset home drops theme-toggle');
+    assert.doesNotMatch(home, /\/features\//, 'reset home has no gallery links');
+
+    // The schema is reverted to the minimal base (no demo todos, no auth column).
+    const schema = await readFile(join(appDir, 'db', 'schema.server.ts'), 'utf8');
+    assert.doesNotMatch(schema, /export const todos = table/, 'todos table dropped');
+    assert.doesNotMatch(schema, /passwordHash/, 'auth passwordHash column dropped');
+    assert.match(schema, /defineRelations\(\{ users \}/, 'relations reverted to users only');
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
 test('feature pages have no stale /examples/ links after the features refactor', async () => {
   // Regression guard: moving the demos from app/examples/ to app/features/ must
   // update the in-page hrefs too, not just the marker text. The ONLY valid

From be343b7e6d28c1ab3bb83e926c149750c40e2a0e Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 12:47:36 +0530
Subject: [PATCH 11/73] docs(skill): teach effect/batch, Task, context, and the
 directive set

The gallery demos (reactive-meter, task-loader, theme-context, directive-demo)
teach these, but the skill omitted them, so they vanished at gallery:clear. Add
effect/batch to the signals section, and new sections for Task/TaskStatus,
the context API, and a lit-html directive table.
---
 .agents/skills/webjs/references/components.md | 82 ++++++++++++++++++-
 1 file changed, 81 insertions(+), 1 deletion(-)

diff --git a/.agents/skills/webjs/references/components.md b/.agents/skills/webjs/references/components.md
index 965168c91..c842fefe6 100644
--- a/.agents/skills/webjs/references/components.md
+++ b/.agents/skills/webjs/references/components.md
@@ -3,11 +3,13 @@
 ## What This Covers
 
 - Declaring reactive properties through the `WebComponent({ ... })` factory and `prop()`, with options (`reflect`, `state`, `attribute`, `default`, `converter`, `hasChanged`)
-- Signals as the default state primitive for component-local and shared state
+- Signals as the default state primitive for component-local and shared state, plus `effect` / `batch`
 - The Lit-aligned lifecycle and exactly which hooks SSR runs versus skips
 - Light DOM (default) versus shadow DOM, and the light-host `display: block` rule
 - Slots with full shadow-DOM parity in both DOM modes
 - `async render()`: SSR-blocking first paint, client stale-while-revalidate, `renderFallback()` / `renderError()`
+- `Task` for client-only async data, and context (`createContext` / `ContextProvider` / `ContextConsumer`) to avoid attribute drilling
+- The lit-html directive set (`repeat`, `watch`, `live`, `keyed`, `guard`, `cache`, `until`, `unsafeHTML`, `ref`, `asyncAppend` / `asyncReplace`, `templateContent`)
 - Display-only elision (when a component is stripped from the browser)
 - Inherited members app code must NOT shadow (`title`, `remove`, `render`, ...)
 
@@ -70,6 +72,19 @@ const count = computed(() => cart.get().length); // derived
 
 Read with `signal.get()` inside `render()`; the built-in `SignalWatcher` tracks the read and re-renders on change. An instance signal created in the constructor is component-local. For a fine-grained DOM swap use `${watch(signal)}` from `@webjsdev/core/directives`.
 
+Two more signal primitives from `@webjsdev/core` cover client-side reactions and batched writes:
+
+- `effect(fn)` runs `fn` now and re-runs it whenever a signal it read changes. It is a BROWSER-ONLY side-effect primitive (a subscription, a `document.title` sync, an analytics ping), not a render path. It returns a disposer, so create it in `connectedCallback` and call the disposer in `disconnectedCallback` to avoid a leak.
+- `batch(fn)` coalesces several `.set()` writes inside `fn` into ONE re-render instead of one per write. Reach for it when a handler updates multiple signals at once.
+
+```ts
+import { signal, effect, batch } from '@webjsdev/core';
+const open = signal(false), count = signal(0);
+connectedCallback() { super.connectedCallback(); this.dispose = effect(() => { document.title = `(${count.get()})`; }); }
+disconnectedCallback() { super.disconnectedCallback(); this.dispose?.(); }
+reset() { batch(() => { open.set(false); count.set(0); }); }   // one re-render, not two
+```
+
 ## Lifecycle (Lit-aligned) and what SSR runs
 
 Each update cycle runs these in order; each receives a `changedProperties` Map.
@@ -158,6 +173,71 @@ Errors are isolated per component by default (no user code): a thrown `await` re
 
 Decision rules. Use `async render()` for request-time server data that should be in the first paint (the default). Add `renderFallback()` when a client re-fetch's stale content would mislead. Use `Task` / signals for genuinely client-only data (a click, viewport, live updates). For SLOW data where blocking the first byte hurts, wrap the region in `<webjs-suspense .fallback=${html\`Loading...\`}>` to stream it (the only way to show a first-paint fallback; see `client-router-and-streaming.md`). Do NOT fetch in `connectedCallback` for data knowable server-side, and do NOT prop-drill what a leaf can fetch itself.
 
+## Task: client-only async data
+
+For async data that is genuinely CLIENT-only (it depends on a click, viewport, or a live source, so `async render()` cannot bake it in at SSR), use the `Task` reactive controller. It shows its pending state at SSR (staying `INITIAL`), then runs in the browser.
+
+```ts
+import { Task, TaskStatus } from '@webjsdev/core/task';
+
+class SearchResults extends WebComponent({ q: String }) {
+  #search = new Task(this, {
+    task: async ([q], { signal }) => (await fetch(`/api/s?q=${q}`, { signal })).json(),
+    args: () => [this.q],   // the args array spreads into the task's first parameter
+  });
+  render() {
+    switch (this.#search.status) {
+      case TaskStatus.PENDING: return html`<p>Searching...</p>`;
+      case TaskStatus.ERROR:   return html`<p>${this.#search.error.message}</p>`;
+      case TaskStatus.COMPLETE: return html`<ul>${this.#search.value.map((r) => html`<li>${r.title}</li>`)}</ul>`;
+      default: return html`<p>Type to search.</p>`;   // INITIAL (also the SSR state)
+    }
+  }
+}
+```
+
+`args()` re-runs the task whenever its return changes; call `this.#task.run()` to trigger it manually. `TaskStatus` is `INITIAL` / `PENDING` / `COMPLETE` / `ERROR`. Prefer `async render()` for server data that should be in the first paint; reach for `Task` only when the data cannot exist until the browser runs.
+
+## Context: share state without attribute drilling
+
+When a value must reach a deep descendant without threading it through every intermediate component's attributes, use context (from `@webjsdev/core/context`). This is a CLIENT-TIME concern: a provider publishes on connect, so context is empty at SSR. For server-known data, pass it through the page function or a `.prop` instead (see `muscle-memory-gotchas.md`).
+
+```ts
+import { createContext, ContextProvider, ContextConsumer } from '@webjsdev/core/context';
+
+export const themeContext = createContext<'light' | 'dark'>('theme');
+
+class ThemeRoot extends WebComponent({}) {
+  #provider = new ContextProvider(this, { context: themeContext, initialValue: 'dark' });
+  toggle() { this.#provider.setValue(this.#provider.value === 'dark' ? 'light' : 'dark'); }
+}
+
+class ThemedCard extends WebComponent({}) {
+  #theme = new ContextConsumer(this, { context: themeContext, subscribe: true }); // re-renders on change
+  render() { return html`<div class=${this.#theme.value === 'dark' ? 'bg-black' : 'bg-white'}>...</div>`; }
+}
+```
+
+`subscribe: true` re-renders the consumer on every provider change; omit it for a one-shot read. A component can also fire a `ContextRequestEvent` to pull a value imperatively.
+
+## Directives (lit-html parity)
+
+Import from `@webjsdev/core/directives`. Everything a `class`/`style`/conditional needs is plain JS (`classMap` is `class=${cond ? 'a' : 'b'}`, `when` is a ternary, `map` is `.map`); reach for a directive only for the jobs below.
+
+| Directive | Use it for |
+|---|---|
+| `repeat(items, keyFn, tpl)` | A keyed list where items reorder / insert / remove (preserves DOM + state per key). A static list is a plain `.map`. |
+| `watch(signal)` | A fine-grained DOM swap of one signal's value without re-rendering the whole component. |
+| `live(value)` | An `input` / `textarea` `.value` bound to state, so a user edit that equals the last committed value still resets. |
+| `keyed(key, tpl)` | Force a fresh subtree (discard old DOM + state) when `key` changes. |
+| `guard(deps, () => tpl)` | Skip re-rendering an expensive subtree unless `deps` change. |
+| `cache(tpl)` | Keep the DOM of an inactive branch around when toggling between templates. |
+| `until(promise, fallback)` | Render `fallback` until `promise` resolves (prefer `Task` in a component, `Suspense` for a page). |
+| `unsafeHTML(str)` | Render a TRUSTED raw HTML string. NEVER pass user input (XSS). |
+| `ref(cb)` / `createRef()` | Get a handle to the rendered DOM node. |
+| `asyncAppend(iter)` / `asyncReplace(iter)` | Stream from an async iterable, appending each value or replacing with the latest. |
+| `templateContent(el)` | Render the content of a `<template>` element. |
+
 ## Display-only elision
 
 A component that does no client-side work renders the same SSR'd HTML with or without its JS, so WebJs strips its import from the served source (and any vendor reachable only through it). This is automatic and conservative. A component stays elidable while it has NONE of:

From 4624f244371a99405c3bc2e0637249a229ab0a99 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 12:48:39 +0530
Subject: [PATCH 12/73] docs(skill): teach enableClientRouter, connectWS
 handle, and gotchas

Fill gaps the gallery demos (router-controls, ws-echo, broadcast-feed, stream-demo,
view-transitions) teach but the skill omitted: enableClientRouter() as the toggle
counterpart, the connectWS return handle (.send/.close) + onOpen/onClose lifecycle,
the renderStream-clobber gotcha (plain field not signal), and the metadata.other
form for the per-page view-transition opt-in.
---
 .../references/client-router-and-streaming.md | 30 ++++++++++++++++---
 1 file changed, 26 insertions(+), 4 deletions(-)

diff --git a/.agents/skills/webjs/references/client-router-and-streaming.md b/.agents/skills/webjs/references/client-router-and-streaming.md
index 2f896cb23..dbe7fecbe 100644
--- a/.agents/skills/webjs/references/client-router-and-streaming.md
+++ b/.agents/skills/webjs/references/client-router-and-streaming.md
@@ -35,10 +35,13 @@ Note for anyone testing this: **the Chromium web-test-runner currently resolves
 ```
 
 ```js
-import { disableClientRouter } from '@webjsdev/core';
-disableClientRouter();
+import { disableClientRouter, enableClientRouter } from '@webjsdev/core';
+disableClientRouter();   // stop intercepting document <a> / <form> (plain links resume full loads)
+enableClientRouter();    // turn soft navigation back on
 ```
 
+`disableClientRouter()` / `enableClientRouter()` are a runtime pair that toggle only the document-level `<a>` / `<form>` interception. An explicit `navigate(url)` call still does a soft navigation either way (it is not gated by the toggle).
+
 Per link, opt out with `data-no-router` (auth flows like `/logout`, OAuth redirects, print views, an experimental route with a different runtime). Cross-origin hrefs, `download`, a non-`_self` target, pure same-page hash jumps, and non-HTML extensions are auto-skipped.
 
 **Programmatic navigation and cache eviction.**
@@ -113,6 +116,13 @@ The router can wrap a navigation's DOM mutation in the native View Transitions A
 <meta name="view-transition" content="same-origin">
 ```
 
+A page (or layout) does not write raw `<head>` markup, so emit that meta through the `other` metadata field, which scopes it to the page that declares it:
+
+```ts
+// app/gallery/page.ts
+export const metadata = { other: { 'view-transition': 'same-origin' } };
+```
+
 The accepted value is `same-origin`. When enabled it wraps every swap path (the two-tier boundary swap, the `<webjs-frame>` swap, and the background-revalidation full-body path). When `startViewTransition` is unavailable the swap runs synchronously with no flash and no throw. To persist a live element (a playing `<audio>`, an open menu) across a swap by node identity, mark it `data-webjs-permanent` and give it an `id`.
 
 The opt-in is **per page**, so it is a page-scoped meta: put it on a page's metadata to animate that page, or on the root layout to animate the whole app. Navigating to a page that does NOT declare it turns transitions back off, because the soft-nav head merge reconciles page-scoped `<meta>` tags (a stale one the previous page declared is removed, not left to leak, #1046). View transitions **compose with Suspense streaming**: a streamed boundary (a `loading.{js,ts}` skeleton or a `<webjs-suspense>` region) navigated to under an active transition still resolves its content progressively, because the streamed resolve waits for the transition's DOM swap to commit before it applies (#1048).
@@ -188,13 +198,25 @@ export function WS(ws, req, { params }) {
 }
 ```
 
-**Client.** `connectWS(url, handlers)` from `@webjsdev/core` auto-reconnects with exponential backoff, handles JSON parse/stringify, and queues sends while disconnected.
+**Client.** `connectWS(url, handlers)` from `@webjsdev/core` auto-reconnects with exponential backoff, handles JSON parse/stringify, and queues sends while disconnected. The handler set is `{ onOpen, onMessage, onClose }`, and it RETURNS a connection handle with `.send(data)` and `.close()`. Open it in `connectedCallback` and close it in `disconnectedCallback`, driving a connection-status signal from `onOpen` / `onClose`:
 
 ```js
 import { connectWS, renderStream } from '@webjsdev/core';
-connectWS('/feed', { onMessage: (m) => renderStream(m) });
+
+connectedCallback() {
+  super.connectedCallback();
+  this.conn = connectWS('/feed', {
+    onOpen:    () => (this.online = true),
+    onClose:   () => (this.online = false),
+    onMessage: (m) => renderStream(m),   // apply a server-pushed <webjs-stream> payload
+  });
+}
+disconnectedCallback() { super.disconnectedCallback(); this.conn?.close(); }
+send(text) { this.conn.send(text); }
 ```
 
+**Gotcha: a component re-render clobbers surgical `renderStream()` updates.** `renderStream()` (and `<webjs-stream>` in general) mutates the DOM out of band, appending rows the component's own `render()` does not know about. If the component then re-renders, `render()` re-runs and wipes those out-of-band rows. So render the target container ONCE and drive any mutation counter with a PLAIN instance field, never a signal or reactive prop that `render()` reads (a read would re-render and blow away the streamed-in DOM).
+
 **Broadcast.** `broadcast(path, data)` from `@webjsdev/server` fans a message to every connected client on that path (single-instance). For multi-instance, add Redis pub/sub yourself, there is no framework magic.
 
 ## Navigation-Loading Indicator (opt-in)

From e8f275d8d911e2a7ec173cdd0e1389324f16df10 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 12:49:26 +0530
Subject: [PATCH 13/73] docs(skill): teach actionSignal cancellation and the
 middleware ctx shape

The server-actions demo teaches actionSignal() (request AbortSignal, the 499
cancelled-envelope pattern) and the per-action middleware ctx { request, args,
signal, context } with ctx.context writes read back via actionContext(); the
skill named them but never showed them. Add both.
---
 .../webjs/references/data-and-actions.md      | 21 +++++++++++++++++--
 1 file changed, 19 insertions(+), 2 deletions(-)

diff --git a/.agents/skills/webjs/references/data-and-actions.md b/.agents/skills/webjs/references/data-and-actions.md
index b5d2fa44a..03892f208 100644
--- a/.agents/skills/webjs/references/data-and-actions.md
+++ b/.agents/skills/webjs/references/data-and-actions.md
@@ -5,7 +5,7 @@
 - The `modules/<feature>/` architecture (thin `app/` adapters, `actions/` mutations, `queries/` reads, one function per file)
 - `'use server'` RPC actions, the serializer-safe wire, and how a client import becomes a typed stub
 - Input validation at the boundary via `export const validate`
-- HTTP-verb config exports (`method`, `cache`, `tags`, `invalidates`, `middleware`)
+- HTTP-verb config exports (`method`, `cache`, `tags`, `invalidates`, `middleware`), the middleware `ctx` shape, and `actionSignal()` cancellation
 - The `ActionResult<T>` envelope and its robust failure detection
 - The `route()` REST adapter that exposes an action over HTTP
 - Drizzle rc.3 reads (`db.query.*`) and mutations (`.returning()`)
@@ -141,7 +141,24 @@ export async function updateUser(id: number, patch: Partial<User>) { /* ... */ }
 
 - A **GET** rides args in the URL (POST fallback over a 4KB cap), is CSRF-exempt, and carries `Cache-Control` + a weak `ETag` (304 on `If-None-Match`) + `X-Webjs-Tags`. A **mutation** (POST/PUT/PATCH/DELETE) sends the rich body (DELETE rides the URL), is CSRF-protected, and on success evicts its `invalidates` tags and reports them via `X-Webjs-Invalidate`. A method mismatch is a `405` + `Allow`.
 - **SAFETY.** `cache` with `public: true` SHARES one response across ALL users, keyed only by URL + args. Use it ONLY for data identical for every visitor (the same rule as a page's `export const revalidate`), never for a session or per-user read.
-- Per-action `middleware` short-circuits by returning an `ActionResult` instead of calling `next()`, and accumulates context the action reads via `actionContext()` from `@webjsdev/server`.
+- Per-action `middleware` short-circuits by returning an `ActionResult` instead of calling `next()`, and accumulates context the action reads via `actionContext()` from `@webjsdev/server`. Each middleware is `async (ctx, next) => result` where `ctx` is `{ request, args, signal, context }`. It writes to the shared bag `ctx.context.<key>` (for example `ctx.context.user = user`), which is exactly what `actionContext().user` reads back in the action. A direct server-to-server call skips the RPC boundary (so its middleware does NOT run), so the action must guard rather than assume a middleware-set value is present.
+
+### Cancellation with `actionSignal()`
+
+Inside an action, `actionSignal()` from `@webjsdev/server` returns the request's `AbortSignal`. It fires when the client disconnects OR when a newer client render supersedes this one (the RPC stub aborts the previous in-flight fetch). Thread it into the work you start, and re-check it after an await to map an abort to a cancelled envelope:
+
+```ts
+'use server';
+import { actionSignal } from '@webjsdev/server';
+export async function search(q: string) {
+  const signal = actionSignal();
+  const res = await fetch(`https://api/x?q=${q}`, { signal });   // aborts the fetch on disconnect
+  if (signal.aborted) return { success: false, error: 'Request cancelled.', status: 499 };
+  return { success: true, data: await res.json() };
+}
+```
+
+A guard placed BEFORE any await can never fire (nothing has yielded yet). Outside an action the signal never aborts, so a server-to-server call stays safe.
 
 ## The `ActionResult<T>` envelope
 

From b0762d5386068d624fd5654c64c5e93e3a980aac Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 12:50:22 +0530
Subject: [PATCH 14/73] docs(skill): teach the route-handler toolkit,
 richFetch, and image routes

The route-handler + metadata-image demos teach json()/readBody()/clientIp() (and
the no-arg accessor convention), richFetch() for hand-calling your own route.ts,
and image metadata routes that return a Response with an inline SVG referenced
from metadata; the skill omitted all three. Add them.
---
 .../webjs/references/routing-and-pages.md     | 27 +++++++++++++++++--
 1 file changed, 25 insertions(+), 2 deletions(-)

diff --git a/.agents/skills/webjs/references/routing-and-pages.md b/.agents/skills/webjs/references/routing-and-pages.md
index f9e9f659e..470807227 100644
--- a/.agents/skills/webjs/references/routing-and-pages.md
+++ b/.agents/skills/webjs/references/routing-and-pages.md
@@ -4,8 +4,8 @@
 
 - Pages, layouts, and where the HTML shell comes from
 - Dynamic (`[param]`), catch-all (`[...rest]`), and optional catch-all (`[[...rest]]`) segments, route groups, private folders
-- `route.ts` HTTP handlers and `middleware.ts`
-- `metadata` and `generateMetadata` (folded in here)
+- `route.ts` HTTP handlers and `middleware.ts`, the route-handler toolkit (`json` / `readBody` / `clientIp` / the no-arg accessors), and calling one from the client with `richFetch`
+- `metadata` and `generateMetadata` (folded in here), including image metadata routes that return a `Response`
 - Control-flow throws: `notFound()`, `redirect()`, `forbidden()`, `unauthorized()`
 - The no-JS page `action` write path
 - Boundaries: `error.ts`, `loading.ts`, `not-found.ts`, `forbidden.ts`, `unauthorized.ts`, and the two root-only ones
@@ -78,6 +78,18 @@ export async function GET() {
 
 **NEVER throw `redirect()` / `notFound()` / `forbidden()` inside a `route.ts` handler** (an uncaught throw is a generic 500). Return a real response instead: `return Response.redirect(url, 303)` for a redirect, `return new Response('Not Found', { status: 404 })` for a 404. A `route.ts` is also NOT covered by the action CSRF check, so authenticate every mutating endpoint, validate, and rate-limit. Export `WS(ws, req, { params })` from the same file for a WebSocket endpoint.
 
+**The route-handler toolkit** (from `@webjsdev/server`). Two accessors take the request explicitly: `readBody(req)` decodes a rich request body (the inverse of `json()`, round-tripping `Date` / `Map` / `Set` / `BigInt` / `Blob`), and `clientIp(req)` reads the caller IP. To respond with rich types, `json(value)` serializes with the same wire (so a `Date` survives), versus a plain object return that auto-JSONs. The context accessors take NO argument because they read the in-flight request from context: `headers()`, `cookies()`, `requestId()`, `cspNonce()`.
+
+```ts
+import { json, readBody, clientIp } from '@webjsdev/server';
+export async function POST(req: Request) {
+  const body = await readBody(req);            // rich types decoded
+  return json({ at: new Date(), ip: clientIp(req) });  // Date survives the wire
+}
+```
+
+**Calling your own `route.ts` from the client:** use `richFetch<T>(url, opts?)` from `@webjsdev/core`, a drop-in `fetch` that sends `Accept: application/vnd.webjs+json`, encodes a plain-object `body` with the rich wire, and decodes the `json()` response (so `data.at` is a real `Date`). This is the ONE legitimate hand-fetch (importing a `'use server'` action is the way to call the server otherwise, never a hand-written `fetch` to an action).
+
 ## Middleware (`middleware.ts`)
 
 Optional root-level plus per-segment. The default export is `async (req, next) => Response`. Return a Response to short-circuit, or call `next()` and post-process. Per-segment middleware applies to its subtree, outermost to innermost.
@@ -156,3 +168,14 @@ How the result is read (server side): a success PRG-redirects with `303` (to a s
 - Root-only (in `app/` exactly): `global-error.ts` is the app-wide catch-all after nested `error` boundaries are exhausted and renders its OWN `<!doctype><html><body>` (returned verbatim, so keep it static HTML with no components or hydration). `global-not-found.ts` renders for an unmatched-anywhere URL when no `not-found` matches.
 
 Metadata routes (`sitemap.ts`, `robots.ts`, `manifest.ts`, `icon.ts`, `apple-icon.ts`, `opengraph-image.ts`, `twitter-image.ts`) live at app root or static segments and default-export a possibly-async function; `sitemap()` / `sitemapIndex()` from `@webjsdev/server` serialize spec-valid XML.
+
+The IMAGE metadata routes (`icon`, `apple-icon`, `opengraph-image`, `twitter-image`) default-export a function returning a `Response` with an explicit `content-type`, so an inline SVG needs no asset file (buildless). Then point `metadata` at the route via `openGraph.images` / `twitter.images` / `icons` (or drop a static file in `public/` instead).
+
+```ts
+// app/opengraph-image.ts  (OG is 1200x630; apple-icon 180x180)
+export default function OgImage() {
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630">...</svg>`;
+  return new Response(svg, { headers: { 'content-type': 'image/svg+xml' } });
+}
+// app/page.ts  ->  export const metadata = { openGraph: { images: ['/opengraph-image'] } };
+```

From 08e6f6c37e5d712099540e34552ed4b9aeb65af1 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 12:52:12 +0530
Subject: [PATCH 15/73] docs(skill): fix the session API and teach the full
 auth flow

The auth/sessions demos teach what the skill omitted or got wrong: the Session
method API (.get/.set/.flash/.destroy, replacing the incorrect s.userId=
property style), the cookieSession/storeSession storage factories, scrypt
password hash/compare (the skill referenced a nonexistent verifyPassword),
mounting handlers at app/api/auth/[...path] with the fixed-path constraint, the
no-JS login/logout form flow (redirectTo + pages.error + ?error), and per-segment
middleware protection via auth(req).
---
 .../webjs/references/auth-and-sessions.md     | 94 +++++++++++++++----
 1 file changed, 78 insertions(+), 16 deletions(-)

diff --git a/.agents/skills/webjs/references/auth-and-sessions.md b/.agents/skills/webjs/references/auth-and-sessions.md
index d91398665..1053ab00d 100644
--- a/.agents/skills/webjs/references/auth-and-sessions.md
+++ b/.agents/skills/webjs/references/auth-and-sessions.md
@@ -2,10 +2,10 @@
 
 ## What This Covers
 
-- Sessions: cookie by default, Redis-backed when configured, the `SESSION_SECRET` requirement
-- Authentication: `createAuth` (NextAuth-style), Credentials plus OAuth providers, `auth()` in a page or action
-- Login and logout flows (`signIn` / `signOut` / `handlers`)
-- Protecting a route: gate at the top of a page or action, redirect when unauthenticated
+- Sessions: the `session()` middleware + storage factories (`cookieSession` / `storeSession`), the `getSession(req)` method API (`.get` / `.set` / `.flash` / `.destroy`), the `SESSION_SECRET` requirement
+- Authentication: `createAuth` (NextAuth-style), Credentials plus OAuth providers, `auth()` in a page or action, scrypt password hashing
+- Login and logout flows: mounting `handlers` at `app/api/auth/[...path]`, the no-JS credentials form (`/api/auth/signin/credentials` + `redirectTo` + `?error`), `signIn` / `signOut`
+- Protecting a route: a page-top `auth()` gate OR a per-segment `middleware.ts` calling `auth(req)`
 - `forbidden()` (403) vs `unauthorized()` (401) and their nearest-wins boundary files
 - Returning an `ActionResult` for an auth failure inside a `'use server'` action (do NOT throw there)
 - The Origin / `Sec-Fetch-Site` CSRF model (not a token cookie)
@@ -21,23 +21,30 @@ scaling, the full caching surface).
 
 ## Sessions
 
-Enable sessions in middleware, read and write them in a page or action.
+Enable sessions with `session()` MIDDLEWARE, then read and write them with `getSession(req)` in any route or middleware the session wraps.
 
 ```ts
-// middleware.ts: enable on all routes
-import { session } from '@webjsdev/server';
-export default session();   // auto: REDIS_URL present -> server-side, else -> cookie
+// middleware.ts: enable on all routes. Storage is pluggable.
+import { session, cookieSession, storeSession } from '@webjsdev/server';
+export default session({ secret: process.env.SESSION_SECRET, storage: cookieSession() });
+// cookieSession()  -> whole session in a signed cookie (stateless, the default)
+// storeSession()   -> session in the active store (memoryStore in dev, Redis in prod), id in the cookie
+```
 
-// in a page or action
+`getSession(req)` returns a small key/value `Session` with a METHOD API, not property assignment. Mutating it makes the middleware re-sign and set the cookie on the way out:
+
+```ts
 import { getSession } from '@webjsdev/server';
-const s = getSession(req);
-s.userId = user.id;         // auto-saved after the response
+export async function GET(req: Request) {
+  const s = getSession(req);
+  s.set('userId', user.id);            // write
+  const id = s.get('userId');          // read
+  s.flash('notice', 'Saved');          // one-read-only value (cleared after the next read)
+  s.destroy();                         // clear the whole session (logout)
+}
 ```
 
-Cookie sessions (the default) are signed and encrypted with no server
-state. Store sessions (with Redis) keep the session id in the cookie and
-the data in Redis. Both require `SESSION_SECRET`, read from the
-environment (never a literal in source) so boot fails if it is missing.
+Cookie sessions (the default) are signed with no server state; store sessions keep only the id in the cookie and the data in the store. `cookieSession` / `storeSession` are aliases for `cookieSessionStorage` / `storeSessionStorage`. Both strategies require `SESSION_SECRET`, read from the environment (never a literal in source) so boot fails if it is missing.
 
 ## Authentication (`createAuth`)
 
@@ -55,7 +62,7 @@ export const { auth, signIn, signOut, handlers } = createAuth({
     Credentials({
       async authorize(credentials) {
         const user = await db.query.users.findFirst({ where: { email: credentials.email } });
-        if (!user || !verifyPassword(credentials.password, user.passwordHash)) return null;
+        if (!user || !(await compare(credentials.password, user.passwordHash))) return null;
         return { id: user.id, name: user.name, email: user.email, role: user.role };
       },
     }),
@@ -63,9 +70,50 @@ export const { auth, signIn, signOut, handlers } = createAuth({
     GitHub(),   // reads AUTH_GITHUB_ID, AUTH_GITHUB_SECRET
   ],
   secret: process.env.AUTH_SECRET,   // required, 32+ random chars, from the env
+  pages: { error: '/login' },        // a failed sign-in 302s here with ?error=<code>
 });
 ```
 
+**Password hashing is the app's job** (WebJs ships no `verifyPassword`). Use `scrypt` from `node:crypto` (built into Node AND Bun, no dependency) in a server-only utility, and call it from `authorize`:
+
+```ts
+// modules/auth/password.server.ts (a server-only utility, never reaches the browser)
+import { scrypt, randomBytes, timingSafeEqual } from 'node:crypto';
+import { promisify } from 'node:util';
+const scryptAsync = promisify(scrypt);
+export async function hash(pw: string) {
+  const salt = randomBytes(16).toString('hex');
+  return salt + ':' + ((await scryptAsync(pw, salt, 64)) as Buffer).toString('hex');
+}
+export async function compare(pw: string, stored: string) {
+  const [salt, key] = stored.split(':');
+  return timingSafeEqual((await scryptAsync(pw, salt, 64)) as Buffer, Buffer.from(key, 'hex'));
+}
+```
+
+**Mount `handlers` at an `app/api/auth/[...path]/route.ts` catch-all** (at the app root, NOT under a feature folder): `createAuth` hardcodes `/api/auth/signin/*` and `/api/auth/callback/*` for its form posts and OAuth callback URIs.
+
+```ts
+// app/api/auth/[...path]/route.ts
+import { handlers } from '#modules/auth/auth.server.ts';
+export const GET = handlers.GET;
+export const POST = handlers.POST;
+```
+
+**The no-JS sign-in / sign-out flow is plain forms** (progressive-enhancement-safe). Sign in by POSTing to `/api/auth/signin/credentials` with a hidden `redirectTo`, and read `?error` (mapped from `pages.error`) for feedback; sign out by POSTing to `/api/auth/signout`:
+
+```html
+<form method="POST" action="/api/auth/signin/credentials">
+  <input type="hidden" name="redirectTo" value="/dashboard">
+  <input name="email" type="email" required><input name="password" type="password" required>
+  <button>Sign in</button>
+</form>
+<!-- log out -->
+<form method="POST" action="/api/auth/signout"><button>Log out</button></form>
+```
+
+For a programmatic sign-in (the auto-login-after-signup pattern), `signIn('credentials', creds, { redirectTo })` returns a `302` `Response` that a page `action` can return directly.
+
 Sessions are JWT by default (stateless, scales horizontally). OAuth
 providers handle the full redirect flow. Read the session anywhere on the
 server with `auth()`.
@@ -119,6 +167,20 @@ Reading the session through `auth()` also auto-excludes the page from the
 server HTML response cache, so a per-user page is never cached and served
 to another visitor (see `built-ins.md`).
 
+To gate a WHOLE subtree in one place, use a per-segment `middleware.ts` that reads `auth(req)` (the explicit-request form) and returns a `302` BEFORE the page renders. It runs for every request under its segment and needs only a cookie read (no DB query), so the gate is real the moment the app boots:
+
+```ts
+// app/dashboard/middleware.ts  (protects /dashboard/*)
+import { auth } from '#modules/auth/auth.server.ts';
+export default async function requireAuth(req: Request, next: () => Promise<Response>) {
+  const session = await auth(req);
+  if (!session?.user) return new Response(null, { status: 302, headers: { location: '/login' } });
+  return next();
+}
+```
+
+`auth(req)` takes the in-flight request explicitly (for a middleware / route); the ambient `auth()` (no argument) reads from context inside a page or action.
+
 ## `forbidden()` (403) vs `unauthorized()` (401)
 
 Two control-flow throws from `@webjsdev/core`, mirroring the `notFound()`

From efc7d49addab6625560eecaf5af6d57c0daa8ca5 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 12:52:52 +0530
Subject: [PATCH 16/73] docs(skill): teach env.ts boot validation and signedUrl
 base

The env demo directs readers to an app-root env.ts (schema or validator, fails
fast) and the file-storage demo uses signedUrl's base option to target a custom
serve route; the skill covered neither. Add both.
---
 .agents/skills/webjs/references/built-ins.md | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/.agents/skills/webjs/references/built-ins.md b/.agents/skills/webjs/references/built-ins.md
index 58f554afb..fef6dbb5e 100644
--- a/.agents/skills/webjs/references/built-ins.md
+++ b/.agents/skills/webjs/references/built-ins.md
@@ -4,7 +4,7 @@ Env vars, caching, rate limiting, broadcast, file storage, and the `package.json
 
 ## What This Covers
 
-- **Environment variables** and the `WEBJS_PUBLIC_` browser-exposed prefix.
+- **Environment variables**, the `WEBJS_PUBLIC_` browser-exposed prefix, and `env.ts` boot validation.
 - **Caching primitives.** `cache()` with tag invalidation, HTTP `Cache-Control`, the server HTML response cache (`export const revalidate`), content-hash asset URLs, conditional GET (ETag).
 - **Rate limiting** (`rateLimit()` middleware) and **broadcast** (`broadcast()` over WebSockets).
 - **File storage.** `FileStore` / `diskStore`, safe keys, signed URLs.
@@ -25,6 +25,18 @@ Read this when wiring caching or rate limiting, storing uploads, hardening heade
 
 Defaults are single-instance memory stores. To scale horizontally, switch the store once at startup: `setStore(redisStore({ url: process.env.REDIS_URL }))`.
 
+**Validate required vars at boot with an app-root `env.ts`** (optional). It default-exports either a SCHEMA object (each var mapped to a type `string` / `number` / `boolean` / `url` / `enum`, or an options object with `optional` / `default` / `minLength` / `pattern` / `values`) OR a validator function `(env) => void` that throws. It runs at boot after `.env` loads, coerces values and writes defaults back to `process.env`, and fails fast naming EVERY bad var:
+
+```ts
+// env.ts
+export default {
+  DATABASE_URL: 'url',
+  SESSION_SECRET: { type: 'string', minLength: 16 },
+  PORT: { type: 'number', default: 8080 },
+  LOG_LEVEL: { type: 'enum', values: ['debug', 'info', 'warn'], default: 'info' },
+};
+```
+
 ## Caching
 
 ### `cache()` for query and computation results
@@ -112,7 +124,7 @@ setFileStore(diskStore({ dir: '/var/data/uploads', baseUrl: '/files' }));
 
 **Never trust a user filename as a key.** `generateKey(file.name)` returns an opaque `<uuid>.<ext>` with a sanitized extension; a traversal attempt yields a bare safe key. Keys are containment-checked before any filesystem op.
 
-**Signed URLs** gate serving without a session lookup. `signedUrl(key, { secret, expiresIn })` mints an expiring HMAC signature; `verifySignedUrl(searchParams, secret)` returns `{ valid }`. An `expiresIn` of `0` or negative fails closed.
+**Signed URLs** gate serving without a session lookup. `signedUrl(key, { secret, expiresIn })` mints an expiring HMAC signature; `verifySignedUrl(searchParams, secret)` returns `{ valid }`. An `expiresIn` of `0` or negative fails closed. Pass `base` to point the signed link at your own serve route instead of the default upload URL: `signedUrl(key, { secret, base: '/files/' + key, expiresIn: 3600 })`.
 
 **Serving-XSS warning.** The recorded content-type is attacker-controlled (the browser sent it at upload). A serving route MUST send `X-Content-Type-Options: nosniff` and SHOULD send `Content-Disposition: attachment` for user uploads. Only serve inline after validating bytes against a strict inert allowlist, never `text/html` / `image/svg+xml`. Add the uploads directory to `.gitignore`.
 

From 907164e756787240cae8431531b8cb20a4050268 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 12:53:55 +0530
Subject: [PATCH 17/73] docs(skill): teach degrade-first optimistic forms and
 control a11y

The todo example authors each optimistic mutation as a real <form method=post>
that degrades to the page action (with a hidden intent for multi-mutation pages),
and hand-authors accessible controls (label-for, aria-pressed, aria-label); the
skill taught neither. Add the degrade-first form pattern to optimistic-ui.md and
an accessible-controls note to styling.md.
---
 .../skills/webjs/references/optimistic-ui.md   | 18 ++++++++++++++++++
 .agents/skills/webjs/references/styling.md     | 11 +++++++++++
 2 files changed, 29 insertions(+)

diff --git a/.agents/skills/webjs/references/optimistic-ui.md b/.agents/skills/webjs/references/optimistic-ui.md
index ccbdf6117..9177fba70 100644
--- a/.agents/skills/webjs/references/optimistic-ui.md
+++ b/.agents/skills/webjs/references/optimistic-ui.md
@@ -67,6 +67,24 @@ TodoList.register('todo-list');
 - Multiple `.add()` calls stack independently. Each carries its own release by ID, so overlapping in-flight mutations do not clobber one another.
 - When `update` is omitted, the payload REPLACES the state directly (`Action = State`), matching the simple `useOptimistic(setState)` pattern.
 
+### Author the optimistic mutation as a degrade-first form
+
+Wrap the mutation in a REAL `<form method="post" action="">` posting to the page's own URL, then intercept it for the optimistic path. One form then serves both: with JS off the browser submits to the page `action` (the no-JS write path, see `routing-and-pages.md`), and with JS on `@submit` calls `e.preventDefault()` and runs the optimistic path. That is the progressive-enhancement contract, not a fetch-only handler.
+
+```ts
+render() {
+  return html`
+    <form method="post" action="" @submit=${this.handleSubmit}>
+      <input type="hidden" name="intent" value="create">   <!-- one page action dispatches on intent -->
+      <input name="title" required>
+      <button>Add</button>
+    </form>
+    <ul>${this.optimisticTodos.value.map(t => html`<li class=${t.pending ? 'opacity-50' : ''}>${t.title}</li>`)}</ul>`;
+}
+```
+
+When a page owns SEVERAL mutations (create, toggle, delete), give each form a hidden `intent` field and let the single page `action` dispatch on it. Each interactive control (a toggle button, a delete button) is also its own tiny form so it still works with JS off.
+
 ## Seed the list from the server for SSR plus optimistic
 
 For a page that server-renders a list AND lets the user add to it optimistically, let ONE component own both the list and the form, and seed it from the page through a `.prop` hole (a DOM property that round-trips through SSR on custom elements). The list is then fully server-rendered on first paint (readable with JS off) and re-renders optimistically on each add. A separate static list in the page would not update on an optimistic add.
diff --git a/.agents/skills/webjs/references/styling.md b/.agents/skills/webjs/references/styling.md
index 69a019a5a..ef31039ca 100644
--- a/.agents/skills/webjs/references/styling.md
+++ b/.agents/skills/webjs/references/styling.md
@@ -8,6 +8,7 @@
 - Design tokens: `:root` / `@theme` in the root layout
 - Light-DOM host `display: block` behaviour (and shadow hosts via `:host`)
 - When to use `static styles` (shadow DOM)
+- Accessible native controls (label association, `aria-pressed`, `aria-label`)
 - `position: fixed`, not `sticky`, for a pinned header (the iOS WebKit flicker)
 - Even-grid / no-reflow layout tips
 
@@ -92,6 +93,16 @@ Why a class helper (not a `<ui-button>` wrapper): it adds NO indirection, so the
 
 **Own and theme your copy.** `webjs ui add <name>` copies the primitive INTO your `components/ui/`, so you own it. Theme it to YOUR app: change the class values so the helper produces YOUR look, rather than bending your app to the kit's defaults. Keep only the parts you use (the gallery's `cardClass` is surface-only, since its panels vary their own padding and layout). Reserve `lib/utils/ui.ts` `html`-fragment helpers for repeated markup chunks; reserve `components/ui/*` class helpers for themed primitives with variants.
 
+## Accessible native controls
+
+A cleared, growing app hand-authors its own controls, so accessibility is your job (the `@webjsdev/ui` primitives carry their own, but a raw `<button>` / `<input>` does not). Three habits keep hand-authored interactive markup accessible on BOTH the JS and no-JS paths:
+
+- **Associate a label with its control.** `<label for="email">` paired with `<input id="email">` (or wrap the control in the `<label>`), so a click on the label focuses the field and a screen reader announces it.
+- **State a toggle's pressed state.** A button that toggles carries `aria-pressed=${on}` so assistive tech announces on/off, not just "button".
+- **Name an icon-only button.** A button whose only content is an icon has no accessible name, so give it `aria-label="Delete task"`.
+
+Native `<button>` / `<a>` / `<input>` already have correct focus + keyboard behaviour, which is the main reason to prefer them (and the `buttonClass()` / `inputClass()` class helpers) over a custom `<div role>` element.
+
 ## Design tokens
 
 The default stack is a static compiled Tailwind stylesheet (`css:build` compiles `public/input.css` to the linked `public/tailwind.css`, so it works with JS off) plus `@theme` design tokens (palette, fonts, fluid type, motion durations) declared once in the root layout. Consume them as utility classes (`text-foreground`, `bg-card`, `font-serif`, `duration-fast`). If you wire your own theme switch, drive BOTH signals on `<html>` (the `data-theme` attribute for the app palette blocks AND the `.dark` class for the `@webjsdev/ui` kit), or half the UI renders stale tokens. Verify dark mode in a real browser, light mode passing proves nothing about dark.

From f23a31066de0923dfc89eb76ae0689a0ac38d0af Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 12:54:45 +0530
Subject: [PATCH 18/73] docs(skill): route the newly-documented exports from
 SKILL.md

Add effect/batch to the signals line, the missing directives (asyncAppend/
asyncReplace/templateContent) + Task/TaskStatus + context to the directives line,
and the route-handler toolkit (json/readBody/clientIp) + auth/session/file-storage
helpers to the server-side export map, each pointing at the reference that now
teaches it. Closes the skill-vs-gallery coverage gaps.
---
 .agents/skills/webjs/SKILL.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/.agents/skills/webjs/SKILL.md b/.agents/skills/webjs/SKILL.md
index e0a4f42b0..7785b7917 100644
--- a/.agents/skills/webjs/SKILL.md
+++ b/.agents/skills/webjs/SKILL.md
@@ -112,17 +112,19 @@ Find the right export fast. Load the linked reference for full examples.
 ### `@webjsdev/core` (browser + isomorphic)
 
 - `html` / `css` tagged templates. `WebComponent({ ... })` base-class factory; `prop(type?, opts?)` declares one reactive property. `register(tag, C)` / `Class.register('tag')`.
-- `signal` / `computed` reactive state; `render(v, el)` client render.
+- `signal` / `computed` reactive state, `effect(fn)` client-only reaction (returns a disposer), `batch(fn)` coalesced writes; `render(v, el)` client render.
 - `notFound()` / `redirect(url[, status])` control-flow throws (page/layout/action only, NOT `route.ts`). `forbidden()` / `unauthorized()` render the nearest boundary.
 - `Suspense({fallback, children})` page-level streaming; `<webjs-suspense>` component-level streaming.
 - `optimistic()` optimistic UI; `navigate(url)` / `revalidate(url?)` client-router control; `connectWS` / `richFetch`.
 - Types: `Metadata`, `PageProps<R>`, `LayoutProps<R>`, `RouteHandlerContext<R>`, `WebjsConfig`.
 - `@webjsdev/core/server`: `renderToString` / `renderToStream` (Node side).
-- `@webjsdev/core/directives`: `repeat`, `unsafeHTML` (trusted only), `live`, `keyed`, `guard`, `cache`, `until`, `watch(signal)`, `ref` / `createRef`. `Task` lives at `@webjsdev/core/task`, context at `/context`.
+- `@webjsdev/core/directives`: `repeat`, `unsafeHTML` (trusted only), `live`, `keyed`, `guard`, `cache`, `until`, `watch(signal)`, `ref` / `createRef`, `asyncAppend` / `asyncReplace`, `templateContent`. `Task` / `TaskStatus` live at `@webjsdev/core/task`, context (`createContext` / `ContextProvider` / `ContextConsumer`) at `/context`. See `references/components.md` for the directive table + Task + context.
 
 ### `@webjsdev/server` (server side)
 
 - `createRequestHandler`, `cors()`, `route(action, opts?)` REST adapter, `sitemap()` / `sitemapIndex()`, `actionContext()`, `actionSignal()`, `requestId()`, `cache()` / `revalidateTag`.
+- Route-handler toolkit: `json(v)` rich responder, `readBody(req)`, `clientIp(req)`, no-arg `headers()` / `cookies()` / `cspNonce()` (client counterpart `richFetch` is in `@webjsdev/core`). See `references/routing-and-pages.md`.
+- Auth + sessions: `createAuth` (+ `Credentials` / `Google` / `GitHub`), `auth()` / `auth(req)`, `session()` + `cookieSession` / `storeSession`, `getSession(req)` (`.get` / `.set` / `.flash` / `.destroy`). File storage: `getFileStore` / `diskStore` / `signedUrl`. See `references/auth-and-sessions.md` + `references/built-ins.md`.
 - Data layer is Drizzle in `db/*.server.ts`. Auth, sessions, caching, rate limit, file storage are built in and pluggable (`references/built-ins.md`).
 
 ### File conventions

From 0189da98e3115a55a6edfbc479d4f507ec94ea94 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 12:55:56 +0530
Subject: [PATCH 19/73] test: the agent skill satisfies the scaffold gate

Cover the new behavior: a feature-src commit is satisfied by a .agents/skills/webjs/
change (the durable teacher), not only a gallery/generator change. The existing
'blocks when no surface staged' case is the counterfactual.
---
 test/hooks/require-scaffold-with-src.test.mjs | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/test/hooks/require-scaffold-with-src.test.mjs b/test/hooks/require-scaffold-with-src.test.mjs
index 34cf8e342..378cabe4b 100644
--- a/test/hooks/require-scaffold-with-src.test.mjs
+++ b/test/hooks/require-scaffold-with-src.test.mjs
@@ -31,7 +31,7 @@ function makeRepo() {
   for (const d of [
     'packages/core/src', 'packages/server/src', 'packages/cli/src',
     'packages/cli/lib', 'packages/cli/templates/gallery/app/features/x',
-    'packages/editors/vscode/src',
+    'packages/editors/vscode/src', '.agents/skills/webjs/references',
   ]) mkdirSync(join(dir, d), { recursive: true });
   writeFileSync(join(dir, 'packages/core/src/x.js'), 'v1\n');
   writeFileSync(join(dir, 'packages/cli/lib/create.js'), 'gen1\n');
@@ -70,6 +70,18 @@ test('allows a feature-src commit that also stages a gallery demo', () => {
   } finally { rmSync(dir, { recursive: true, force: true }); }
 });
 
+test('allows a feature-src commit that also stages the agent skill (the durable teacher)', () => {
+  // The skill at .agents/skills/webjs/ is the only teaching surface that survives
+  // gallery:clear, so a skill update satisfies the gate the same as a gallery demo.
+  const { dir, git } = makeRepo();
+  try {
+    writeFileSync(join(dir, 'packages/core/src/x.js'), 'v2\n');
+    writeFileSync(join(dir, '.agents/skills/webjs/references/components.md'), '# taught here\n');
+    git('add', '-A');
+    assert.equal(runHook(dir), 0);
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+});
+
 test('allows a feature-src commit that also stages a generator (cli/lib)', () => {
   const { dir, git } = makeRepo();
   try {

From 67fe0d7c07cd477c9b53e71be80db8c6868afc26 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 13:20:42 +0530
Subject: [PATCH 20/73] refactor(gallery): build the last hand-rolled buttons
 on the design system

Three demos still hand-reimplemented the button base + variants inline instead of
using buttonClass, the exact drift the design system exists to prevent (they even
missed the focus-visible ring every other button has). The like toggle IS the
secondary/default variants, and the two 'Go to page two' links ARE the default
variant on an <a>. Compose buttonClass() and override only the genuinely bespoke
bits with cn() (the like button's pill radius + heart SVG). The todo
toggle-checkbox, delete icon-button, and the native file: input button stay
bespoke (the variants do not cover them). Verified: all render, webjs check passes.
---
 .../gallery/app/features/client-router/page.ts     |  3 ++-
 .../gallery/app/features/view-transitions/page.ts  |  3 ++-
 .../optimistic-ui/components/like-button.ts        | 14 +++++++++++++-
 3 files changed, 17 insertions(+), 3 deletions(-)

diff --git a/packages/cli/templates/gallery/app/features/client-router/page.ts b/packages/cli/templates/gallery/app/features/client-router/page.ts
index eb350aa5d..2ce6b3124 100644
--- a/packages/cli/templates/gallery/app/features/client-router/page.ts
+++ b/packages/cli/templates/gallery/app/features/client-router/page.ts
@@ -7,6 +7,7 @@
 // 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 '#modules/client-router/components/router-controls.ts';
 
 export const metadata: Metadata = { title: 'Client router (soft nav) | features' };
@@ -21,7 +22,7 @@ export default function ClientRouterExample() {
       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>
diff --git a/packages/cli/templates/gallery/app/features/view-transitions/page.ts b/packages/cli/templates/gallery/app/features/view-transitions/page.ts
index c96cacbe3..db287dd7e 100644
--- a/packages/cli/templates/gallery/app/features/view-transitions/page.ts
+++ b/packages/cli/templates/gallery/app/features/view-transitions/page.ts
@@ -8,6 +8,7 @@
 // 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';
 
 export const metadata: Metadata = {
   title: 'View transitions (soft-nav cross-fade) | features',
@@ -29,7 +30,7 @@ export default function ViewTransitionsExample() {
         class="mt-2 block w-full max-w-sm rounded-xl border border-border bg-card px-4 py-2 text-foreground" />
     </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">
diff --git a/packages/cli/templates/gallery/modules/optimistic-ui/components/like-button.ts b/packages/cli/templates/gallery/modules/optimistic-ui/components/like-button.ts
index 23222f321..5721e7ea5 100644
--- a/packages/cli/templates/gallery/modules/optimistic-ui/components/like-button.ts
+++ b/packages/cli/templates/gallery/modules/optimistic-ui/components/like-button.ts
@@ -9,6 +9,8 @@
 // see the declarative optimistic(host, { source, update }) + .add() form in the
 // /examples/todo app.
 import { WebComponent, signal, optimistic, html } from '@webjsdev/core';
+import { cn } from '#lib/utils/cn.ts';
+import { buttonClass } from '#components/ui/button.ts';
 import { likePost } from '../actions/like-post.server.ts';
 
 export class LikeButton extends WebComponent {
@@ -23,9 +25,19 @@ export class LikeButton extends WebComponent {
 
   render() {
     const liked = this.liked.get();
+    // Build ON the design system, do not re-implement it. The like toggle IS the
+    // button variants: unliked reads as `secondary` (card surface), liked as
+    // `default` (primary fill). So compose buttonClass() for the base + colors +
+    // focus ring + cursor, then override only the genuinely bespoke bits with cn()
+    // (which tailwind-merges): a pill radius over the helper's rounded-xl, and a
+    // primary outline when liked. Only the heart SVG stays fully custom.
     return html`
       <button @click=${() => this.toggle()} aria-pressed=${liked ? 'true' : 'false'}
-        class="inline-flex items-center gap-2 px-4 py-2 rounded-full font-semibold text-sm border cursor-pointer transition-all active:scale-[0.97] ${liked ? 'bg-primary text-primary-foreground border-primary' : 'bg-card text-foreground border-border hover:border-border-strong'}">
+        class=${cn(
+          buttonClass({ variant: liked ? 'default' : 'secondary' }),
+          'rounded-full',
+          liked && 'border border-primary',
+        )}>
         <svg viewBox="0 0 24 24" class="w-4 h-4 ${liked ? 'fill-current stroke-none' : 'fill-none stroke-current'}" style="stroke-width:2;stroke-linecap:round;stroke-linejoin:round"><path d="M20.8 4.6a5.5 5.5 0 0 0-7.8 0L12 5.7l-1-1.1a5.5 5.5 0 0 0-7.8 7.8l1.1 1L12 21l7.7-7.6 1.1-1a5.5 5.5 0 0 0 0-7.8Z"/></svg>
         ${liked ? 'Liked' : 'Like'}
       </button>

From 4a17111ef20d0d96b1f527daa6ea5add3e6f30e8 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 13:25:23 +0530
Subject: [PATCH 21/73] docs(gallery): explain the like-button border override

Extend the comment to say why the liked state re-adds a border: secondary carries
a 1px border and default carries none, so under box-sizing border-box the toggle
would jitter the button width by ~1px without it. The border matches the primary
fill (invisible), doing only the no-jitter job.
---
 .../modules/optimistic-ui/components/like-button.ts       | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/packages/cli/templates/gallery/modules/optimistic-ui/components/like-button.ts b/packages/cli/templates/gallery/modules/optimistic-ui/components/like-button.ts
index 5721e7ea5..7de04774d 100644
--- a/packages/cli/templates/gallery/modules/optimistic-ui/components/like-button.ts
+++ b/packages/cli/templates/gallery/modules/optimistic-ui/components/like-button.ts
@@ -30,7 +30,13 @@ export class LikeButton extends WebComponent {
     // `default` (primary fill). So compose buttonClass() for the base + colors +
     // focus ring + cursor, then override only the genuinely bespoke bits with cn()
     // (which tailwind-merges): a pill radius over the helper's rounded-xl, and a
-    // primary outline when liked. Only the heart SVG stays fully custom.
+    // border on the liked state. The border is GEOMETRY, not decoration: the
+    // `secondary` variant carries a 1px border and `default` carries none, so under
+    // box-sizing border-box an auto-width inline-flex button would change its outer
+    // size by ~1px each toggle (a small label jitter). Re-adding `border
+    // border-primary` keeps a 1px border in both states so the pill stays put. On
+    // the primary fill that border color matches the fill, so it reads as invisible,
+    // doing only the no-jitter job. Only the heart SVG stays fully custom.
     return html`
       <button @click=${() => this.toggle()} aria-pressed=${liked ? 'true' : 'false'}
         class=${cn(

From 736bc9ea93ad6c6057e1ce0448d85b4862dd87f9 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 14:17:51 +0530
Subject: [PATCH 22/73] feat(gallery): add badgeClass, a destructive button
 variant, ui.ts helpers

Balanced design-system extension (per decision). New primitives the audit found
missing: badgeClass (components/ui/badge.ts, themed to the scaffold's soft-primary
pill + muted outline tag), a 'destructive' button variant (subtle muted-to-red,
so the todo delete icon converts cleanly), and lib/utils/ui.ts markup-chunk
helpers (pageHeading/lede/backLink, the styling.md html-fragment pattern). Wire
copyGallery to ship the gallery lib/. Also fix the stale copyGallery comment that
claimed gallery:clear keeps components/ui (it removes it). Conversions follow.
---
 packages/cli/lib/create.js                    | 15 ++++---
 .../templates/gallery/components/ui/badge.ts  | 41 +++++++++++++++++++
 .../templates/gallery/components/ui/button.ts |  4 ++
 .../cli/templates/gallery/lib/utils/ui.ts     | 31 ++++++++++++++
 4 files changed, 86 insertions(+), 5 deletions(-)
 create mode 100644 packages/cli/templates/gallery/components/ui/badge.ts
 create mode 100644 packages/cli/templates/gallery/lib/utils/ui.ts

diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
index 6bb44dd71..2423f5443 100644
--- a/packages/cli/lib/create.js
+++ b/packages/cli/lib/create.js
@@ -124,11 +124,16 @@ async function copyGallery(appDir) {
   const galleryDir = join(TEMPLATES, 'gallery');
   // `test` carries the auth card's real request-pipeline test (test/auth); it
   // ships with the gallery and is pruned by gallery:clear alongside the card.
-  // `components` carries the design system (components/ui/ class helpers) the
-  // demos import; it is INFRASTRUCTURE that gallery:clear KEEPS (a real app goes
-  // on importing buttonClass/cardClass/inputClass), so it merges into the app's
-  // components/ alongside the separately-written theme toggle.
-  for (const sub of ['app', 'modules', 'test', 'components']) {
+  // `components` carries the gallery's EXAMPLE design system (components/ui/ class
+  // helpers) the demos import. It ships here so a fresh app's demos work, but it
+  // is an example to learn from, so gallery:clear REMOVES it (the agent then runs
+  // `webjs ui add` and themes its own components/ui/); only cn.ts is kept as the
+  // `webjs ui add` prerequisite. It merges into the app's components/ alongside
+  // the separately-written theme toggle (also removed by gallery:clear).
+  // `lib` merges the gallery's markup-chunk helpers (lib/utils/ui.ts) alongside
+  // the ui bootstrap's cn.ts/dom.ts (written earlier); gallery:clear removes just
+  // ui.ts. cp is recursive-merge, so the pre-written lib/utils/ files are kept.
+  for (const sub of ['app', 'modules', 'test', 'components', 'lib']) {
     await cp(join(galleryDir, sub), join(appDir, sub), { recursive: true });
   }
 }
diff --git a/packages/cli/templates/gallery/components/ui/badge.ts b/packages/cli/templates/gallery/components/ui/badge.ts
new file mode 100644
index 000000000..d07159c59
--- /dev/null
+++ b/packages/cli/templates/gallery/components/ui/badge.ts
@@ -0,0 +1,41 @@
+/**
+ * badgeClass: the gallery's badge/pill design token, built on @webjsdev/ui.
+ *
+ * A `@webjsdev/ui` tier-1 CLASS HELPER (like buttonClass): it returns a Tailwind
+ * class string you spread onto a NATIVE inline element, almost always a `<span>`
+ * (a static label) or an `<a>` (a linked tag). Native markup means no wrapper
+ * component and correct semantics for free:
+ *
+ *   <span class=${badgeClass()}>Signed in</span>
+ *   <span class=${badgeClass({ variant: 'outline' })}>Example app</span>
+ *
+ * OWN-AND-THEME: this is `@webjsdev/ui`'s badge THEMED to this scaffold's two
+ * real uses, NOT the fuller shadcn badge (solid primary, secondary, destructive,
+ * ghost, link). Keep only the variants you use, styled to your look. `default`
+ * is a soft primary pill (a status chip); `outline` is a quiet muted tag.
+ *
+ * A11y: a static badge is a plain non-focusable `<span>`. Make it an `<a>` only
+ * when it links somewhere.
+ *
+ * Design tokens used (app/layout.ts): --color-primary, --color-border,
+ * --color-muted-foreground.
+ */
+import { cn } from '#lib/utils/cn.ts';
+
+// Shared by every variant: an inline pill that hugs its content and never wraps.
+const BASE = 'inline-flex w-fit shrink-0 items-center whitespace-nowrap';
+
+const VARIANTS = {
+  // A soft, tinted primary chip. Used for a status ("Signed in").
+  default: 'rounded-full bg-primary/15 text-primary px-2.5 py-1 text-xs font-medium',
+  // A tiny, quiet outline tag. Used to label a kind of thing ("Example app").
+  outline:
+    'rounded border border-border text-muted-foreground px-1.5 py-0.5 text-[0.6rem] font-semibold uppercase tracking-wider',
+} as const;
+
+export type BadgeVariant = keyof typeof VARIANTS;
+
+/** Compose the Tailwind classes for a badge/pill. Append your own layout as needed. */
+export function badgeClass(opts: { variant?: BadgeVariant } = {}): string {
+  return cn(BASE, VARIANTS[opts.variant ?? 'default']);
+}
diff --git a/packages/cli/templates/gallery/components/ui/button.ts b/packages/cli/templates/gallery/components/ui/button.ts
index 28e323920..ca1b3156c 100644
--- a/packages/cli/templates/gallery/components/ui/button.ts
+++ b/packages/cli/templates/gallery/components/ui/button.ts
@@ -48,6 +48,10 @@ const VARIANTS = {
   ghost: 'bg-transparent text-foreground font-medium hover:bg-accent',
   // A button that reads as an inline text link (navigate, toggle, reveal).
   link: 'text-muted-foreground font-medium underline decoration-dotted underline-offset-4 hover:text-foreground',
+  // A subtle destructive action (a delete icon / a remove control): transparent
+  // and muted at rest, turning red on hover. NOT a loud solid-red button; theme
+  // it to a filled `bg-destructive` variant if you want a prominent confirm.
+  destructive: 'bg-transparent text-muted-foreground font-medium hover:text-destructive hover:bg-destructive/10',
 } as const;
 
 // SIZES carry SHAPE (padding + radius). `none` is for the link variant, which
diff --git a/packages/cli/templates/gallery/lib/utils/ui.ts b/packages/cli/templates/gallery/lib/utils/ui.ts
new file mode 100644
index 000000000..7bbffc87b
--- /dev/null
+++ b/packages/cli/templates/gallery/lib/utils/ui.ts
@@ -0,0 +1,31 @@
+/**
+ * ui.ts: repeated MARKUP-chunk helpers (the `lib/utils/ui.ts` pattern).
+ *
+ * A design system has two kinds of helper. A repeated PRIMITIVE with variants
+ * (button, input, card, badge) is a CLASS helper in `components/ui/` returning a
+ * class string. A repeated markup CHUNK (a heading, a lede, a back link) is an
+ * `html`-fragment helper here in `lib/utils/ui.ts`: it returns SSR-time markup,
+ * so the output is byte-identical to writing the tags inline, with no client
+ * runtime. Use these for chunks that repeat across pages; keep genuinely one-off
+ * or trivial prose (a lone `<code>`, a single text link) inline for readability.
+ *
+ * OWN-AND-THEME: these fragments are THIS gallery's shared bits. Change a class
+ * here and every page updates at once. Build your own for your app.
+ */
+import { html } from '@webjsdev/core';
+
+/** A page's `<h1>` heading (the standard demo/page title). */
+export function pageHeading(title: unknown) {
+  return html`<h1 class="text-h2 font-bold mb-4">${title}</h1>`;
+}
+
+/** The muted intro paragraph under a heading. Pass a string OR an `html` fragment
+ *  (a lede often wraps an inline `<code>`). */
+export function lede(content: unknown) {
+  return html`<p class="text-muted-foreground mb-4">${content}</p>`;
+}
+
+/** A slim "back" link (used above each gallery demo to return to the index). */
+export function backLink(href: string, label: unknown) {
+  return html`<a href=${href} class="inline-flex items-center gap-1 text-sm text-muted-foreground hover:text-foreground transition-colors no-underline mb-6">${label}</a>`;
+}

From 59eea1ff741851101c699c8f6494c2eb5fd62fc8 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 14:22:02 +0530
Subject: [PATCH 23/73] refactor(gallery): build the base theme-toggle + home
 on the design system

Convert the create.js-emitted base surfaces to the helpers: theme-toggle uses
buttonClass({ variant: 'secondary', size: 'none' }) + cn() overrides for the
circular icon shape (dropping its bespoke focus ring for the shared one); the
home feature/example cards use cardClass(); the 'Example app' pill uses
badgeClass({ variant: 'outline' }). Teach the icon-button pattern (size:'none' +
cn overrides, since cn does not merge p-0 vs px-4 py-2) in styling.md. Verified:
generates, home SSRs 200, webjs check passes.
---
 .agents/skills/webjs/references/styling.md |  2 +-
 packages/cli/lib/create.js                 | 12 ++++++++----
 2 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/.agents/skills/webjs/references/styling.md b/.agents/skills/webjs/references/styling.md
index ef31039ca..512423598 100644
--- a/.agents/skills/webjs/references/styling.md
+++ b/.agents/skills/webjs/references/styling.md
@@ -70,7 +70,7 @@ Avoid `@apply`: it hides which utilities a class uses and creates a second sourc
 
 ### A design system for repeated PRIMITIVES: class helpers built on `@webjsdev/ui`
 
-An `html`-fragment helper is right for a repeated CHUNK of markup (the rubric above). For a repeated UI PRIMITIVE (button, input, card, badge) that needs variants and sizes, use a class helper instead: a function that returns a Tailwind class STRING you spread onto a native element. That is exactly what `@webjsdev/ui` ships (`buttonClass({ variant, size })`, `cardClass()`, `inputClass()`), and it is what the scaffold gallery uses in `components/ui/`.
+An `html`-fragment helper is right for a repeated CHUNK of markup (the rubric above). For a repeated UI PRIMITIVE (button, input, card, badge) that needs variants and sizes, use a class helper instead: a function that returns a Tailwind class STRING you spread onto a native element. That is exactly what `@webjsdev/ui` ships (`buttonClass({ variant, size })`, `cardClass()`, `inputClass()`, `badgeClass({ variant })`), and it is what the scaffold gallery uses in `components/ui/`. To style a ONE-OFF that a variant does not cover (a circular icon button, a pill), compose the helper and override the bespoke bits with `cn()`: `cn(buttonClass({ variant: 'secondary', size: 'none' }), 'w-9 h-9 rounded-full')`. Use `size: 'none'` for an icon button (it drops the helper's padding/radius so your `w-/h-/rounded-` apply cleanly), since `cn`'s merge does NOT resolve a `p-0` against `px-4 py-2`.
 
 ```ts
 // components/ui/button.ts  (webjs ui add button, themed to your app)
diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
index 2423f5443..16a07be1e 100644
--- a/packages/cli/lib/create.js
+++ b/packages/cli/lib/create.js
@@ -1290,6 +1290,8 @@ export default function RootLayout({ children }: { children: unknown }) {
   // app/features/<x> route AND its modules/<x>), then reshape this page into the
   // app's real landing page.
   await writeFile(join(appDir, 'app', 'page.ts'), `import { html } from '@webjsdev/core';
+import { cardClass } from '#components/ui/card.ts';
+import { badgeClass } from '#components/ui/badge.ts';
 
 export const metadata = {
   title: '${displayName}',
@@ -1357,7 +1359,7 @@ export default function Home() {
         </div>
         <div class="grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
           \${FEATURES.map(f => html\`
-            <a href="\${f.href}" class="group flex flex-col gap-1.5 rounded-xl border border-border bg-card p-4 no-underline transition-colors hover:border-border-strong hover:bg-accent">
+            <a href="\${f.href}" class=\${cardClass('group flex flex-col gap-1.5 rounded-xl p-4 no-underline transition-colors hover:border-border-strong hover:bg-accent')}>
               <span class="flex items-center justify-between gap-2">
                 <span class="text-sm font-medium text-foreground">\${f.title}</span>
                 <span class="text-muted-foreground transition-transform group-hover:translate-x-0.5" aria-hidden="true">&rarr;</span>
@@ -1367,9 +1369,9 @@ export default function Home() {
           \`)}
         </div>
         \${EXAMPLES.map(e => html\`
-          <a href="\${e.href}" class="group flex flex-col gap-2 rounded-xl border border-border bg-card p-5 no-underline transition-colors hover:border-border-strong hover:bg-accent">
+          <a href="\${e.href}" class=\${cardClass('group flex flex-col gap-2 rounded-xl p-5 no-underline transition-colors hover:border-border-strong hover:bg-accent')}>
             <span class="flex items-center gap-2.5">
-              <span class="text-[0.6rem] font-semibold uppercase tracking-wider text-muted-foreground rounded border border-border px-1.5 py-0.5">Example app</span>
+              <span class=\${badgeClass({ variant: 'outline' })}>Example app</span>
               <span class="text-sm font-medium text-foreground">\${e.title}</span>
               <span class="ml-auto text-muted-foreground transition-transform group-hover:translate-x-0.5" aria-hidden="true">&rarr;</span>
             </span>
@@ -1406,6 +1408,8 @@ function iconGithub() {
   // --- Theme toggle component ---
 
   await writeFile(join(appDir, 'components', 'theme-toggle.ts'), `import { WebComponent, html, signal } from '@webjsdev/core';
+import { cn } from '#lib/utils/cn.ts';
+import { buttonClass } from '#components/ui/button.ts';
 
 type Theme = 'system' | 'light' | 'dark';
 
@@ -1453,7 +1457,7 @@ export class ThemeToggle extends WebComponent {
     const icon = t === 'light' ? ICONS.sun : t === 'dark' ? ICONS.moon : ICONS.system;
     return html\`
       <button
-        class="inline-flex items-center justify-center w-9 h-9 p-0 border border-border rounded-full bg-card text-muted-foreground cursor-pointer transition-all duration-150 hover:text-foreground hover:border-border-strong active:scale-[0.94] focus-visible:outline-none focus-visible:border-primary focus-visible:ring-[3px] focus-visible:ring-primary-tint"
+        class=\${cn(buttonClass({ variant: 'secondary', size: 'none' }), 'w-9 h-9 rounded-full text-muted-foreground duration-150 hover:text-foreground active:scale-[0.94]')}
         @click=\${() => this.cycle()}
         aria-label="Cycle theme (currently \${label})"
         title="Theme: \${label.toLowerCase()}"

From 36cb3d87a2703fea0a7c84946690f005d8b48b17 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 14:35:14 +0530
Subject: [PATCH 24/73] refactor(gallery): route every demo through the design
 system

Sweep the gallery to eliminate inline-Tailwind that a helper should own (the
like-button drift class, everywhere). Drift fixes: hand-rolled inputs ->
inputClass (broadcast, ws-echo, directives, view-transitions x2), panels ->
cardClass (theme-context, file-storage), the global-not-found button -> buttonClass
(clearing bg-neutral/text-white hardcoded colors), reactive-meter #8883 ->
var(--color-border), task-loader text-red-500 -> text-destructive. Primitives:
the 'Signed in' pill -> badgeClass, the todo delete icon -> the destructive
variant, the two Gallery back-links -> backLink(). Sweep: 29 pages + 4 boundary
files use pageHeading()/lede(). Verified: generate + webjs check + typecheck +
boot, all 27 routes serve (boundaries 403/401 by design).
---
 packages/cli/templates/gallery/app/examples/layout.ts  |  3 ++-
 .../cli/templates/gallery/app/examples/todo/page.ts    |  3 ++-
 .../gallery/app/features/async-render/page.ts          |  5 +++--
 .../gallery/app/features/auth/dashboard/page.ts        |  3 ++-
 .../cli/templates/gallery/app/features/auth/page.ts    |  5 +++--
 .../templates/gallery/app/features/boundaries/error.ts |  7 ++++---
 .../gallery/app/features/boundaries/gated/forbidden.ts |  7 ++++---
 .../gallery/app/features/boundaries/not-found.ts       |  7 ++++---
 .../templates/gallery/app/features/boundaries/page.ts  |  7 ++++---
 .../app/features/boundaries/private/unauthorized.ts    |  7 ++++---
 .../templates/gallery/app/features/broadcast/page.ts   |  7 ++++---
 .../cli/templates/gallery/app/features/caching/page.ts |  7 ++++---
 .../gallery/app/features/client-router/page.ts         |  7 ++++---
 .../gallery/app/features/client-router/second/page.ts  |  7 ++++---
 .../templates/gallery/app/features/components/page.ts  |  5 +++--
 .../templates/gallery/app/features/directives/page.ts  |  5 +++--
 .../cli/templates/gallery/app/features/env/page.ts     |  7 ++++---
 .../gallery/app/features/file-storage/page.ts          | 10 ++++++----
 .../cli/templates/gallery/app/features/forms/page.ts   |  3 ++-
 .../cli/templates/gallery/app/features/frames/page.ts  |  7 ++++---
 packages/cli/templates/gallery/app/features/layout.ts  |  3 ++-
 .../templates/gallery/app/features/metadata/page.ts    |  7 ++++---
 .../gallery/app/features/optimistic-ui/page.ts         |  5 +++--
 .../templates/gallery/app/features/rate-limit/page.ts  |  7 ++++---
 .../gallery/app/features/route-handler/page.ts         |  5 +++--
 .../gallery/app/features/routing/[id]/page.ts          |  3 ++-
 .../cli/templates/gallery/app/features/routing/page.ts |  5 +++--
 .../gallery/app/features/server-actions/page.ts        |  5 +++--
 .../gallery/app/features/service-worker/page.ts        |  7 ++++---
 .../templates/gallery/app/features/sessions/page.ts    |  5 +++--
 .../cli/templates/gallery/app/features/stream/page.ts  |  7 ++++---
 .../templates/gallery/app/features/streaming/page.ts   |  7 ++++---
 .../templates/gallery/app/features/suspense/page.ts    |  7 ++++---
 .../gallery/app/features/view-transitions/page.ts      |  6 ++++--
 .../app/features/view-transitions/second/page.ts       |  6 ++++--
 .../templates/gallery/app/features/websockets/page.ts  |  7 ++++---
 packages/cli/templates/gallery/app/global-not-found.ts |  7 ++++---
 .../modules/broadcast/components/broadcast-feed.ts     |  3 ++-
 .../modules/components/components/reactive-meter.ts    |  2 +-
 .../modules/components/components/task-loader.ts       |  2 +-
 .../modules/components/components/theme-context.ts     |  3 ++-
 .../modules/directives/components/directive-demo.ts    |  3 ++-
 .../gallery/modules/todo/components/todo-app.ts        |  3 ++-
 .../gallery/modules/websockets/components/ws-echo.ts   |  3 ++-
 44 files changed, 141 insertions(+), 96 deletions(-)

diff --git a/packages/cli/templates/gallery/app/examples/layout.ts b/packages/cli/templates/gallery/app/examples/layout.ts
index 4960cad4a..354370030 100644
--- a/packages/cli/templates/gallery/app/examples/layout.ts
+++ b/packages/cli/templates/gallery/app/examples/layout.ts
@@ -1,11 +1,12 @@
 import { html } from '@webjsdev/core';
+import { backLink } from '#lib/utils/ui.ts';
 
 // Shared layout for every gallery example app under /examples/*. It adds the same
 // slim "back to the gallery" link the feature demos get, so an example is never a
 // dead end. A non-root layout, so it never writes the document shell.
 export default function ExamplesLayout({ children }: { children: unknown }) {
   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>
+    ${backLink('/', html`&larr; Gallery`)}
     ${children}
   `;
 }
diff --git a/packages/cli/templates/gallery/app/examples/todo/page.ts b/packages/cli/templates/gallery/app/examples/todo/page.ts
index 711a91b99..8eb3726b0 100644
--- a/packages/cli/templates/gallery/app/examples/todo/page.ts
+++ b/packages/cli/templates/gallery/app/examples/todo/page.ts
@@ -4,6 +4,7 @@
 // lives in modules/todo/. This is the idiomatic app-thin + modules-logic split.
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core'; // Metadata is a @webjsdev/core type
+import { pageHeading } from '#lib/utils/ui.ts';
 import { listTodos } from '#modules/todo/queries/list-todos.server.ts';
 import { createTodo } from '#modules/todo/actions/create-todo.server.ts';
 import { toggleTodo } from '#modules/todo/actions/toggle-todo.server.ts';
@@ -16,7 +17,7 @@ export default async function TodoExample() {
   // SSR-fetched and seeded, so <todo-app> paints the real list on first byte.
   const todos = await listTodos();
   return html`
-    <h1 class="text-h2 font-bold mb-4">Optimistic todo</h1>
+    ${pageHeading('Optimistic todo')}
     <todo-app .todos=${todos}></todo-app>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/async-render/page.ts b/packages/cli/templates/gallery/app/features/async-render/page.ts
index 632d25bb1..586fa21e8 100644
--- a/packages/cli/templates/gallery/app/features/async-render/page.ts
+++ b/packages/cli/templates/gallery/app/features/async-render/page.ts
@@ -1,5 +1,6 @@
 import { html, Suspense } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
+import { pageHeading, lede } from '#lib/utils/ui.ts';
 import '#modules/async-render/components/server-clock.ts';
 
 export const metadata: Metadata = { title: 'Async render (server data in first paint) | features' };
@@ -14,8 +15,8 @@ async function slowRegion() {
 
 export default function AsyncRenderExample() {
   return html`
-    <h1 class="text-h2 font-bold mb-4">Async render</h1>
-    <p class="text-muted-foreground mb-4">A component's <code>async render()</code> awaits server data. SSR blocks, so the resolved value is in the first paint (no fallback, readable with JS off).</p>
+    ${pageHeading('Async render')}
+    ${lede(html`A component's <code>async render()</code> awaits server data. SSR blocks, so the resolved value is in the first paint (no fallback, readable with JS off).`)}
     <server-clock></server-clock>
     <p class="text-muted-foreground mt-6 mb-2">For a SLOW region where blocking the first byte hurts, wrap it in <code class="font-mono">Suspense</code> to stream it instead:</p>
     ${Suspense({ fallback: html`<p class="text-muted-foreground">loading slow region…</p>`, children: slowRegion() })}
diff --git a/packages/cli/templates/gallery/app/features/auth/dashboard/page.ts b/packages/cli/templates/gallery/app/features/auth/dashboard/page.ts
index 2c7f5feea..c5206d1a4 100644
--- a/packages/cli/templates/gallery/app/features/auth/dashboard/page.ts
+++ b/packages/cli/templates/gallery/app/features/auth/dashboard/page.ts
@@ -1,5 +1,6 @@
 import { html } from '@webjsdev/core';
 import { cardClass } from '#components/ui/card.ts';
+import { badgeClass } from '#components/ui/badge.ts';
 import { currentUser } from '#modules/auth/queries/current-user.server.ts';
 
 export const metadata = { title: 'Dashboard' };
@@ -9,7 +10,7 @@ export default async function Dashboard() {
   return html`
     <div class="flex items-center justify-between mb-6">
       <h1 class="text-2xl font-semibold">Dashboard</h1>
-      <span class="text-xs font-medium rounded-full bg-primary/15 text-primary px-2.5 py-1">Signed in</span>
+      <span class=${badgeClass()}>Signed in</span>
     </div>
     <div class="${cardClass()} p-6">
       <h2 class="text-lg font-semibold text-foreground m-0 mb-1">Welcome, ${user?.name || user?.email}!</h2>
diff --git a/packages/cli/templates/gallery/app/features/auth/page.ts b/packages/cli/templates/gallery/app/features/auth/page.ts
index c3b883055..9b0d61bb2 100644
--- a/packages/cli/templates/gallery/app/features/auth/page.ts
+++ b/packages/cli/templates/gallery/app/features/auth/page.ts
@@ -10,6 +10,7 @@
 // line is the real query during SSR and a safe RPC stub on the client.
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
+import { pageHeading, lede } from '#lib/utils/ui.ts';
 import { currentUser } from '#modules/auth/queries/current-user.server.ts';
 
 export const metadata: Metadata = { title: 'Auth (login + protected route) | features' };
@@ -17,8 +18,8 @@ export const metadata: Metadata = { title: 'Auth (login + protected route) | fea
 export default async function AuthExample() {
   const user = await currentUser();
   return html`
-    <h1 class="text-h2 font-bold mb-4">Auth</h1>
-    <p class="text-muted-foreground mb-4">Password login on <code>createAuth</code>, a signed session cookie, and a protected <code>/features/auth/dashboard</code> that redirects anonymous visitors to login.</p>
+    ${pageHeading('Auth')}
+    ${lede(html`Password login on <code>createAuth</code>, a signed session cookie, and a protected <code>/features/auth/dashboard</code> that redirects anonymous visitors to login.`)}
 
     ${user
       ? html`
diff --git a/packages/cli/templates/gallery/app/features/boundaries/error.ts b/packages/cli/templates/gallery/app/features/boundaries/error.ts
index 4804de680..e5d24136a 100644
--- a/packages/cli/templates/gallery/app/features/boundaries/error.ts
+++ b/packages/cli/templates/gallery/app/features/boundaries/error.ts
@@ -3,14 +3,15 @@
 // rendered scoped to this boundary, so outer layouts stay alive. The default
 // export receives { error, ...ctx }; in production only error.message is sent.
 import { html } from '@webjsdev/core';
+import { pageHeading, lede } from '#lib/utils/ui.ts';
 
 export default function BoundariesError({ error }: { error: Error }) {
   return html`
-    <h1 class="text-h2 font-bold mb-4">Something went wrong</h1>
-    <p class="text-muted-foreground mb-4">
+    ${pageHeading('Something went wrong')}
+    ${lede(html`
       This segment's <code class="font-mono">error.ts</code> boundary caught a
       render error: <code class="font-mono">${error?.message ?? 'unknown'}</code>.
-    </p>
+    `)}
     <p><a class="text-primary" href="/features/boundaries">Back to boundaries</a></p>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/boundaries/gated/forbidden.ts b/packages/cli/templates/gallery/app/features/boundaries/gated/forbidden.ts
index d8164e920..c808723a6 100644
--- a/packages/cli/templates/gallery/app/features/boundaries/gated/forbidden.ts
+++ b/packages/cli/templates/gallery/app/features/boundaries/gated/forbidden.ts
@@ -4,15 +4,16 @@
 // forbidden.ts higher up the tree. Keep the message actionable for an
 // authenticated user who lacks permission.
 import { html } from '@webjsdev/core';
+import { pageHeading, lede } from '#lib/utils/ui.ts';
 
 export default function Forbidden() {
   return html`
-    <h1 class="text-h2 font-bold mb-4">403 Forbidden</h1>
-    <p class="text-muted-foreground mb-4">
+    ${pageHeading('403 Forbidden')}
+    ${lede(html`
       You are signed in but do not have permission to view this page. This is the
       nearest <code class="font-mono">forbidden.ts</code> boundary, rendered
       because the page threw <code class="font-mono">forbidden()</code>.
-    </p>
+    `)}
     <p><a class="text-primary" href="/features/boundaries">Back to boundaries</a></p>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/boundaries/not-found.ts b/packages/cli/templates/gallery/app/features/boundaries/not-found.ts
index 2f6b5b588..e35382984 100644
--- a/packages/cli/templates/gallery/app/features/boundaries/not-found.ts
+++ b/packages/cli/templates/gallery/app/features/boundaries/not-found.ts
@@ -3,15 +3,16 @@
 // /features/boundaries/ (try /features/boundaries/does-not-exist). Nearest wins,
 // so this beats the root not-found for anything in this segment.
 import { html } from '@webjsdev/core';
+import { pageHeading, lede } from '#lib/utils/ui.ts';
 
 export default function BoundariesNotFound() {
   return html`
-    <h1 class="text-h2 font-bold mb-4">404: Not here</h1>
-    <p class="text-muted-foreground mb-4">
+    ${pageHeading('404: Not here')}
+    ${lede(html`
       This segment's <code class="font-mono">not-found.ts</code> boundary rendered,
       because a page threw <code class="font-mono">notFound()</code> or the URL
       matched nothing under this segment.
-    </p>
+    `)}
     <p><a class="text-primary" href="/features/boundaries">Back to boundaries</a></p>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/boundaries/page.ts b/packages/cli/templates/gallery/app/features/boundaries/page.ts
index 40061ac49..b802eea71 100644
--- a/packages/cli/templates/gallery/app/features/boundaries/page.ts
+++ b/packages/cli/templates/gallery/app/features/boundaries/page.ts
@@ -16,18 +16,19 @@
 //   /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>
diff --git a/packages/cli/templates/gallery/app/features/boundaries/private/unauthorized.ts b/packages/cli/templates/gallery/app/features/boundaries/private/unauthorized.ts
index bd3f4d4b7..e277bcb24 100644
--- a/packages/cli/templates/gallery/app/features/boundaries/private/unauthorized.ts
+++ b/packages/cli/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>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/broadcast/page.ts b/packages/cli/templates/gallery/app/features/broadcast/page.ts
index 511d8a746..b7c59673e 100644
--- a/packages/cli/templates/gallery/app/features/broadcast/page.ts
+++ b/packages/cli/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>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/caching/page.ts b/packages/cli/templates/gallery/app/features/caching/page.ts
index a98c4574c..a55f9d9c2 100644
--- a/packages/cli/templates/gallery/app/features/caching/page.ts
+++ b/packages/cli/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>.
diff --git a/packages/cli/templates/gallery/app/features/client-router/page.ts b/packages/cli/templates/gallery/app/features/client-router/page.ts
index 2ce6b3124..9875d20d4 100644
--- a/packages/cli/templates/gallery/app/features/client-router/page.ts
+++ b/packages/cli/templates/gallery/app/features/client-router/page.ts
@@ -8,19 +8,20 @@
 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="${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>
diff --git a/packages/cli/templates/gallery/app/features/client-router/second/page.ts b/packages/cli/templates/gallery/app/features/client-router/second/page.ts
index 66565bab3..cc3152574 100644
--- a/packages/cli/templates/gallery/app/features/client-router/second/page.ts
+++ b/packages/cli/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>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/components/page.ts b/packages/cli/templates/gallery/app/features/components/page.ts
index 91e9e353c..4c1a05196 100644
--- a/packages/cli/templates/gallery/app/features/components/page.ts
+++ b/packages/cli/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>
diff --git a/packages/cli/templates/gallery/app/features/directives/page.ts b/packages/cli/templates/gallery/app/features/directives/page.ts
index 462a4ad75..2aee2b633 100644
--- a/packages/cli/templates/gallery/app/features/directives/page.ts
+++ b/packages/cli/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>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/env/page.ts b/packages/cli/templates/gallery/app/features/env/page.ts
index fa60297be..a92de3176 100644
--- a/packages/cli/templates/gallery/app/features/env/page.ts
+++ b/packages/cli/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>
diff --git a/packages/cli/templates/gallery/app/features/file-storage/page.ts b/packages/cli/templates/gallery/app/features/file-storage/page.ts
index ce85850da..8270e1a3d 100644
--- a/packages/cli/templates/gallery/app/features/file-storage/page.ts
+++ b/packages/cli/templates/gallery/app/features/file-storage/page.ts
@@ -6,6 +6,8 @@
 // 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';
 
@@ -34,13 +36,13 @@ 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" />
@@ -52,7 +54,7 @@ export default function FileStorageExample({
       : ''}
     ${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>
diff --git a/packages/cli/templates/gallery/app/features/forms/page.ts b/packages/cli/templates/gallery/app/features/forms/page.ts
index 4c9dbf0e1..6e686d404 100644
--- a/packages/cli/templates/gallery/app/features/forms/page.ts
+++ b/packages/cli/templates/gallery/app/features/forms/page.ts
@@ -9,6 +9,7 @@ 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' };
@@ -33,7 +34,7 @@ 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>
+      ${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>
diff --git a/packages/cli/templates/gallery/app/features/frames/page.ts b/packages/cli/templates/gallery/app/features/frames/page.ts
index 05669f8c7..79f9b99c9 100644
--- a/packages/cli/templates/gallery/app/features/frames/page.ts
+++ b/packages/cli/templates/gallery/app/features/frames/page.ts
@@ -21,6 +21,7 @@
 // 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 { pageHeading, lede } from '#lib/utils/ui.ts';
 import type { Metadata } from '@webjsdev/core';
 import { filterTasks, normalizeStatus, type Status } from '#modules/frames/utils/tasks.ts';
 
@@ -42,15 +43,15 @@ 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 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.
-    </p>
+    `)}
     <webjs-frame id="tasks" class="${cardClass()} block p-4">
       <div class="flex gap-2 mb-4">
         ${filterTab(status, 'all', 'All')}
diff --git a/packages/cli/templates/gallery/app/features/layout.ts b/packages/cli/templates/gallery/app/features/layout.ts
index 1c3fa8fe6..9c64a22b7 100644
--- a/packages/cli/templates/gallery/app/features/layout.ts
+++ b/packages/cli/templates/gallery/app/features/layout.ts
@@ -1,4 +1,5 @@
 import { html } from '@webjsdev/core';
+import { backLink } from '#lib/utils/ui.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.
@@ -6,7 +7,7 @@ import { html } from '@webjsdev/core';
 // A non-root layout, so it never writes the document shell (the framework does).
 export default function FeaturesLayout({ children }: { children: unknown }) {
   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>
+    ${backLink('/', html`&larr; Gallery`)}
     ${children}
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/metadata/page.ts b/packages/cli/templates/gallery/app/features/metadata/page.ts
index 47ef5e57f..7da9c21bd 100644
--- a/packages/cli/templates/gallery/app/features/metadata/page.ts
+++ b/packages/cli/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,12 +32,12 @@ 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>
diff --git a/packages/cli/templates/gallery/app/features/optimistic-ui/page.ts b/packages/cli/templates/gallery/app/features/optimistic-ui/page.ts
index 825fc4862..9eaa79b12 100644
--- a/packages/cli/templates/gallery/app/features/optimistic-ui/page.ts
+++ b/packages/cli/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" href="/examples/todo">/examples/todo</a>.`)}
     <like-button></like-button>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/rate-limit/page.ts b/packages/cli/templates/gallery/app/features/rate-limit/page.ts
index 58f3bfc46..7231d8e13 100644
--- a/packages/cli/templates/gallery/app/features/rate-limit/page.ts
+++ b/packages/cli/templates/gallery/app/features/rate-limit/page.ts
@@ -5,19 +5,20 @@
 // 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">
       With JavaScript off, hit
diff --git a/packages/cli/templates/gallery/app/features/route-handler/page.ts b/packages/cli/templates/gallery/app/features/route-handler/page.ts
index e0b5d2be5..4418c1dcd 100644
--- a/packages/cli/templates/gallery/app/features/route-handler/page.ts
+++ b/packages/cli/templates/gallery/app/features/route-handler/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/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>
+    ${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" 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>
diff --git a/packages/cli/templates/gallery/app/features/routing/[id]/page.ts b/packages/cli/templates/gallery/app/features/routing/[id]/page.ts
index 4f8ca9ee6..832b867b3 100644
--- a/packages/cli/templates/gallery/app/features/routing/[id]/page.ts
+++ b/packages/cli/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,7 +24,7 @@ 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">
       Typed with <code class="font-mono">PageProps&lt;'/features/routing/[id]'&gt;</code>,
diff --git a/packages/cli/templates/gallery/app/features/routing/page.ts b/packages/cli/templates/gallery/app/features/routing/page.ts
index ca2dfe542..8ae988a04 100644
--- a/packages/cli/templates/gallery/app/features/routing/page.ts
+++ b/packages/cli/templates/gallery/app/features/routing/page.ts
@@ -3,13 +3,14 @@
 // `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>
diff --git a/packages/cli/templates/gallery/app/features/server-actions/page.ts b/packages/cli/templates/gallery/app/features/server-actions/page.ts
index b58338f40..f49ffde4a 100644
--- a/packages/cli/templates/gallery/app/features/server-actions/page.ts
+++ b/packages/cli/templates/gallery/app/features/server-actions/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/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
diff --git a/packages/cli/templates/gallery/app/features/service-worker/page.ts b/packages/cli/templates/gallery/app/features/service-worker/page.ts
index c574b1708..9ccd2bce8 100644
--- a/packages/cli/templates/gallery/app/features/service-worker/page.ts
+++ b/packages/cli/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();
diff --git a/packages/cli/templates/gallery/app/features/sessions/page.ts b/packages/cli/templates/gallery/app/features/sessions/page.ts
index 421095ba3..01d239e5d 100644
--- a/packages/cli/templates/gallery/app/features/sessions/page.ts
+++ b/packages/cli/templates/gallery/app/features/sessions/page.ts
@@ -5,13 +5,14 @@
 // 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>
+    ${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" 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>
   `;
diff --git a/packages/cli/templates/gallery/app/features/stream/page.ts b/packages/cli/templates/gallery/app/features/stream/page.ts
index 82a0ae58c..4a90cde56 100644
--- a/packages/cli/templates/gallery/app/features/stream/page.ts
+++ b/packages/cli/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
diff --git a/packages/cli/templates/gallery/app/features/streaming/page.ts b/packages/cli/templates/gallery/app/features/streaming/page.ts
index 2bf79d622..ed98c1df7 100644
--- a/packages/cli/templates/gallery/app/features/streaming/page.ts
+++ b/packages/cli/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
diff --git a/packages/cli/templates/gallery/app/features/suspense/page.ts b/packages/cli/templates/gallery/app/features/suspense/page.ts
index 68b603803..4321c0c1b 100644
--- a/packages/cli/templates/gallery/app/features/suspense/page.ts
+++ b/packages/cli/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
diff --git a/packages/cli/templates/gallery/app/features/view-transitions/page.ts b/packages/cli/templates/gallery/app/features/view-transitions/page.ts
index db287dd7e..836ab122f 100644
--- a/packages/cli/templates/gallery/app/features/view-transitions/page.ts
+++ b/packages/cli/templates/gallery/app/features/view-transitions/page.ts
@@ -9,6 +9,8 @@
 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',
@@ -17,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,
@@ -27,7 +29,7 @@ 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="${buttonClass()} no-underline">Go to page two</a>
diff --git a/packages/cli/templates/gallery/app/features/view-transitions/second/page.ts b/packages/cli/templates/gallery/app/features/view-transitions/second/page.ts
index d81efc96d..0da67caaf 100644
--- a/packages/cli/templates/gallery/app/features/view-transitions/second/page.ts
+++ b/packages/cli/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>
   `;
diff --git a/packages/cli/templates/gallery/app/features/websockets/page.ts b/packages/cli/templates/gallery/app/features/websockets/page.ts
index da1184ac3..7d5e66947 100644
--- a/packages/cli/templates/gallery/app/features/websockets/page.ts
+++ b/packages/cli/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>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/global-not-found.ts b/packages/cli/templates/gallery/app/global-not-found.ts
index 5a8ffca94..80405c4d2 100644
--- a/packages/cli/templates/gallery/app/global-not-found.ts
+++ b/packages/cli/templates/gallery/app/global-not-found.ts
@@ -8,14 +8,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>
   `;
 }
diff --git a/packages/cli/templates/gallery/modules/broadcast/components/broadcast-feed.ts b/packages/cli/templates/gallery/modules/broadcast/components/broadcast-feed.ts
index 620c57543..2512a312f 100644
--- a/packages/cli/templates/gallery/modules/broadcast/components/broadcast-feed.ts
+++ b/packages/cli/templates/gallery/modules/broadcast/components/broadcast-feed.ts
@@ -5,6 +5,7 @@
 // the page still reads with JS off (a live feed has no no-JS equivalent).
 import { WebComponent, signal, html, connectWS } from '@webjsdev/core';
 import { buttonClass } from '#components/ui/button.ts';
+import { inputClass } from '#components/ui/input.ts';
 
 export class BroadcastFeed extends WebComponent {
   private connected = signal(false);
@@ -46,7 +47,7 @@ export class BroadcastFeed extends WebComponent {
         </div>
         <form @submit=${(e: SubmitEvent) => this.send(e)} class="flex gap-2">
           <input name="msg" autocomplete="off" placeholder="Message everyone"
-            class="flex-1 px-3 py-2 rounded-xl bg-card border border-border text-foreground text-sm outline-none focus:border-border-strong" />
+            class=${inputClass('flex-1 min-w-0')} />
           <button type="submit"
             class=${buttonClass({ size: 'sm' })}>Send</button>
         </form>
diff --git a/packages/cli/templates/gallery/modules/components/components/reactive-meter.ts b/packages/cli/templates/gallery/modules/components/components/reactive-meter.ts
index c8cb3e9f1..68f14f0b6 100644
--- a/packages/cli/templates/gallery/modules/components/components/reactive-meter.ts
+++ b/packages/cli/templates/gallery/modules/components/components/reactive-meter.ts
@@ -10,7 +10,7 @@ export class ReactiveMeter extends WebComponent {
   static styles = css`
     .row { display: flex; align-items: center; gap: 8px; }
     button {
-      padding: 6px 12px; border-radius: 10px; border: 1px solid #8883;
+      padding: 6px 12px; border-radius: 10px; border: 1px solid var(--color-border);
       background: transparent; color: inherit; cursor: pointer; font: inherit;
     }
     .val { font-variant-numeric: tabular-nums; font-weight: 600; }
diff --git a/packages/cli/templates/gallery/modules/components/components/task-loader.ts b/packages/cli/templates/gallery/modules/components/components/task-loader.ts
index 2e41f0f8b..640d76cc7 100644
--- a/packages/cli/templates/gallery/modules/components/components/task-loader.ts
+++ b/packages/cli/templates/gallery/modules/components/components/task-loader.ts
@@ -34,7 +34,7 @@ export class TaskLoader extends WebComponent {
     const t = this.task;
     const body =
       t.status === TaskStatus.PENDING ? html`<span class="text-muted-foreground">loading…</span>`
-      : t.status === TaskStatus.ERROR ? html`<span class="text-red-500">error: ${String((t.error as Error)?.message ?? t.error)}</span>`
+      : t.status === TaskStatus.ERROR ? html`<span class="text-destructive">error: ${String((t.error as Error)?.message ?? t.error)}</span>`
       : t.status === TaskStatus.COMPLETE ? html`<span class="text-foreground">${t.value}</span>`
       : html`<span class="text-muted-foreground">idle</span>`;
     return html`
diff --git a/packages/cli/templates/gallery/modules/components/components/theme-context.ts b/packages/cli/templates/gallery/modules/components/components/theme-context.ts
index 5c6995c6e..4f25b5a5c 100644
--- a/packages/cli/templates/gallery/modules/components/components/theme-context.ts
+++ b/packages/cli/templates/gallery/modules/components/components/theme-context.ts
@@ -8,6 +8,7 @@
 // children normally.
 import { WebComponent, html, signal } from '@webjsdev/core';
 import { buttonClass } from '#components/ui/button.ts';
+import { cardClass } from '#components/ui/card.ts';
 import { createContext, ContextProvider, ContextConsumer, ContextRequestEvent } from '@webjsdev/core/context';
 
 type Theme = 'light' | 'dark';
@@ -27,7 +28,7 @@ export class ThemeProvider extends WebComponent {
 
   render() {
     return html`
-      <div class="grid gap-3 p-3 rounded-xl bg-card border border-border max-w-[420px]">
+      <div class=${cardClass('grid gap-3 p-3 max-w-[420px]')}>
         <button @click=${() => this.toggle()}
           class="${buttonClass({ size: 'sm' })} w-fit">
           provider theme: ${this.provider.value} (toggle)
diff --git a/packages/cli/templates/gallery/modules/directives/components/directive-demo.ts b/packages/cli/templates/gallery/modules/directives/components/directive-demo.ts
index 3e3537555..9f7f0dbe5 100644
--- a/packages/cli/templates/gallery/modules/directives/components/directive-demo.ts
+++ b/packages/cli/templates/gallery/modules/directives/components/directive-demo.ts
@@ -13,6 +13,7 @@
 // iterable, appending each or replacing with the latest).
 import { WebComponent, signal, html } from '@webjsdev/core';
 import { buttonClass } from '#components/ui/button.ts';
+import { inputClass } from '#components/ui/input.ts';
 import { repeat, watch, live, until, keyed, unsafeHTML, ref, createRef, guard, cache, templateContent, asyncAppend, asyncReplace } from '@webjsdev/core/directives';
 
 interface Item { id: number; label: string }
@@ -133,7 +134,7 @@ export class DirectiveDemo extends WebComponent {
             <input
               ${ref(this.inputRef)}
               aria-label="Editable text for the ref focus demo"
-              class="flex-1 px-3 py-1.5 rounded-xl bg-card border border-border text-[15px] text-foreground"
+              class=${inputClass('flex-1 min-w-0')}
               .value=${live(this.text.get())}
               @input=${(e: Event) => this.text.set((e.target as HTMLInputElement).value)}>
             <button @click=${() => this.focusInput()}
diff --git a/packages/cli/templates/gallery/modules/todo/components/todo-app.ts b/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
index 67528649b..4cdfe520d 100644
--- a/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
+++ b/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
@@ -12,6 +12,7 @@
 import { WebComponent, prop, optimistic, 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 { createTodo } from '../actions/create-todo.server.ts';
 import { toggleTodo } from '../actions/toggle-todo.server.ts';
 import { deleteTodo } from '../actions/delete-todo.server.ts';
@@ -126,7 +127,7 @@ export class TodoApp extends WebComponent({
                 <!-- Delete: a proper icon button, revealed on row hover / focus. -->
                 <button type="submit" name="intent" value="delete" aria-label="Delete task"
                   @click=${(e: Event) => this.removeTodo(e, todo)}
-                  class="shrink-0 grid place-items-center w-7 h-7 rounded-lg border-0 bg-transparent text-muted-foreground cursor-pointer opacity-0 group-hover:opacity-100 focus:opacity-100 transition-all hover:text-destructive hover:bg-[color-mix(in_oklch,var(--color-destructive)_12%,transparent)]">
+                  class=${cn(buttonClass({ variant: 'destructive', size: 'none' }), 'w-7 h-7 rounded-lg opacity-0 group-hover:opacity-100 focus:opacity-100')}>
                   <svg viewBox="0 0 24 24" class="w-4 h-4 stroke-current fill-none" style="stroke-width:2;stroke-linecap:round;stroke-linejoin:round"><path d="M18 6 6 18M6 6l12 12"/></svg>
                 </button>
               </form>
diff --git a/packages/cli/templates/gallery/modules/websockets/components/ws-echo.ts b/packages/cli/templates/gallery/modules/websockets/components/ws-echo.ts
index fa1dc4049..20b414b68 100644
--- a/packages/cli/templates/gallery/modules/websockets/components/ws-echo.ts
+++ b/packages/cli/templates/gallery/modules/websockets/components/ws-echo.ts
@@ -6,6 +6,7 @@
 // (a live socket has no no-JS equivalent, which is the honest fallback here).
 import { WebComponent, signal, html, connectWS, renderStream } from '@webjsdev/core';
 import { buttonClass } from '#components/ui/button.ts';
+import { inputClass } from '#components/ui/input.ts';
 
 export class WsEcho extends WebComponent {
   private connected = signal(false);
@@ -60,7 +61,7 @@ export class WsEcho extends WebComponent {
         </div>
         <form @submit=${(e: SubmitEvent) => this.send(e)} class="flex gap-2">
           <input name="msg" autocomplete="off" placeholder="Say something"
-            class="flex-1 px-3 py-2 rounded-xl bg-card border border-border text-foreground text-sm outline-none focus:border-border-strong" />
+            class=${inputClass('flex-1 min-w-0')} />
           <button type="submit"
             class=${buttonClass({ size: 'sm' })}>Send</button>
         </form>

From 69901a1e6ea5d5f3b2db5289835f16363b9d82d3 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 14:36:55 +0530
Subject: [PATCH 25/73] chore(gallery): clear removes lib/utils/ui.ts; update
 tests for helpers

gallery:clear now also removes lib/utils/ui.ts (its users, the feature pages +
features/examples layouts, are all cleared), keeping cn.ts/dom.ts. Update the
scaffold-gallery tests: assert ui.ts is present pre-clear and removed post-clear,
and match the back-to-gallery link via the backLink('/') helper instead of a
literal href. Verified: full suite green, boundary routes render (403/401/404 +
error boundary).
---
 packages/cli/templates/scripts/clear-gallery.mjs | 4 ++++
 test/scaffolds/scaffold-gallery.test.js          | 6 ++++--
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/packages/cli/templates/scripts/clear-gallery.mjs b/packages/cli/templates/scripts/clear-gallery.mjs
index b88e84339..5a3fc98a6 100644
--- a/packages/cli/templates/scripts/clear-gallery.mjs
+++ b/packages/cli/templates/scripts/clear-gallery.mjs
@@ -66,6 +66,10 @@ const galleryPaths = [
   // for a true blank slate; the layout's theme import is stripped separately
   // below. The agent writes its own tests + components for the real app.
   'components/theme-toggle.ts', 'test/hello',
+  // The gallery's markup-chunk helpers. Their only users (the feature pages +
+  // the features/examples layouts) are removed above, so drop the example file
+  // too; cn.ts + dom.ts (real infrastructure) stay under lib/utils/.
+  'lib/utils/ui.ts',
 ];
 // 2) The gallery's feature modules (by name). `auth` is the auth card's server
 // modules (createAuth config, password hashing, signup action, current-user
diff --git a/test/scaffolds/scaffold-gallery.test.js b/test/scaffolds/scaffold-gallery.test.js
index 99bbf91e7..c7a9bba60 100644
--- a/test/scaffolds/scaffold-gallery.test.js
+++ b/test/scaffolds/scaffold-gallery.test.js
@@ -55,10 +55,10 @@ test('full-stack scaffold ships feature demos and one example app', async () =>
       assert.ok(await exists(join(appDir, 'app', 'features', name, 'page.ts')), `app/features/${name}/page.ts`);
     }
     // Shared layouts give every feature demo AND every example app a
-    // back-to-gallery link so no card is a dead end (each links the home at /).
+    // back-to-gallery link so no card is a dead end (via the backLink('/') helper).
     for (const seg of ['features', 'examples']) {
       const layout = await readFile(join(appDir, 'app', seg, 'layout.ts'), 'utf8');
-      assert.match(layout, /href="\/"/, `${seg} layout links back to the gallery home`);
+      assert.match(layout, /backLink\('\/'/, `${seg} layout links back to the gallery home`);
       assert.match(layout, /Gallery/, `${seg} layout renders a Gallery link`);
     }
     for (const name of EXAMPLE_APPS) {
@@ -179,6 +179,7 @@ test('full-stack gallery:clear strips the app to a barebones blank slate', async
     assert.ok(has('components', 'ui', 'button.ts'), 'pre: components/ui design system exists');
     assert.ok(has('components', 'theme-toggle.ts'), 'pre: example theme-toggle exists');
     assert.ok(has('test', 'hello'), 'pre: example test suite exists');
+    assert.ok(has('lib', 'utils', 'ui.ts'), 'pre: gallery ui.ts fragment helpers exist');
     assert.ok(has('app', 'api', 'auth'), 'pre: gallery auth handler under app/api exists');
     assert.match(await readFile(join(appDir, 'app', 'layout.ts'), 'utf8'), /theme-toggle/, 'pre: layout imports theme-toggle');
 
@@ -200,6 +201,7 @@ test('full-stack gallery:clear strips the app to a barebones blank slate', async
 
     // Kept: the buildable base.
     assert.ok(has('.agents', 'skills', 'webjs', 'SKILL.md'), 'the durable agent skill is kept');
+    assert.equal(has('lib', 'utils', 'ui.ts'), false, 'gallery ui.ts fragment helpers removed');
     assert.ok(has('lib', 'utils', 'cn.ts'), 'cn.ts kept (webjs ui add prerequisite)');
     assert.ok(has('db', 'connection.server.ts'), 'db wiring kept');
     assert.ok(has('components'), 'components/ kept as an (empty) build target');

From 14ff1c8a2e83152b363fcc1a1ee08f8b74539bc2 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 14:39:39 +0530
Subject: [PATCH 26/73] test: the full-stack scaffold ships the gallery design
 system

Update stale assertions: the gallery now ships components/ui/ (buttonClass/
cardClass/inputClass/badgeClass) + lib/utils/ui.ts, and the home builds its cards
on cardClass/badgeClass. The pre-init config (components.json, cn.ts,
styles/globals.css) still ships for webjs ui add. Full scaffold suite green (46).
---
 test/scaffolds/scaffold-ui-integration.test.js | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/test/scaffolds/scaffold-ui-integration.test.js b/test/scaffolds/scaffold-ui-integration.test.js
index 571af53b5..4bae774d0 100644
--- a/test/scaffolds/scaffold-ui-integration.test.js
+++ b/test/scaffolds/scaffold-ui-integration.test.js
@@ -28,15 +28,17 @@ test('full-stack scaffold pre-initialises the Webjs UI kit', async () => {
     await scaffoldApp('demo', cwd, { template: 'full-stack' });
     const appDir = join(cwd, 'demo');
 
-    // Bootstrap for `webjs ui add`: the config + cn() helper + theme ship, but
-    // NOT a pre-copied component kit (a UI app adds components on demand with
-    // `webjs ui add <name>`; the gallery cards style with plain Tailwind).
+    // Bootstrap for `webjs ui add`: the config + cn() helper + theme ship, so an
+    // app can add more components on demand. The gallery ALSO ships its example
+    // design system (components/ui/ class helpers + lib/utils/ui.ts fragment
+    // helpers) that the demos use; gallery:clear removes those examples.
     assert.ok(await exists(join(appDir, 'components.json')), 'components.json should exist');
     assert.ok(await exists(join(appDir, 'lib', 'utils', 'cn.ts')), 'lib/utils/cn.ts should exist');
     assert.ok(await exists(join(appDir, 'styles', 'globals.css')), 'styles/globals.css should exist');
     assert.equal(existsSync(join(appDir, 'app', 'globals.css')), false, 'globals.css must not be in routing-only app/');
-    assert.ok(!(await exists(join(appDir, 'components', 'ui'))), 'full-stack pre-copies no ui-* kit');
-    assert.ok(!(await exists(join(appDir, 'lib', 'utils', 'ui.ts'))), 'the ui.ts class-bundle helper is removed');
+    assert.ok(await exists(join(appDir, 'components', 'ui', 'button.ts')), 'the gallery ships the design system (components/ui)');
+    assert.ok(await exists(join(appDir, 'components', 'ui', 'badge.ts')), 'the gallery ships badgeClass');
+    assert.ok(await exists(join(appDir, 'lib', 'utils', 'ui.ts')), 'the gallery ships the ui.ts fragment helpers');
 
     // components.json shape matches what webjsui init writes for webjs
     const cfg = JSON.parse(await readFile(join(appDir, 'components.json'), 'utf8'));
@@ -45,11 +47,11 @@ test('full-stack scaffold pre-initialises the Webjs UI kit', async () => {
     assert.equal(cfg.aliases.ui, 'components/ui');
     assert.equal(cfg.aliases.utils, 'lib/utils/cn');
 
-    // The minimal home is a plain welcome page, using no ui-* helpers.
+    // The gallery home builds its feature/example cards on the design system.
     const layout = await readFile(join(appDir, 'app', 'layout.ts'), 'utf8');
     const page = await readFile(join(appDir, 'app', 'page.ts'), 'utf8');
-    assert.match(page, /Welcome to/, 'home is the minimal welcome page');
-    assert.doesNotMatch(page, /buttonClass|cardClass|rubric/, 'home uses no ui-* class helpers');
+    assert.match(page, /Welcome to/, 'home is the gallery welcome page');
+    assert.match(page, /cardClass|badgeClass/, 'the home cards use the design-system helpers');
 
     // CSS delivery (#947): the layout links a STATIC compiled stylesheet (works
     // with JS off), not the browser runtime. The Tailwind @theme maps live in

From f809db0b86a5af8352f80048dea3ce29dc047655 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 15:41:34 +0530
Subject: [PATCH 27/73] fix(ui): cn resolves shorthand-vs-axis conflicts (p-0
 over px-4 py-2)

The hand-rolled cn treated p/px/py (and m/mx/my, size/w/h) as independent
groups, so a shorthand never overrode the axis it subsumes: cn('px-4 py-2','p-0')
kept all three, leaving the winner to Tailwind source order (the icon-button
sharp edge). Add tailwind-merge's directional CONFLICTS model: a shorthand
invalidates the earlier axis/side groups it subsumes, but a later axis only
refines a shorthand (both survive). Test the padding/margin/size cases + variant
isolation. Reframe the styling.md icon-button note (size:'none' is still the
clean intent, but an override now just works).
---
 .agents/skills/webjs/references/styling.md |  2 +-
 packages/ui/packages/registry/lib/utils.ts | 42 +++++++++++++++++-----
 packages/ui/test/cn-helper.test.js         | 18 ++++++++++
 3 files changed, 53 insertions(+), 9 deletions(-)

diff --git a/.agents/skills/webjs/references/styling.md b/.agents/skills/webjs/references/styling.md
index 512423598..a24d5cb9b 100644
--- a/.agents/skills/webjs/references/styling.md
+++ b/.agents/skills/webjs/references/styling.md
@@ -70,7 +70,7 @@ Avoid `@apply`: it hides which utilities a class uses and creates a second sourc
 
 ### A design system for repeated PRIMITIVES: class helpers built on `@webjsdev/ui`
 
-An `html`-fragment helper is right for a repeated CHUNK of markup (the rubric above). For a repeated UI PRIMITIVE (button, input, card, badge) that needs variants and sizes, use a class helper instead: a function that returns a Tailwind class STRING you spread onto a native element. That is exactly what `@webjsdev/ui` ships (`buttonClass({ variant, size })`, `cardClass()`, `inputClass()`, `badgeClass({ variant })`), and it is what the scaffold gallery uses in `components/ui/`. To style a ONE-OFF that a variant does not cover (a circular icon button, a pill), compose the helper and override the bespoke bits with `cn()`: `cn(buttonClass({ variant: 'secondary', size: 'none' }), 'w-9 h-9 rounded-full')`. Use `size: 'none'` for an icon button (it drops the helper's padding/radius so your `w-/h-/rounded-` apply cleanly), since `cn`'s merge does NOT resolve a `p-0` against `px-4 py-2`.
+An `html`-fragment helper is right for a repeated CHUNK of markup (the rubric above). For a repeated UI PRIMITIVE (button, input, card, badge) that needs variants and sizes, use a class helper instead: a function that returns a Tailwind class STRING you spread onto a native element. That is exactly what `@webjsdev/ui` ships (`buttonClass({ variant, size })`, `cardClass()`, `inputClass()`, `badgeClass({ variant })`), and it is what the scaffold gallery uses in `components/ui/`. To style a ONE-OFF that a variant does not cover (a circular icon button, a pill), compose the helper and override the bespoke bits with `cn()`: `cn(buttonClass({ variant: 'secondary', size: 'none' }), 'w-9 h-9 rounded-full')`. `cn` resolves Tailwind conflicts so a later class wins, including a shorthand over the axis it subsumes (`p-0` beats an earlier `px-4 py-2`), so an override just works. For an icon button prefer `size: 'none'` (it states "I supply my own box" by dropping the helper's padding + radius) over layering a `p-0` on top of the default size.
 
 ```ts
 // components/ui/button.ts  (webjs ui add button, themed to your app)
diff --git a/packages/ui/packages/registry/lib/utils.ts b/packages/ui/packages/registry/lib/utils.ts
index f5dc4491b..e24a6182f 100644
--- a/packages/ui/packages/registry/lib/utils.ts
+++ b/packages/ui/packages/registry/lib/utils.ts
@@ -73,22 +73,48 @@ const GROUPS: Array<[RegExp, string]> = [
   [/^grid(-|$)/, 'grid'],
 ];
 
+// Directional shorthand conflicts (the tailwind-merge model). A shorthand
+// utility invalidates the axis / side utilities it SUBSUMES, because Tailwind's
+// cascade makes the shorthand win: `p-0` after `px-4 py-2` drops both, but
+// `px-4` after `p-2` refines only the x-axis so BOTH survive (the conflict is
+// directional, not symmetric). Keyed by the group a NEWLY-seen token belongs to;
+// the value lists the EARLIER groups whose survivors it removes (its own group
+// is always removed too, handled below).
+const CONFLICTS: Record<string, string[]> = {
+  p: ['px', 'py', 'pt', 'pr', 'pb', 'pl'],
+  px: ['pl', 'pr'],
+  py: ['pt', 'pb'],
+  m: ['mx', 'my', 'mt', 'mr', 'mb', 'ml'],
+  mx: ['ml', 'mr'],
+  my: ['mt', 'mb'],
+  size: ['w', 'h'],
+};
+
 function dedupeUtilities(input: string): string {
   const tokens = input.split(/\s+/).filter(Boolean);
-  const seen = new Map<string, number>();
+  // `${prefix}::${group}` -> index of the last SURVIVING token in that group.
+  const lastByKey = new Map<string, number>();
   const result: Array<string | null> = [];
 
   for (const token of tokens) {
-    let key: string | null = null;
-    // Strip variant prefix (`hover:`, `dark:md:`, …) before testing each
-    // dedupe regex so `hover:bg-red-500` still matches the `bg-color` group.
+    // Strip variant prefix (`hover:`, `dark:md:`, …) before testing each dedupe
+    // regex so `hover:bg-red-500` still matches the `bg-color` group. Conflicts
+    // only apply WITHIN the same variant (`px-4 hover:p-0` keeps both).
     const prefix = variantPrefix(token);
     const bare = prefix ? token.slice(prefix.length) : token;
-    for (const [re, gk] of GROUPS) {
-      if (re.test(bare)) { key = `${prefix}::${gk}`; break; }
+    let gk: string | null = null;
+    for (const [re, g] of GROUPS) {
+      if (re.test(bare)) { gk = g; break; }
+    }
+    if (gk) {
+      // Remove earlier survivors in this group AND in every group it subsumes.
+      for (const g of [gk, ...(CONFLICTS[gk] ?? [])]) {
+        const k = `${prefix}::${g}`;
+        const idx = lastByKey.get(k);
+        if (idx !== undefined) { result[idx] = null; lastByKey.delete(k); }
+      }
+      lastByKey.set(`${prefix}::${gk}`, result.length);
     }
-    if (key && seen.has(key)) result[seen.get(key)!] = null;
-    if (key) seen.set(key, result.length);
     result.push(token);
   }
   return result.filter(Boolean).join(' ');
diff --git a/packages/ui/test/cn-helper.test.js b/packages/ui/test/cn-helper.test.js
index 2ade19649..98d26f66c 100644
--- a/packages/ui/test/cn-helper.test.js
+++ b/packages/ui/test/cn-helper.test.js
@@ -66,6 +66,24 @@ test('cn: padding subgroups: px-4 + py-2 coexist; px-4 + px-6 collapses to px-6'
   assert.match(out, /py-2/);
 });
 
+test('cn: a shorthand overrides the axis/side it subsumes (the icon-button gap)', () => {
+  // The bug this fixes: buttonClass() ships px-4 py-2, and cn(..., 'p-0') used to
+  // keep all three (unreliable). A shorthand now wins over what it subsumes.
+  assert.equal(cn('px-4', 'py-2', 'p-0'), 'p-0');
+  // Directional, not symmetric: shorthand THEN axis refines (both survive);
+  // axis THEN shorthand collapses to the shorthand.
+  assert.equal(cn('p-4', 'px-2'), 'p-4 px-2');
+  assert.equal(cn('px-2', 'p-4'), 'p-4');
+  // Side vs axis: a later px removes an earlier pl/pr; a later side refines px.
+  assert.equal(cn('pl-1', 'px-2'), 'px-2');
+  assert.equal(cn('px-2', 'pl-1'), 'px-2 pl-1');
+  // Margin behaves the same; size subsumes w and h.
+  assert.equal(cn('mx-4', 'm-0'), 'm-0');
+  assert.equal(cn('w-8', 'size-4'), 'size-4');
+  // Conflicts stay within a variant (a hover: shorthand does not touch a base axis).
+  assert.equal(cn('px-4', 'hover:p-0'), 'px-4 hover:p-0');
+});
+
 test('cn: variant prefixes (hover:, dark:) dedupe within their own variant only', () => {
   const out = cn('bg-white', 'hover:bg-blue-500', 'hover:bg-red-500');
   assert.match(out, /bg-white/);

From 16bf72d3c2682493c7a9a7d9f84b44cf9bfeb76c Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 15:45:23 +0530
Subject: [PATCH 28/73] fix(blog): sync the dogfood cn to the
 shorthand-conflict fix

examples/blog ships a hand-committed lib/utils/cn.ts (the shadcn you-own-it copy,
not auto-synced), so it still had the flat-group cn where p-0 did not override
px-4 py-2. Apply the same CONFLICTS fix as the registry source. (The canonical
fix lives in packages/ui/packages/registry/lib/utils.ts, which webjs ui init +
the scaffold pull from; this syncs the one committed downstream copy.)
---
 examples/blog/lib/utils/cn.ts | 37 +++++++++++++++++++++++++++--------
 1 file changed, 29 insertions(+), 8 deletions(-)

diff --git a/examples/blog/lib/utils/cn.ts b/examples/blog/lib/utils/cn.ts
index 28604fbcf..66e5dc02d 100644
--- a/examples/blog/lib/utils/cn.ts
+++ b/examples/blog/lib/utils/cn.ts
@@ -73,22 +73,43 @@ const GROUPS: Array<[RegExp, string]> = [
   [/^grid(-|$)/, 'grid'],
 ];
 
+// Directional shorthand conflicts (the tailwind-merge model): a shorthand
+// utility invalidates the axis/side utilities it SUBSUMES (`p-0` beats an earlier
+// `px-4 py-2`), but a later axis only refines a shorthand (both survive). Keyed
+// by the group of a newly-seen token; the value lists the EARLIER groups it removes.
+const CONFLICTS: Record<string, string[]> = {
+  p: ['px', 'py', 'pt', 'pr', 'pb', 'pl'],
+  px: ['pl', 'pr'],
+  py: ['pt', 'pb'],
+  m: ['mx', 'my', 'mt', 'mr', 'mb', 'ml'],
+  mx: ['ml', 'mr'],
+  my: ['mt', 'mb'],
+  size: ['w', 'h'],
+};
+
 function dedupeUtilities(input: string): string {
   const tokens = input.split(/\s+/).filter(Boolean);
-  const seen = new Map<string, number>();
+  const lastByKey = new Map<string, number>();
   const result: Array<string | null> = [];
 
   for (const token of tokens) {
-    let key: string | null = null;
-    // Strip variant prefix (`hover:`, `dark:md:`, …) before testing each
-    // dedupe regex so `hover:bg-red-500` still matches the `bg-color` group.
+    // Strip variant prefix (`hover:`, `dark:md:`, …) before testing each dedupe
+    // regex so `hover:bg-red-500` still matches the `bg-color` group. Conflicts
+    // only apply WITHIN the same variant.
     const prefix = variantPrefix(token);
     const bare = prefix ? token.slice(prefix.length) : token;
-    for (const [re, gk] of GROUPS) {
-      if (re.test(bare)) { key = `${prefix}::${gk}`; break; }
+    let gk: string | null = null;
+    for (const [re, g] of GROUPS) {
+      if (re.test(bare)) { gk = g; break; }
+    }
+    if (gk) {
+      for (const g of [gk, ...(CONFLICTS[gk] ?? [])]) {
+        const k = `${prefix}::${g}`;
+        const idx = lastByKey.get(k);
+        if (idx !== undefined) { result[idx] = null; lastByKey.delete(k); }
+      }
+      lastByKey.set(`${prefix}::${gk}`, result.length);
     }
-    if (key && seen.has(key)) result[seen.get(key)!] = null;
-    if (key) seen.set(key, result.length);
     result.push(token);
   }
   return result.filter(Boolean).join(' ');

From 71d4d2aa9b3ba550966ba0508630c278ef3d92b5 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 16:01:03 +0530
Subject: [PATCH 29/73] feat(gallery): add a grouped left sidebar + centered
 docs-style layout

Feature pages now use a two-column docs shell (like ui.webjs.dev/docs): a sticky,
grouped sidebar listing every demo with the current one highlighted, plus the
content. The demo index is defined ONCE in modules/gallery/nav.ts (the home cards
and the sidebar both read it, so they cannot drift). The sidebar is a
<gallery-nav> component that tracks the active demo across SOFT navigation (the
features layout is preserved on soft-nav, so a server-only highlight would go
stale) by listening to the router's webjs:navigate event; SSR seeds the active
item from the layout's url. Center the whole app (root <main> max-w-5xl mx-auto),
mobile keeps the back link. gallery:clear removes modules/gallery. Verified:
generate + check + typecheck + boot, home + sidebar render, active highlight SSRs.
---
 packages/cli/lib/create.js                    | 42 ++--------
 .../templates/gallery/app/features/layout.ts  | 19 +++--
 .../modules/gallery/components/gallery-nav.ts | 52 ++++++++++++
 .../templates/gallery/modules/gallery/nav.ts  | 79 +++++++++++++++++++
 .../cli/templates/scripts/clear-gallery.mjs   |  2 +-
 5 files changed, 151 insertions(+), 43 deletions(-)
 create mode 100644 packages/cli/templates/gallery/modules/gallery/components/gallery-nav.ts
 create mode 100644 packages/cli/templates/gallery/modules/gallery/nav.ts

diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
index 16a07be1e..7e3736b34 100644
--- a/packages/cli/lib/create.js
+++ b/packages/cli/lib/create.js
@@ -1277,7 +1277,7 @@ export default function RootLayout({ children }: { children: unknown }) {
         -moz-osx-font-smoothing: grayscale;
       }
     </style>
-    <main class="min-h-dvh px-4 sm:px-6 py-8">
+    <main class="min-h-dvh max-w-5xl mx-auto px-4 sm:px-6 py-8">
       \${children}
     </main>
   \`;
@@ -1292,51 +1292,19 @@ export default function RootLayout({ children }: { children: unknown }) {
   await writeFile(join(appDir, 'app', 'page.ts'), `import { html } from '@webjsdev/core';
 import { cardClass } from '#components/ui/card.ts';
 import { badgeClass } from '#components/ui/badge.ts';
+// The demo index is defined once in modules/gallery/nav.ts (the same source the
+// left sidebar reads), so the home cards and the sidebar can never drift.
+import { FEATURES, EXAMPLES } from '#modules/gallery/nav.ts';
 
 export const metadata = {
   title: '${displayName}',
 };
 
-// The gallery this page links. FEATURES are single-concept demos (one WebJs
-// concept each, under app/features/, logic in modules/). EXAMPLES are whole apps
-// composing several features (under app/examples/). Prune what you do not use
-// (delete the route AND its modules/<name>), then reshape this page.
-const FEATURES = [
-  { href: '/features/routing', title: 'Routing', blurb: 'A static route plus a dynamic [id] segment that reads params. The file-based router in miniature.' },
-  { href: '/features/boundaries', title: 'Boundaries', blurb: 'The control-flow throws (forbidden / unauthorized / notFound) and the nearest boundary file that catches each.' },
-  { href: '/features/auth', title: 'Auth', blurb: 'Password login on createAuth, a signed session cookie, and a real protected route that redirects anonymous visitors to login.' },
-  { href: '/features/components', title: 'Components', blurb: 'The WebComponent factory, reactive props, instance signals, and slot projection in light DOM.' },
-  { href: '/features/server-actions', title: 'Server actions', blurb: 'A use-server RPC action next to a server-only .server.ts utility, and why the boundary matters.' },
-  { href: '/features/optimistic-ui', title: 'Optimistic UI', blurb: 'The imperative optimistic(signal, value, action) flip: instant update, automatic rollback on failure.' },
-  { href: '/features/async-render', title: 'Async render', blurb: 'A component that awaits server data in async render(), so the resolved value is in the first paint.' },
-  { href: '/features/streaming', title: 'Streaming actions', blurb: 'A use-server action that returns an async generator, streamed to the call site token by token with for await.' },
-  { href: '/features/stream', title: 'Stream updates', blurb: 'The <webjs-stream> element: renderStream() applies surgical append / replace / remove DOM updates by target id, no region redraw.' },
-  { href: '/features/suspense', title: 'Suspense boundary', blurb: 'The <webjs-suspense> element: a first-paint fallback for a SLOW component, with the resolved content streamed in.' },
-  { href: '/features/view-transitions', title: 'View transitions', blurb: 'The opt-in view-transition meta cross-fades a soft navigation, with a data-webjs-permanent element persisted across the swap.' },
-  { href: '/features/directives', title: 'Directives', blurb: 'The lit-html directive set: repeat for keyed lists, watch(signal) for a fine-grained node swap.' },
-  { href: '/features/route-handler', title: 'Route handlers', blurb: 'A server-only route.ts HTTP endpoint returning JSON, the WebJs equivalent of a Next route handler.' },
-  { href: '/features/forms', title: 'Forms', blurb: 'A no-JS progressive-enhancement form posting to the page action, with server-side validation errors.' },
-  { href: '/features/metadata', title: 'Metadata', blurb: 'Static metadata plus generateMetadata(ctx), which reads the request to compute the title and Open Graph tags.' },
-  { href: '/features/caching', title: 'Caching', blurb: 'export const revalidate caches the page HTML per URL, with the safety rule for when a shared cache is allowed.' },
-  { href: '/features/env', title: 'Env vars', blurb: 'The server-only vs WEBJS_PUBLIC_ boundary, read during SSR so secrets never reach the browser.' },
-  { href: '/features/client-router', title: 'Client router', blurb: 'Automatic soft navigation: fragment-only fetches, hover prefetch, scroll restore, and graceful no-JS fallback.' },
-  { href: '/features/frames', title: 'Frames', blurb: 'A webjs-frame region that swaps a filtered sub-list in place from a link, shipping zero component JS, with a no-JS full-nav fallback.' },
-  { href: '/features/service-worker', title: 'Service worker', blurb: 'The opt-in offline enhancement, registered from a browser-only lifecycle hook (never a page or layout).' },
-  { href: '/features/websockets', title: 'WebSockets', blurb: 'A WS(ws, req) route endpoint plus the connectWS() client, echoing messages over a live socket.' },
-  { href: '/features/broadcast', title: 'Broadcast', blurb: 'Fan a message out to every connected client on a WebSocket path, so all open tabs stay in sync.' },
-  { href: '/features/rate-limit', title: 'Rate limiting', blurb: 'The rateLimit() middleware scoped to one endpoint, returning a 429 with Retry-After past the window.' },
-  { href: '/features/file-storage', title: 'File storage', blurb: 'A no-JS multipart upload streamed into the FileStore, then served back through a streaming route.' },
-  { href: '/features/sessions', title: 'Sessions', blurb: 'A signed-cookie session applied by a segment middleware, read and written per visitor with getSession() in a route.' },
-];
-const EXAMPLES = [
-  { href: '/examples/todo', title: 'Optimistic todo', blurb: 'A whole app composing several features: the declarative optimistic() list API, progressive-enhancement forms, accessible labels, the modules split, and SQLite.' },
-];
-
 export default function Home() {
   return html\`
     <div class="fixed top-4 right-4 z-10"><theme-toggle></theme-toggle></div>
 
-    <div class="max-w-5xl mx-auto px-6 py-16 flex flex-col items-center gap-16">
+    <div class="py-8 flex flex-col items-center gap-16">
       <!-- Masthead -->
       <section class="flex flex-col items-center text-center gap-5">
         <p class="text-xs font-semibold uppercase tracking-[0.22em] text-muted-foreground m-0">Welcome to</p>
diff --git a/packages/cli/templates/gallery/app/features/layout.ts b/packages/cli/templates/gallery/app/features/layout.ts
index 9c64a22b7..be070eda8 100644
--- a/packages/cli/templates/gallery/app/features/layout.ts
+++ b/packages/cli/templates/gallery/app/features/layout.ts
@@ -1,13 +1,22 @@
 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.
+// 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`
-    ${backLink('/', html`&larr; Gallery`)}
-    ${children}
+    <div class="lg:hidden mb-6">${backLink('/', html`&larr; Gallery`)}</div>
+    <div class="grid lg:grid-cols-[190px_1fr] gap-8 lg:gap-12">
+      <aside class="hidden lg:block sticky top-6 self-start max-h-[calc(100dvh-4rem)] overflow-y-auto py-1 text-sm">
+        <gallery-nav current=${path}></gallery-nav>
+      </aside>
+      <div class="min-w-0">${children}</div>
+    </div>
   `;
 }
diff --git a/packages/cli/templates/gallery/modules/gallery/components/gallery-nav.ts b/packages/cli/templates/gallery/modules/gallery/components/gallery-nav.ts
new file mode 100644
index 000000000..2309c8103
--- /dev/null
+++ b/packages/cli/templates/gallery/modules/gallery/components/gallery-nav.ts
@@ -0,0 +1,52 @@
+// The gallery's left sidebar: a grouped index of every demo, with the current
+// one highlighted (docs-site style). WHY a component and not plain layout markup:
+// the features layout is PRESERVED across a soft navigation (only the page
+// content swaps), so a server-rendered "active" highlight would go stale. This
+// component listens for the router's `webjs:navigate` event and re-derives the
+// active item from location.pathname, so the highlight follows soft-nav. SSR is
+// still correct: `render()` reads the `current` prop (the pathname the layout
+// passes) for the first paint, and the client takes over from location after.
+import { WebComponent, prop, html, signal } from '@webjsdev/core';
+import { FEATURE_GROUPS } from '#modules/gallery/nav.ts';
+
+// Module-scope so the value survives re-renders; set on the client only (SSR
+// reads the `current` prop instead, so it never touches location during render).
+const activePath = signal('');
+
+export class GalleryNav extends WebComponent({ current: prop(String) }) {
+  #onNav = () => activePath.set(location.pathname);
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.#onNav(); // seed from the real URL on hydrate
+    document.addEventListener('webjs:navigate', this.#onNav); // soft-nav (link + navigate())
+    window.addEventListener('popstate', this.#onNav); // back / forward
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    document.removeEventListener('webjs:navigate', this.#onNav);
+    window.removeEventListener('popstate', this.#onNav);
+  }
+
+  render() {
+    // activePath is '' at SSR (and before hydrate), so fall back to the prop.
+    const active = activePath.get() || this.current;
+    const link = (href: string, title: string) => {
+      const on = active === href;
+      const cls = 'block px-3 py-1.5 -mx-2 rounded-lg no-underline transition-colors ' +
+        (on ? 'bg-accent text-foreground font-medium' : 'text-muted-foreground hover:bg-accent hover:text-foreground');
+      return html`<a href=${href} aria-current=${on ? 'page' : 'false'} class=${cls}>${title}</a>`;
+    };
+    return html`
+      <a href="/" class="block px-3 py-1.5 -mx-2 mb-4 rounded-lg no-underline text-sm text-muted-foreground hover:text-foreground transition-colors">&larr; All demos</a>
+      ${FEATURE_GROUPS.map((g) => html`
+        <div class="mb-5">
+          <div class="px-3 mb-1.5 text-[11px] font-semibold uppercase tracking-wider text-muted-foreground/60">${g.label}</div>
+          <nav class="flex flex-col gap-0.5">${g.items.map((i) => link(i.href, i.title))}</nav>
+        </div>
+      `)}
+    `;
+  }
+}
+GalleryNav.register('gallery-nav');
diff --git a/packages/cli/templates/gallery/modules/gallery/nav.ts b/packages/cli/templates/gallery/modules/gallery/nav.ts
new file mode 100644
index 000000000..02dda71ca
--- /dev/null
+++ b/packages/cli/templates/gallery/modules/gallery/nav.ts
@@ -0,0 +1,79 @@
+/**
+ * The gallery's demo index, ONE source of truth for both the home cards and the
+ * left sidebar (so they can never drift). A browser-safe data module (no server
+ * imports, no client globals): the home flattens the groups into its card grid,
+ * and <gallery-nav> renders them grouped. gallery:clear removes this module.
+ */
+export interface NavItem { href: string; title: string; blurb: string; }
+export interface NavGroup { label: string; items: NavItem[]; }
+
+export const FEATURE_GROUPS: NavGroup[] = [
+  {
+    label: 'Routing',
+    items: [
+      { href: '/features/routing', title: 'Routing', blurb: 'A static route plus a dynamic [id] segment that reads params. The file-based router in miniature.' },
+      { href: '/features/boundaries', title: 'Boundaries', blurb: 'The control-flow throws (forbidden / unauthorized / notFound) and the nearest boundary file that catches each.' },
+      { href: '/features/metadata', title: 'Metadata', blurb: 'Static metadata plus generateMetadata(ctx), which reads the request to compute the title and Open Graph tags.' },
+    ],
+  },
+  {
+    label: 'Components',
+    items: [
+      { href: '/features/components', title: 'Components', blurb: 'The WebComponent factory, reactive props, instance signals, and slot projection in light DOM.' },
+      { href: '/features/directives', title: 'Directives', blurb: 'The lit-html directive set: repeat for keyed lists, watch(signal) for a fine-grained node swap.' },
+      { href: '/features/async-render', title: 'Async render', blurb: 'A component that awaits server data in async render(), so the resolved value is in the first paint.' },
+    ],
+  },
+  {
+    label: 'Data & actions',
+    items: [
+      { href: '/features/server-actions', title: 'Server actions', blurb: 'A use-server RPC action next to a server-only .server.ts utility, and why the boundary matters.' },
+      { href: '/features/route-handler', title: 'Route handlers', blurb: 'A server-only route.ts HTTP endpoint returning JSON, the WebJs equivalent of a Next route handler.' },
+      { href: '/features/forms', title: 'Forms', blurb: 'A no-JS progressive-enhancement form posting to the page action, with server-side validation errors.' },
+      { href: '/features/optimistic-ui', title: 'Optimistic UI', blurb: 'The imperative optimistic(signal, value, action) flip: instant update, automatic rollback on failure.' },
+    ],
+  },
+  {
+    label: 'Client & streaming',
+    items: [
+      { href: '/features/client-router', title: 'Client router', blurb: 'Automatic soft navigation: fragment-only fetches, hover prefetch, scroll restore, and graceful no-JS fallback.' },
+      { href: '/features/view-transitions', title: 'View transitions', blurb: 'The opt-in view-transition meta cross-fades a soft navigation, with a data-webjs-permanent element persisted across the swap.' },
+      { href: '/features/streaming', title: 'Streaming actions', blurb: 'A use-server action that returns an async generator, streamed to the call site token by token with for await.' },
+      { href: '/features/stream', title: 'Stream updates', blurb: 'The <webjs-stream> element: renderStream() applies surgical append / replace / remove DOM updates by target id, no region redraw.' },
+      { href: '/features/suspense', title: 'Suspense boundary', blurb: 'The <webjs-suspense> element: a first-paint fallback for a SLOW component, with the resolved content streamed in.' },
+      { href: '/features/frames', title: 'Frames', blurb: 'A webjs-frame region that swaps a filtered sub-list in place from a link, shipping zero component JS, with a no-JS full-nav fallback.' },
+    ],
+  },
+  {
+    label: 'Real-time',
+    items: [
+      { href: '/features/websockets', title: 'WebSockets', blurb: 'A WS(ws, req) route endpoint plus the connectWS() client, echoing messages over a live socket.' },
+      { href: '/features/broadcast', title: 'Broadcast', blurb: 'Fan a message out to every connected client on a WebSocket path, so all open tabs stay in sync.' },
+    ],
+  },
+  {
+    label: 'Auth & sessions',
+    items: [
+      { href: '/features/auth', title: 'Auth', blurb: 'Password login on createAuth, a signed session cookie, and a real protected route that redirects anonymous visitors to login.' },
+      { href: '/features/sessions', title: 'Sessions', blurb: 'A signed-cookie session applied by a segment middleware, read and written per visitor with getSession() in a route.' },
+    ],
+  },
+  {
+    label: 'Built-ins',
+    items: [
+      { href: '/features/caching', title: 'Caching', blurb: 'export const revalidate caches the page HTML per URL, with the safety rule for when a shared cache is allowed.' },
+      { href: '/features/env', title: 'Env vars', blurb: 'The server-only vs WEBJS_PUBLIC_ boundary, read during SSR so secrets never reach the browser.' },
+      { href: '/features/rate-limit', title: 'Rate limiting', blurb: 'The rateLimit() middleware scoped to one endpoint, returning a 429 with Retry-After past the window.' },
+      { href: '/features/file-storage', title: 'File storage', blurb: 'A no-JS multipart upload streamed into the FileStore, then served back through a streaming route.' },
+      { href: '/features/service-worker', title: 'Service worker', blurb: 'The opt-in offline enhancement, registered from a browser-only lifecycle hook (never a page or layout).' },
+    ],
+  },
+];
+
+/** The whole example apps (composed features), shown after the single-feature demos. */
+export const EXAMPLES: NavItem[] = [
+  { href: '/examples/todo', title: 'Optimistic todo', blurb: 'A whole app composing several features: the declarative optimistic() list API, progressive-enhancement forms, accessible labels, the modules split, and SQLite.' },
+];
+
+/** Flattened single-feature list (for the home card grid). */
+export const FEATURES: NavItem[] = FEATURE_GROUPS.flatMap((g) => g.items);
diff --git a/packages/cli/templates/scripts/clear-gallery.mjs b/packages/cli/templates/scripts/clear-gallery.mjs
index 5a3fc98a6..de2611cb9 100644
--- a/packages/cli/templates/scripts/clear-gallery.mjs
+++ b/packages/cli/templates/scripts/clear-gallery.mjs
@@ -76,7 +76,7 @@ const galleryPaths = [
 // query), pruned with the rest of the card.
 const galleryModules = [
   'async-render', 'auth', 'broadcast', 'caching', 'client-router', 'components',
-  'directives', 'file-storage', 'frames', 'optimistic-ui', 'rate-limit',
+  'directives', 'file-storage', 'frames', 'gallery', 'optimistic-ui', 'rate-limit',
   'route-handler', 'server-actions', 'sessions', 'stream', 'streaming', 'suspense',
   'todo', 'websockets',
 ].map((m) => `modules/${m}`);

From 586f3fd6833f140f06df2269f9940cfd8e2e9c2b Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 16:05:53 +0530
Subject: [PATCH 30/73] chore(scaffold): enforce gallery:clear parity + center
 the example app

Enforce clear-parity so it is not a manual reminder each time the gallery grows:
the clear tests now assert a TRUE blank slate (full-stack: modules/ + components/
EMPTY after clear; api: modules/ holds only the users base), so a new gallery
artifact left out of the clear script fails CI. The webjs-scaffold-sync skill now
mandates updating the matching clear script (clear-gallery.mjs / clear-api-gallery.mjs)
for BOTH templates on any gallery change. Sync the tests to the shared nav index
(the feature list moved to modules/gallery/nav.ts). Center the example app in a
focused max-w-xl column (it has no sidebar to fill the width). 46 scaffold tests green.
---
 .claude/skills/webjs-scaffold-sync/SKILL.md   | 24 ++++++++++++-----
 .../templates/gallery/app/examples/layout.ts  |  8 ++++--
 test/scaffolds/scaffold-gallery.test.js       | 26 ++++++++++++++++---
 test/scaffolds/scaffold-integration.test.js   |  3 +--
 4 files changed, 46 insertions(+), 15 deletions(-)

diff --git a/.claude/skills/webjs-scaffold-sync/SKILL.md b/.claude/skills/webjs-scaffold-sync/SKILL.md
index 57f5d46d3..64505c666 100644
--- a/.claude/skills/webjs-scaffold-sync/SKILL.md
+++ b/.claude/skills/webjs-scaffold-sync/SKILL.md
@@ -114,12 +114,21 @@ it applies, then update or consciously skip each.
    - `packages/cli/lib/api-gallery.js` (the api backend-features showcase). Auth
      is a full-stack GALLERY card now (`templates/gallery/{app/features/auth,
      modules/auth}`), pruned by `gallery:clear`, not a separate template.
-   - `packages/cli/templates/scripts/clear-gallery.mjs` (the `gallery:clear`
-     reset). It strips the app to a barebones blank slate (the gallery, the
-     example design system `components/ui/`, the example theme-toggle + its
-     layout wiring, the example tests, empty leftover dirs), keeping only the
-     buildable base + the skill. A NEW gallery route/module/example-artifact must
-     be added to its removal list, or `gallery:clear` will leave it behind.
+   - **The `gallery:clear` reset scripts (BOTH templates, MANDATORY parity).**
+     `packages/cli/templates/scripts/clear-gallery.mjs` (full-stack) strips the
+     app to a barebones blank slate (the gallery routes + modules, the example
+     design system `components/ui/`, `lib/utils/ui.ts`, the example theme-toggle +
+     its layout wiring, the example tests, empty leftover dirs), keeping only the
+     buildable base + the skill. `packages/cli/templates/scripts/clear-api-gallery.mjs`
+     (the `api` template) does the same for the backend showcase (`app/api/features`,
+     the demo modules, `env.ts`, the widgets test), keeping the health + users base.
+     **RULE: any NEW gallery artifact (a route, a module, a shared component, a lib
+     helper, a schema table) MUST be added to the matching clear script's removal
+     list in the SAME change, or `gallery:clear` leaves it behind and the app is not
+     a blank slate.** This is enforced by `test/scaffolds/scaffold-gallery.test.js`
+     (full-stack: asserts `modules/` and `components/` are EMPTY after clear, so a
+     forgotten module/component fails) and the api clear test in the same file; run
+     them after any gallery change.
    - Any future `*-template.js` / `*-gallery.js` split out for escaping sanity.
 3. **The verbatim template files** copied into every app:
    - `packages/cli/templates/gallery/**` (the UI feature gallery + example app,
@@ -156,7 +165,8 @@ it applies, then update or consciously skip each.
 | Change | Surfaces that MUST be checked |
 |---|---|
 | New / changed **WebJs feature, export, idiom, or convention** an agent must know | **the agent skill** `.agents/skills/webjs/` FIRST (SKILL.md routing line + the right `references/*.md`), the DURABLE teacher that survives `gallery:clear`, THEN a gallery demo (surface 2/3). Skill-without-demo means no runnable example; demo-without-skill means the pattern is LOST the moment an agent clears the gallery. A feature needs BOTH. |
-| New / changed **gallery or showcase demo** | the template file(s) or generator strings for the demo + the home-page `features`/index array + the scaffold AGENTS.md gallery list + the `gallery:clear` removal list (`templates/scripts/clear-gallery.mjs`, so the new demo/module is stripped to a blank slate) + `test/scaffolds/*` FEATURES/assertions + **generate + boot the affected template** |
+| New / changed **gallery or showcase demo** | the template file(s) or generator strings for the demo + the home-page `features`/index array + the scaffold AGENTS.md gallery list + **the matching `gallery:clear` removal list** (`clear-gallery.mjs` for full-stack, `clear-api-gallery.mjs` for api, so the new demo/module/component/lib artifact is stripped to a blank slate) + `test/scaffolds/*` FEATURES/assertions + **generate + boot the affected template + run `gallery:clear` and confirm a blank slate** |
+| **Removed / renamed gallery artifact** (a demo route, a module, a shared component, a lib helper, a schema table the gallery added) | the matching `gallery:clear` script's removal list (add the new path; remove a stale one) + the blank-slate clear test (`test/scaffolds/scaffold-gallery.test.js`) + **generate + run the clear + assert nothing gallery remains** |
 | New / removed **template** | the `create.js` template branch (+ a `*-template.js` if large) + the "only N templates exist" list in EVERY per-agent rule file + the framework `AGENTS.md`/getting-started/README template matrix + the CLI `--template` validation + `--help` + `test/scaffolds/*` |
 | New **control-flow throw or routing boundary file** (`notFound` / `redirect` / `forbidden` / `unauthorized` and their `not-found` / `forbidden` / `unauthorized` / `error` / `loading` / `global-error` / `global-not-found` boundary files) | a runnable **gallery demo** that exercises it (a route that throws it plus the nearest boundary file), NOT just an app-tree bullet in the rule files + the home-page `features` array + `test/scaffolds/*` FEATURES/boundary-file asserts + **generate + boot + hit the route**. A doc bullet in `AGENTS.md` / `CONVENTIONS.md` is necessary but NOT sufficient: the gallery is the primary teaching surface, so an undemoed thrower is invisible to a scaffolding agent (the #848 gap). Carve-out: a **root-only** boundary (`global-error` / `global-not-found`) cannot mount under `app/features/` without clashing with the generated app root, so teach those in the demo's PROSE rather than as a live route. |
 | New / renamed **public `@webjsdev/core` or `@webjsdev/server` export, or a new routing convention file** the router parses | `test/scaffolds/gallery-coverage.json` MUST classify it (a `{ demo }` / `{ demoed: true }`, or `{ exempt }` with an `internal:` / `deferred:` reason) or the tier-2 CI gate (`gallery-coverage.test.js`) FAILS. Prefer a real demo; `deferred:` is a conscious, reviewer-visible exemption tracked for later. This is the coverage-gate teeth described above. |
diff --git a/packages/cli/templates/gallery/app/examples/layout.ts b/packages/cli/templates/gallery/app/examples/layout.ts
index 354370030..b14f294a3 100644
--- a/packages/cli/templates/gallery/app/examples/layout.ts
+++ b/packages/cli/templates/gallery/app/examples/layout.ts
@@ -5,8 +5,12 @@ import { backLink } from '#lib/utils/ui.ts';
 // slim "back to the gallery" link the feature demos get, so an example is never a
 // dead end. A non-root layout, so it never writes the document shell.
 export default function ExamplesLayout({ children }: { children: unknown }) {
+  // An example app has no sidebar, so center it in a focused reading column
+  // (the root centers the whole page; this narrows the example within it).
   return html`
-    ${backLink('/', html`&larr; Gallery`)}
-    ${children}
+    <div class="max-w-xl mx-auto">
+      <div class="mb-6">${backLink('/', html`&larr; Gallery`)}</div>
+      ${children}
+    </div>
   `;
 }
diff --git a/test/scaffolds/scaffold-gallery.test.js b/test/scaffolds/scaffold-gallery.test.js
index c7a9bba60..38254ce80 100644
--- a/test/scaffolds/scaffold-gallery.test.js
+++ b/test/scaffolds/scaffold-gallery.test.js
@@ -17,7 +17,7 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { mkdtemp, rm, readFile, stat } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
+import { existsSync, readdirSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
@@ -98,18 +98,23 @@ test('full-stack scaffold ships feature demos and one example app', async () =>
   }
 });
 
-test('full-stack home page links every feature and the example app', async () => {
+test('the shared gallery nav lists every feature and the example app', async () => {
+  // The feature index moved to modules/gallery/nav.ts (one source for the home
+  // cards AND the sidebar). Assert every demo is listed there, and that the home
+  // reads it rather than hard-coding its own list.
   const cwd = await tempCwd();
   try {
     await scaffoldApp('demo', cwd, { template: 'full-stack' });
+    const nav = await readFile(join(cwd, 'demo', 'modules', 'gallery', 'nav.ts'), 'utf8');
     const home = await readFile(join(cwd, 'demo', 'app', 'page.ts'), 'utf8');
 
     assert.doesNotMatch(home, /webjs-scaffold-placeholder/, 'the placeholder gate was retired');
+    assert.match(home, /from '#modules\/gallery\/nav\.ts'/, 'home reads the shared nav index');
     for (const name of FEATURES) {
-      assert.match(home, new RegExp(`/features/${name}`), `home links /features/${name}`);
+      assert.match(nav, new RegExp(`/features/${name}`), `nav lists /features/${name}`);
     }
     for (const name of EXAMPLE_APPS) {
-      assert.match(home, new RegExp(`/examples/${name}`), `home links /examples/${name}`);
+      assert.match(nav, new RegExp(`/examples/${name}`), `nav lists /examples/${name}`);
     }
   } finally {
     await rm(cwd, { recursive: true, force: true });
@@ -206,6 +211,14 @@ test('full-stack gallery:clear strips the app to a barebones blank slate', async
     assert.ok(has('db', 'connection.server.ts'), 'db wiring kept');
     assert.ok(has('components'), 'components/ kept as an (empty) build target');
     assert.ok(has('modules'), 'modules/ kept as an (empty) build target');
+    // ENFORCEMENT (so a new gallery demo can't be added without updating
+    // gallery:clear): after clear, modules/ and components/ MUST be a blank
+    // slate. A gallery module or ui helper left behind fails here. If you added
+    // gallery content, add its removal to templates/scripts/clear-gallery.mjs.
+    const modulesLeft = readdirSync(join(appDir, 'modules'));
+    assert.deepEqual(modulesLeft, [], `modules/ must be empty after clear, found: ${modulesLeft.join(', ')}`);
+    const componentsLeft = readdirSync(join(appDir, 'components'));
+    assert.deepEqual(componentsLeft, [], `components/ must be empty after clear, found: ${componentsLeft.join(', ')}`);
     assert.ok(has('app', 'layout.ts'), 'root layout kept');
 
     // The layout no longer references the removed theme-toggle, but keeps its
@@ -310,6 +323,11 @@ test('the api gallery:clear sheds the showcase to a health + users base', async
     assert.ok(await exists(join(appDir, 'app', 'api', 'health', 'route.ts')), 'health endpoint kept');
     assert.ok(await exists(join(appDir, 'app', 'api', 'users', 'route.ts')), 'users endpoint kept');
     assert.ok(await exists(join(appDir, 'modules', 'users')), 'modules/users kept');
+    // ENFORCEMENT (parity with the full-stack clear test): after clear, modules/
+    // holds ONLY the users base. A new api demo module left behind fails here, so
+    // clear-api-gallery.mjs must be updated whenever the api showcase gains one.
+    assert.deepEqual(readdirSync(join(appDir, 'modules')).sort(), ['users'],
+      'modules/ must hold only the users base after the api clear');
 
     // A rerun is a safe no-op (the showcase is already gone).
     execFileSync(process.execPath, ['scripts/clear-api-gallery.mjs'], { cwd: appDir, stdio: 'ignore' });
diff --git a/test/scaffolds/scaffold-integration.test.js b/test/scaffolds/scaffold-integration.test.js
index 0ed649881..25a941752 100644
--- a/test/scaffolds/scaffold-integration.test.js
+++ b/test/scaffolds/scaffold-integration.test.js
@@ -134,8 +134,7 @@ test('scaffoldApp full-stack: writes the canonical full-stack app layout', async
     const pageSrc = readFileSync(join(appDir, 'app', 'page.ts'), 'utf8');
     assert.match(pageSrc, /Welcome to/, 'home is a welcome page');
     assert.match(pageSrc, /Explore the gallery/, 'home indexes the gallery');
-    assert.match(pageSrc, /\/features\/routing/, 'home links the feature demos');
-    assert.match(pageSrc, /\/examples\/todo/, 'home links the example app');
+    assert.match(pageSrc, /from '#modules\/gallery\/nav\.ts'/, 'home reads the shared gallery nav (the feature + example index)');
     assert.match(pageSrc, /docs\.webjs\.dev/, 'footer links the docs');
     assert.match(pageSrc, /github\.com\/webjsdev\/webjs/, 'footer links the source');
     assert.doesNotMatch(pageSrc, /<prompt-button\b/, 'the AI-prompts card is gone');

From ad06f4129124944b644a5b2bd0af62f979474557 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 16:15:46 +0530
Subject: [PATCH 31/73] fix(gallery): sidebar back link reads Gallery, drop the
 horizontal scroll

Rename the sidebar's top link 'All demos' -> 'Gallery' (matches the mobile back
link). Remove the -mx-2 from the nav links: it pushed them 8px past the column,
and overflow-y-auto makes overflow-x compute to auto, so it induced a horizontal
scrollbar. Add overflow-x-hidden on the aside as a guard. Verified in-browser:
no horizontal scroll (scrollWidth == clientWidth), link reads Gallery.
---
 packages/cli/templates/gallery/app/features/layout.ts         | 2 +-
 .../gallery/modules/gallery/components/gallery-nav.ts         | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/cli/templates/gallery/app/features/layout.ts b/packages/cli/templates/gallery/app/features/layout.ts
index be070eda8..3968aaa97 100644
--- a/packages/cli/templates/gallery/app/features/layout.ts
+++ b/packages/cli/templates/gallery/app/features/layout.ts
@@ -13,7 +13,7 @@ export default function FeaturesLayout({ children, url }: { children: unknown; u
   return html`
     <div class="lg:hidden mb-6">${backLink('/', html`&larr; Gallery`)}</div>
     <div class="grid lg:grid-cols-[190px_1fr] gap-8 lg:gap-12">
-      <aside class="hidden lg:block sticky top-6 self-start max-h-[calc(100dvh-4rem)] overflow-y-auto py-1 text-sm">
+      <aside class="hidden lg:block sticky top-6 self-start max-h-[calc(100dvh-4rem)] overflow-y-auto overflow-x-hidden py-1 text-sm">
         <gallery-nav current=${path}></gallery-nav>
       </aside>
       <div class="min-w-0">${children}</div>
diff --git a/packages/cli/templates/gallery/modules/gallery/components/gallery-nav.ts b/packages/cli/templates/gallery/modules/gallery/components/gallery-nav.ts
index 2309c8103..da061e8b0 100644
--- a/packages/cli/templates/gallery/modules/gallery/components/gallery-nav.ts
+++ b/packages/cli/templates/gallery/modules/gallery/components/gallery-nav.ts
@@ -34,12 +34,12 @@ export class GalleryNav extends WebComponent({ current: prop(String) }) {
     const active = activePath.get() || this.current;
     const link = (href: string, title: string) => {
       const on = active === href;
-      const cls = 'block px-3 py-1.5 -mx-2 rounded-lg no-underline transition-colors ' +
+      const cls = 'block px-3 py-1.5 rounded-lg no-underline transition-colors ' +
         (on ? 'bg-accent text-foreground font-medium' : 'text-muted-foreground hover:bg-accent hover:text-foreground');
       return html`<a href=${href} aria-current=${on ? 'page' : 'false'} class=${cls}>${title}</a>`;
     };
     return html`
-      <a href="/" class="block px-3 py-1.5 -mx-2 mb-4 rounded-lg no-underline text-sm text-muted-foreground hover:text-foreground transition-colors">&larr; All demos</a>
+      <a href="/" class="block px-3 py-1.5 mb-4 rounded-lg no-underline text-sm text-muted-foreground hover:text-foreground transition-colors">&larr; Gallery</a>
       ${FEATURE_GROUPS.map((g) => html`
         <div class="mb-5">
           <div class="px-3 mb-1.5 text-[11px] font-semibold uppercase tracking-wider text-muted-foreground/60">${g.label}</div>

From bac5f03cfc93a8a098457ffe332888e36dbb18e1 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 16:20:07 +0530
Subject: [PATCH 32/73] fix(gallery): highlight parent demo on subroutes + stop
 tab reflow

Sidebar: highlight a demo's menu item on its SUBROUTES too (/features/auth/dashboard
and /features/routing/42 now highlight Auth / Routing), via a startsWith(href + '/')
match (the trailing slash keeps /stream from matching /streaming).

Tab reflow: the Directives Tab A/B and the Frames filter tabs toggled between the
default and secondary variants, which differ in font-weight AND border, so the
active tab resized and the content below danced. Keep ONE variant (constant box)
and override only the active COLORS with cn(). Verified in-browser: tab width
constant across toggle, subroutes highlight correctly, check + typecheck pass.
---
 .../templates/gallery/app/features/frames/page.ts  | 14 ++++++++++----
 .../directives/components/directive-demo.ts        |  9 +++++++--
 .../modules/gallery/components/gallery-nav.ts      |  5 ++++-
 3 files changed, 21 insertions(+), 7 deletions(-)

diff --git a/packages/cli/templates/gallery/app/features/frames/page.ts b/packages/cli/templates/gallery/app/features/frames/page.ts
index 79f9b99c9..10a4ba16e 100644
--- a/packages/cli/templates/gallery/app/features/frames/page.ts
+++ b/packages/cli/templates/gallery/app/features/frames/page.ts
@@ -21,6 +21,8 @@
 // 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';
@@ -32,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>`;
 }
 
diff --git a/packages/cli/templates/gallery/modules/directives/components/directive-demo.ts b/packages/cli/templates/gallery/modules/directives/components/directive-demo.ts
index 9f7f0dbe5..8fe842b93 100644
--- a/packages/cli/templates/gallery/modules/directives/components/directive-demo.ts
+++ b/packages/cli/templates/gallery/modules/directives/components/directive-demo.ts
@@ -13,6 +13,7 @@
 // iterable, appending each or replacing with the latest).
 import { WebComponent, signal, html } from '@webjsdev/core';
 import { buttonClass } from '#components/ui/button.ts';
+import { cn } from '#lib/utils/cn.ts';
 import { inputClass } from '#components/ui/input.ts';
 import { repeat, watch, live, until, keyed, unsafeHTML, ref, createRef, guard, cache, templateContent, asyncAppend, asyncReplace } from '@webjsdev/core/directives';
 
@@ -159,11 +160,15 @@ export class DirectiveDemo extends WebComponent {
 
           <!-- cache(value) keeps the inactive tab's DOM alive while you toggle,
                so switching back is instant and preserves any element state. -->
+          <!-- A tab toggle must keep a CONSTANT size between states, or the row
+               reflows and the content below dances. So both tabs use ONE variant
+               (same weight, border, padding) and cn() overrides only the active
+               COLORS, never the box. -->
           <div class="flex gap-2">
             <button @click=${() => this.tab.set('a')}
-              class=${buttonClass({ variant: this.tab.get() === 'a' ? 'default' : 'secondary', size: 'xs' })}>Tab A</button>
+              class=${cn(buttonClass({ variant: 'secondary', size: 'xs' }), this.tab.get() === 'a' && 'bg-primary text-primary-foreground border-primary hover:border-primary')}>Tab A</button>
             <button @click=${() => this.tab.set('b')}
-              class=${buttonClass({ variant: this.tab.get() === 'b' ? 'default' : 'secondary', size: 'xs' })}>Tab B</button>
+              class=${cn(buttonClass({ variant: 'secondary', size: 'xs' }), this.tab.get() === 'b' && 'bg-primary text-primary-foreground border-primary hover:border-primary')}>Tab B</button>
           </div>
           <div class="text-[15px] text-foreground">${cache(
             this.tab.get() === 'a'
diff --git a/packages/cli/templates/gallery/modules/gallery/components/gallery-nav.ts b/packages/cli/templates/gallery/modules/gallery/components/gallery-nav.ts
index da061e8b0..ec1422e8b 100644
--- a/packages/cli/templates/gallery/modules/gallery/components/gallery-nav.ts
+++ b/packages/cli/templates/gallery/modules/gallery/components/gallery-nav.ts
@@ -33,7 +33,10 @@ export class GalleryNav extends WebComponent({ current: prop(String) }) {
     // activePath is '' at SSR (and before hydrate), so fall back to the prop.
     const active = activePath.get() || this.current;
     const link = (href: string, title: string) => {
-      const on = active === href;
+      // Highlight the demo whose route we are on, INCLUDING its subroutes
+      // (/features/auth/dashboard highlights Auth). The trailing slash keeps
+      // /features/stream from matching /features/streaming.
+      const on = active === href || active.startsWith(href + '/');
       const cls = 'block px-3 py-1.5 rounded-lg no-underline transition-colors ' +
         (on ? 'bg-accent text-foreground font-medium' : 'text-muted-foreground hover:bg-accent hover:text-foreground');
       return html`<a href=${href} aria-current=${on ? 'page' : 'false'} class=${cls}>${title}</a>`;

From 21bcd927559f07980bca30e9cc793f5afb2f17fb Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 16:26:47 +0530
Subject: [PATCH 33/73] fix(gallery): rename stream-demo append/prepend
 (native-method shadowing)

append() and prepend() are native ParentNode methods, and WebJs instruments them
on every light-DOM host for the slot API (#1021), so the component's same-named
methods were shadowed: clicking Append/Prepend called the slot-append (a no-op),
not renderStream. Rename to appendRow()/prependRow(). Verified in-browser: both
add rows again. (A comment warns future readers; a check-rule follow-up could
flag append/prepend the way it flags remove/title.)
---
 .../gallery/modules/stream/components/stream-demo.ts | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/packages/cli/templates/gallery/modules/stream/components/stream-demo.ts b/packages/cli/templates/gallery/modules/stream/components/stream-demo.ts
index 63a471e92..fca370a52 100644
--- a/packages/cli/templates/gallery/modules/stream/components/stream-demo.ts
+++ b/packages/cli/templates/gallery/modules/stream/components/stream-demo.ts
@@ -31,11 +31,15 @@ export class StreamDemo extends WebComponent {
   // component and blow away the streamed-in rows.
   #n = 2;
 
-  append() {
+  // NOTE the method names: NOT append() / prepend(). Those are native
+  // ParentNode methods, and WebJs instruments them on every light-DOM host for
+  // the slot API (#1021), so a component method of the same name is shadowed and
+  // never runs. Name your handlers something else (see muscle-memory-gotchas).
+  appendRow() {
     this.#n++;
     renderStream(streamPayload('append', 'stream-list', row(`row-${this.#n}`, `Row ${this.#n} (appended)`)));
   }
-  prepend() {
+  prependRow() {
     this.#n++;
     renderStream(streamPayload('prepend', 'stream-list', row(`row-${this.#n}`, `Row ${this.#n} (prepended)`)));
   }
@@ -58,8 +62,8 @@ export class StreamDemo extends WebComponent {
     return html`
       <div class="grid gap-4 max-w-[460px]">
         <div class="flex flex-wrap gap-2">
-          <button class=${btn} @click=${() => this.append()}>Append</button>
-          <button class=${btn} @click=${() => this.prepend()}>Prepend</button>
+          <button class=${btn} @click=${() => this.appendRow()}>Append</button>
+          <button class=${btn} @click=${() => this.prependRow()}>Prepend</button>
           <button class=${btn} @click=${() => this.replaceFirst()}>Replace Row 1</button>
           <button class=${btn} @click=${() => this.removeSecond()}>Remove Row 2</button>
           <button class=${btn} @click=${() => this.reset()}>Reset</button>

From 50d1b2da03ed0f39142c572801728a8faf37dd4d Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 16:26:47 +0530
Subject: [PATCH 34/73] feat(gallery): redirect a signed-in visitor away from
 login/signup

A per-segment middleware.ts (the mirror of the dashboard's protect gate) reads
auth(req) and 302s an already-signed-in visitor to the dashboard, so /login and
/signup are not shown to logged-in users. Keeps auth.server.ts off the client
(the check lives in middleware, not the page). Verified: signed-in visit to
/features/auth/login lands on the dashboard.
---
 .../gallery/app/features/auth/login/middleware.ts | 15 +++++++++++++++
 .../app/features/auth/signup/middleware.ts        | 11 +++++++++++
 2 files changed, 26 insertions(+)
 create mode 100644 packages/cli/templates/gallery/app/features/auth/login/middleware.ts
 create mode 100644 packages/cli/templates/gallery/app/features/auth/signup/middleware.ts

diff --git a/packages/cli/templates/gallery/app/features/auth/login/middleware.ts b/packages/cli/templates/gallery/app/features/auth/login/middleware.ts
new file mode 100644
index 000000000..ca4f410b0
--- /dev/null
+++ b/packages/cli/templates/gallery/app/features/auth/login/middleware.ts
@@ -0,0 +1,15 @@
+import { auth } from '#modules/auth/auth.server.ts';
+
+// The mirror of the dashboard's protect-middleware: a visitor who is ALREADY
+// signed in has no reason to see the login form, so send them to the dashboard.
+// A per-segment middleware.ts reads the signed session off the request with
+// auth(req) (a cookie read, no DB), so the redirect happens before the page
+// renders. Keeping the check in middleware (not the page) keeps auth.server.ts
+// off the client.
+export default async function redirectIfSignedIn(req: Request, next: () => Promise<Response>) {
+  const session = await auth(req);
+  if (session?.user) {
+    return new Response(null, { status: 302, headers: { location: '/features/auth/dashboard' } });
+  }
+  return next();
+}
diff --git a/packages/cli/templates/gallery/app/features/auth/signup/middleware.ts b/packages/cli/templates/gallery/app/features/auth/signup/middleware.ts
new file mode 100644
index 000000000..35b4d9313
--- /dev/null
+++ b/packages/cli/templates/gallery/app/features/auth/signup/middleware.ts
@@ -0,0 +1,11 @@
+import { auth } from '#modules/auth/auth.server.ts';
+
+// Like the login middleware: an already-signed-in visitor has no reason to see
+// the signup form, so send them to the dashboard before the page renders.
+export default async function redirectIfSignedIn(req: Request, next: () => Promise<Response>) {
+  const session = await auth(req);
+  if (session?.user) {
+    return new Response(null, { status: 302, headers: { location: '/features/auth/dashboard' } });
+  }
+  return next();
+}

From 210e560dbaf33ee9e55dd8fb4de0e871ed22a089 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 16:28:29 +0530
Subject: [PATCH 35/73] fix(gallery): underline prose text links so they read
 as links

In the neutral palette text-primary resolves to near-white (the same as body
text), so a bare 'text-primary' inline link is invisible AS a link. Add
underline underline-offset-2 to every prose <a> (32 links across the demos, plus
the sessions count link), leaving the 2 non-anchor text-primary status spans and
the intentional no-underline nav links untouched. Verified: check + typecheck pass.
---
 .../templates/gallery/app/features/auth/login/page.ts  |  2 +-
 .../cli/templates/gallery/app/features/auth/page.ts    |  6 +++---
 .../templates/gallery/app/features/auth/signup/page.ts |  2 +-
 .../templates/gallery/app/features/boundaries/error.ts |  2 +-
 .../gallery/app/features/boundaries/gated/forbidden.ts |  2 +-
 .../gallery/app/features/boundaries/not-found.ts       |  2 +-
 .../templates/gallery/app/features/boundaries/page.ts  | 10 +++++-----
 .../app/features/boundaries/private/unauthorized.ts    |  2 +-
 .../cli/templates/gallery/app/features/forms/page.ts   |  2 +-
 .../templates/gallery/app/features/metadata/page.ts    |  6 +++---
 .../gallery/app/features/optimistic-ui/page.ts         |  2 +-
 .../templates/gallery/app/features/rate-limit/page.ts  |  2 +-
 .../gallery/app/features/route-handler/page.ts         |  2 +-
 .../gallery/app/features/routing/[id]/page.ts          |  6 +++---
 .../cli/templates/gallery/app/features/routing/page.ts |  8 ++++----
 .../gallery/app/features/server-actions/page.ts        |  4 ++--
 .../templates/gallery/app/features/sessions/page.ts    |  2 +-
 .../modules/server-actions/components/greeter.ts       |  2 +-
 18 files changed, 32 insertions(+), 32 deletions(-)

diff --git a/packages/cli/templates/gallery/app/features/auth/login/page.ts b/packages/cli/templates/gallery/app/features/auth/login/page.ts
index 91e1a21d3..b736f8847 100644
--- a/packages/cli/templates/gallery/app/features/auth/login/page.ts
+++ b/packages/cli/templates/gallery/app/features/auth/login/page.ts
@@ -37,7 +37,7 @@ export default function LoginPage({ searchParams }: { searchParams: { error?: st
         </div>
         <button type="submit" class="${buttonClass()} justify-self-start">Sign in</button>
       </form>
-      <p class="text-sm text-muted-foreground mt-4">Don't have an account? <a href="/features/auth/signup" class="text-primary">Sign up</a></p>
+      <p class="text-sm text-muted-foreground mt-4">Don't have an account? <a href="/features/auth/signup" class="text-primary underline underline-offset-2">Sign up</a></p>
     </div>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/auth/page.ts b/packages/cli/templates/gallery/app/features/auth/page.ts
index 9b0d61bb2..b0da14c2a 100644
--- a/packages/cli/templates/gallery/app/features/auth/page.ts
+++ b/packages/cli/templates/gallery/app/features/auth/page.ts
@@ -24,10 +24,10 @@ export default async function AuthExample() {
     ${user
       ? html`
         <p class="mb-4">Signed in as <strong>${user.name || user.email}</strong>.</p>
-        <p><a class="text-primary" href="/features/auth/dashboard">Open the protected dashboard</a></p>`
+        <p><a class="text-primary underline underline-offset-2" href="/features/auth/dashboard">Open the protected dashboard</a></p>`
       : html`
-        <p class="mb-4">You are signed out. <a class="text-primary" href="/features/auth/dashboard">Visiting the dashboard</a> bounces you to login.</p>
-        <p class="flex gap-4"><a class="text-primary" href="/features/auth/login">Log in</a><a class="text-primary" href="/features/auth/signup">Create an account</a></p>`}
+        <p class="mb-4">You are signed out. <a class="text-primary underline underline-offset-2" href="/features/auth/dashboard">Visiting the dashboard</a> bounces you to login.</p>
+        <p class="flex gap-4"><a class="text-primary underline underline-offset-2" href="/features/auth/login">Log in</a><a class="text-primary underline underline-offset-2" href="/features/auth/signup">Create an account</a></p>`}
 
     <p class="text-muted-foreground text-sm mt-6">The gate is <code class="font-mono">app/features/auth/dashboard/middleware.ts</code> calling <code class="font-mono">auth(req)</code>; the login form posts to the <code class="font-mono">app/api/auth/[...path]</code> handler; OAuth (GitHub / Google) activates once you set the matching env vars.</p>
   `;
diff --git a/packages/cli/templates/gallery/app/features/auth/signup/page.ts b/packages/cli/templates/gallery/app/features/auth/signup/page.ts
index 998c7c146..142a21199 100644
--- a/packages/cli/templates/gallery/app/features/auth/signup/page.ts
+++ b/packages/cli/templates/gallery/app/features/auth/signup/page.ts
@@ -55,7 +55,7 @@ export default function SignupPage({ actionData }: { actionData?: { fieldErrors?
         </div>
         <button type="submit" class="${buttonClass()} justify-self-start">Create account</button>
       </form>
-      <p class="text-sm text-muted-foreground mt-4">Already have an account? <a href="/features/auth/login" class="text-primary">Log in</a></p>
+      <p class="text-sm text-muted-foreground mt-4">Already have an account? <a href="/features/auth/login" class="text-primary underline underline-offset-2">Log in</a></p>
     </div>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/boundaries/error.ts b/packages/cli/templates/gallery/app/features/boundaries/error.ts
index e5d24136a..dbb86e45d 100644
--- a/packages/cli/templates/gallery/app/features/boundaries/error.ts
+++ b/packages/cli/templates/gallery/app/features/boundaries/error.ts
@@ -12,6 +12,6 @@ export default function BoundariesError({ error }: { error: Error }) {
       This segment's <code class="font-mono">error.ts</code> boundary caught a
       render error: <code class="font-mono">${error?.message ?? 'unknown'}</code>.
     `)}
-    <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>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/boundaries/gated/forbidden.ts b/packages/cli/templates/gallery/app/features/boundaries/gated/forbidden.ts
index c808723a6..34190586b 100644
--- a/packages/cli/templates/gallery/app/features/boundaries/gated/forbidden.ts
+++ b/packages/cli/templates/gallery/app/features/boundaries/gated/forbidden.ts
@@ -14,6 +14,6 @@ export default function Forbidden() {
       nearest <code class="font-mono">forbidden.ts</code> boundary, rendered
       because the page threw <code class="font-mono">forbidden()</code>.
     `)}
-    <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>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/boundaries/not-found.ts b/packages/cli/templates/gallery/app/features/boundaries/not-found.ts
index e35382984..4f7d3a436 100644
--- a/packages/cli/templates/gallery/app/features/boundaries/not-found.ts
+++ b/packages/cli/templates/gallery/app/features/boundaries/not-found.ts
@@ -13,6 +13,6 @@ export default function BoundariesNotFound() {
       because a page threw <code class="font-mono">notFound()</code> or the URL
       matched nothing under this segment.
     `)}
-    <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>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/boundaries/page.ts b/packages/cli/templates/gallery/app/features/boundaries/page.ts
index b802eea71..1aa2b3177 100644
--- a/packages/cli/templates/gallery/app/features/boundaries/page.ts
+++ b/packages/cli/templates/gallery/app/features/boundaries/page.ts
@@ -31,22 +31,22 @@ export default function BoundariesExample() {
     `)}
     <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>
@@ -72,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>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/boundaries/private/unauthorized.ts b/packages/cli/templates/gallery/app/features/boundaries/private/unauthorized.ts
index e277bcb24..f1e76cad6 100644
--- a/packages/cli/templates/gallery/app/features/boundaries/private/unauthorized.ts
+++ b/packages/cli/templates/gallery/app/features/boundaries/private/unauthorized.ts
@@ -13,6 +13,6 @@ export default function Unauthorized() {
       <code class="font-mono">unauthorized.ts</code> boundary, rendered because the
       page threw <code class="font-mono">unauthorized()</code>.
     `)}
-    <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>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/forms/page.ts b/packages/cli/templates/gallery/app/features/forms/page.ts
index 6e686d404..4e92083fa 100644
--- a/packages/cli/templates/gallery/app/features/forms/page.ts
+++ b/packages/cli/templates/gallery/app/features/forms/page.ts
@@ -40,7 +40,7 @@ export default function FormsFeature({ searchParams, actionData }: { searchParam
           <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>
     `;
   }
diff --git a/packages/cli/templates/gallery/app/features/metadata/page.ts b/packages/cli/templates/gallery/app/features/metadata/page.ts
index 7da9c21bd..c76148691 100644
--- a/packages/cli/templates/gallery/app/features/metadata/page.ts
+++ b/packages/cli/templates/gallery/app/features/metadata/page.ts
@@ -43,9 +43,9 @@ export default function MetadataExample({
       <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
diff --git a/packages/cli/templates/gallery/app/features/optimistic-ui/page.ts b/packages/cli/templates/gallery/app/features/optimistic-ui/page.ts
index 9eaa79b12..62eea2595 100644
--- a/packages/cli/templates/gallery/app/features/optimistic-ui/page.ts
+++ b/packages/cli/templates/gallery/app/features/optimistic-ui/page.ts
@@ -8,7 +8,7 @@ export const metadata: Metadata = { title: 'Optimistic UI (imperative flip) | fe
 export default function OptimisticUiFeature() {
   return html`
     ${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" href="/examples/todo">/examples/todo</a>.`)}
+    ${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>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/rate-limit/page.ts b/packages/cli/templates/gallery/app/features/rate-limit/page.ts
index 7231d8e13..433c7f6fa 100644
--- a/packages/cli/templates/gallery/app/features/rate-limit/page.ts
+++ b/packages/cli/templates/gallery/app/features/rate-limit/page.ts
@@ -22,7 +22,7 @@ export default function RateLimitExample() {
     <rate-probe></rate-probe>
     <p class="text-muted-foreground text-sm mt-4">
       With JavaScript off, hit
-      <a class="text-primary" href="/features/rate-limit/ping" 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>
   `;
diff --git a/packages/cli/templates/gallery/app/features/route-handler/page.ts b/packages/cli/templates/gallery/app/features/route-handler/page.ts
index 4418c1dcd..5874edbfa 100644
--- a/packages/cli/templates/gallery/app/features/route-handler/page.ts
+++ b/packages/cli/templates/gallery/app/features/route-handler/page.ts
@@ -9,7 +9,7 @@ export default function RouteHandlerExample() {
   return html`
     ${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" 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>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>
   `;
diff --git a/packages/cli/templates/gallery/app/features/routing/[id]/page.ts b/packages/cli/templates/gallery/app/features/routing/[id]/page.ts
index 832b867b3..55119ab37 100644
--- a/packages/cli/templates/gallery/app/features/routing/[id]/page.ts
+++ b/packages/cli/templates/gallery/app/features/routing/[id]/page.ts
@@ -34,13 +34,13 @@ export default async function RoutingParam({ params }: PageProps<'/features/rout
       <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>
+      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>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/routing/page.ts b/packages/cli/templates/gallery/app/features/routing/page.ts
index 8ae988a04..64b4e9917 100644
--- a/packages/cli/templates/gallery/app/features/routing/page.ts
+++ b/packages/cli/templates/gallery/app/features/routing/page.ts
@@ -12,9 +12,9 @@ export default function RoutingExample() {
     ${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">
       Routes are type-safe: <code class="font-mono">webjs types</code> (run by
@@ -50,7 +50,7 @@ export default function RoutingExample() {
       <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>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/server-actions/page.ts b/packages/cli/templates/gallery/app/features/server-actions/page.ts
index f49ffde4a..2068970c1 100644
--- a/packages/cli/templates/gallery/app/features/server-actions/page.ts
+++ b/packages/cli/templates/gallery/app/features/server-actions/page.ts
@@ -12,13 +12,13 @@ export default function ServerActionsExample() {
     <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>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/sessions/page.ts b/packages/cli/templates/gallery/app/features/sessions/page.ts
index 01d239e5d..9814e6e18 100644
--- a/packages/cli/templates/gallery/app/features/sessions/page.ts
+++ b/packages/cli/templates/gallery/app/features/sessions/page.ts
@@ -13,7 +13,7 @@ export default function SessionsExample() {
   return html`
     ${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" 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>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 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>
   `;
 }
diff --git a/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts b/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts
index eb9fcfbb2..0d49e7b1e 100644
--- a/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts
+++ b/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts
@@ -29,7 +29,7 @@ export class Greeter extends WebComponent {
           <button type="submit"
             class="${buttonClass()} shrink-0">Greet</button>
         </form>
-        <p class="m-0 text-sm text-muted-foreground">The action is gated by requireAuth. <a class="text-primary" href="/features/auth/login">Sign in</a> to greet; signed out returns a real 401.</p>
+        <p class="m-0 text-sm text-muted-foreground">The action is gated by requireAuth. <a class="text-primary underline underline-offset-2" href="/features/auth/login">Sign in</a> to greet; signed out returns a real 401.</p>
         ${this.msg.get() ? html`<p class="m-0 font-semibold text-foreground">${this.msg.get()}</p>` : ''}
       </div>
     `;

From aca2ba042c95638b4cb3fc047a01085e8be78f71 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 16:34:07 +0530
Subject: [PATCH 36/73] fix(gallery): pin the sidebar back link above the
 scrolling demo list
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The '← Gallery' link sat inside the scrolling aside, so it scrolled away when the
nav overflowed. Make the aside a flex column: '← Gallery' is a shrink-0 pinned
header, and only the grouped demo list (a min-h-0 overflow-y-auto region wrapping
<gallery-nav>) scrolls. Verified in a short viewport: list scrolls, back link
stays put.
---
 packages/cli/templates/gallery/app/features/layout.ts     | 8 ++++++--
 .../gallery/modules/gallery/components/gallery-nav.ts     | 1 -
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/packages/cli/templates/gallery/app/features/layout.ts b/packages/cli/templates/gallery/app/features/layout.ts
index 3968aaa97..4a1446897 100644
--- a/packages/cli/templates/gallery/app/features/layout.ts
+++ b/packages/cli/templates/gallery/app/features/layout.ts
@@ -13,8 +13,12 @@ export default function FeaturesLayout({ children, url }: { children: unknown; u
   return html`
     <div class="lg:hidden mb-6">${backLink('/', html`&larr; Gallery`)}</div>
     <div class="grid lg:grid-cols-[190px_1fr] gap-8 lg:gap-12">
-      <aside class="hidden lg:block sticky top-6 self-start max-h-[calc(100dvh-4rem)] overflow-y-auto overflow-x-hidden py-1 text-sm">
-        <gallery-nav current=${path}></gallery-nav>
+      <aside class="hidden lg:flex lg:flex-col sticky top-6 self-start max-h-[calc(100dvh-3rem)] text-sm">
+        <!-- Pinned header: stays put while the demo list below scrolls. -->
+        <a href="/" class="shrink-0 block px-3 py-1.5 mb-2 rounded-lg no-underline text-muted-foreground hover:text-foreground transition-colors">&larr; Gallery</a>
+        <div class="min-h-0 overflow-y-auto overflow-x-hidden">
+          <gallery-nav current=${path}></gallery-nav>
+        </div>
       </aside>
       <div class="min-w-0">${children}</div>
     </div>
diff --git a/packages/cli/templates/gallery/modules/gallery/components/gallery-nav.ts b/packages/cli/templates/gallery/modules/gallery/components/gallery-nav.ts
index ec1422e8b..cf632ca77 100644
--- a/packages/cli/templates/gallery/modules/gallery/components/gallery-nav.ts
+++ b/packages/cli/templates/gallery/modules/gallery/components/gallery-nav.ts
@@ -42,7 +42,6 @@ export class GalleryNav extends WebComponent({ current: prop(String) }) {
       return html`<a href=${href} aria-current=${on ? 'page' : 'false'} class=${cls}>${title}</a>`;
     };
     return html`
-      <a href="/" class="block px-3 py-1.5 mb-4 rounded-lg no-underline text-sm text-muted-foreground hover:text-foreground transition-colors">&larr; Gallery</a>
       ${FEATURE_GROUPS.map((g) => html`
         <div class="mb-5">
           <div class="px-3 mb-1.5 text-[11px] font-semibold uppercase tracking-wider text-muted-foreground/60">${g.label}</div>

From 3c41ccef15ac82888216a26d23b67fb57c72e4a7 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 16:36:50 +0530
Subject: [PATCH 37/73] style(gallery): subtle auto-hiding sidebar scrollbar

Give the sidebar scroll region a thin, hover-revealed scrollbar (transparent
while idle, fades in on hover / focus-within, fades out again), the macOS overlay
feel, matching the ui docs site. A layout may interpolate CSS into a <style> (it
never hydrates), so the rule stays green. Verified: webjs check passes, CSS +
class served.
---
 .../templates/gallery/app/features/layout.ts    | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/packages/cli/templates/gallery/app/features/layout.ts b/packages/cli/templates/gallery/app/features/layout.ts
index 4a1446897..b056b0554 100644
--- a/packages/cli/templates/gallery/app/features/layout.ts
+++ b/packages/cli/templates/gallery/app/features/layout.ts
@@ -2,6 +2,20 @@ 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); }
+`;
+
 // 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
@@ -11,12 +25,13 @@ import '#modules/gallery/components/gallery-nav.ts';
 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}</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">
       <aside class="hidden lg:flex lg:flex-col sticky top-6 self-start max-h-[calc(100dvh-3rem)] text-sm">
         <!-- Pinned header: stays put while the demo list below scrolls. -->
         <a href="/" class="shrink-0 block px-3 py-1.5 mb-2 rounded-lg no-underline text-muted-foreground hover:text-foreground transition-colors">&larr; Gallery</a>
-        <div class="min-h-0 overflow-y-auto overflow-x-hidden">
+        <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>

From d7e71802fa8d1076011f7a184ee1ec93d6935d6d Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 16:40:39 +0530
Subject: [PATCH 38/73] feat(check): flag a component method shadowing a native
 DOM mutation method

Add the no-shadowed-native-member rule: a WebComponent method named after a
native ParentNode/ChildNode/Node mutation method WebJs instruments for the
light-DOM slot API (append/prepend/before/after/replaceWith/replaceChildren/
remove/appendChild/insertBefore/removeChild/replaceChild) is shadowed at runtime
and silently never runs, while TypeScript stays green (a shorter override is
assignable). This is the exact class the stream-demo bug fell into. Lifecycle
hooks are meant to be overridden and are not flagged. Test covers the positive
case, the renamed counterfactual, and Node-mutation members; teach it in
components.md. 147 check tests green, fresh scaffold passes.
---
 .agents/skills/webjs/references/components.md |  2 +-
 packages/server/src/check.js                  | 37 +++++++++
 .../check/no-shadowed-native-member.test.js   | 75 +++++++++++++++++++
 3 files changed, 113 insertions(+), 1 deletion(-)
 create mode 100644 packages/server/test/check/no-shadowed-native-member.test.js

diff --git a/.agents/skills/webjs/references/components.md b/.agents/skills/webjs/references/components.md
index c842fefe6..a97226e30 100644
--- a/.agents/skills/webjs/references/components.md
+++ b/.agents/skills/webjs/references/components.md
@@ -254,7 +254,7 @@ A bare `async render()` (no other signal, light DOM) is elided too: the SSR'd da
 
 ## Members app code must not shadow
 
-A `WebComponent` inherits `HTMLElement` (browser) or an `ElementShim` (SSR) plus the framework reactivity base. A reactive prop or method whose NAME collides either fails to compile (`TS2415` for a type-incompatible property, `TS2416` for a method signature) or silently hijacks the native member at runtime. The fix is always to rename.
+A `WebComponent` inherits `HTMLElement` (browser) or an `ElementShim` (SSR) plus the framework reactivity base. A reactive prop or method whose NAME collides either fails to compile (`TS2415` for a type-incompatible property, `TS2416` for a method signature) or silently hijacks the native member at runtime. The fix is always to rename. The DOM MUTATION methods WebJs instruments for the light-DOM slot API (`append`, `prepend`, `before`, `after`, `replaceWith`, `replaceChildren`, `remove`, `appendChild`, `insertBefore`, `removeChild`, `replaceChild`) are the dangerous case TypeScript does NOT catch (a shorter override is assignable to the native signature), so a handler named `append()` compiles yet silently never runs. `webjs check`'s `no-shadowed-native-member` rule catches exactly these.
 
 - HTMLElement / Element: `title`, `id`, `slot`, `role`, `hidden`, `dir`, `lang`, `translate`, `draggable`, `tabIndex`, `className`, `dataset`, `remove`, `closest`, `matches`, `focus`, `blur`, `click`, `append` / `prepend`, `before` / `after`. Rename (`postTitle`, `removeItem`, `handleClick`).
 - WebComponent base: `render`, `update`, `requestUpdate`, `updated` / `firstUpdated`, `willUpdate` / `shouldUpdate`, `connectedCallback`, `renderError` / `renderFallback`, `addController` / `removeController`, `updateComplete` (#1021: there is no WebJs slot API to override; slots are native). Only override one deliberately, with its exact signature; never repurpose the name for app logic.
diff --git a/packages/server/src/check.js b/packages/server/src/check.js
index d244eb265..53242ad8b 100644
--- a/packages/server/src/check.js
+++ b/packages/server/src/check.js
@@ -119,6 +119,11 @@ export const RULES = [
     description:
       'Flags genuinely browser-only APIs used in a WebComponent constructor, willUpdate, or render() method. The SSR pipeline instantiates the component, runs willUpdate plus controllers\' hostUpdate, reflects properties, and calls render() to produce HTML, on a server element shim that backs the attribute methods but has no real DOM. So a browser global (document, window, localStorage, sessionStorage, navigator, location, matchMedia, screen, history) or an unshimmed HTMLElement member on `this` (attachShadow, shadowRoot, classList, querySelector, querySelectorAll, getBoundingClientRect, focus, blur, scrollIntoView) touched there throws at SSR time (the isomorphic footgun). The attribute methods (getAttribute/setAttribute/hasAttribute/removeAttribute/toggleAttribute), the event methods (addEventListener/removeEventListener/dispatchEvent), and attachInternals are shim-backed and run server-side, so they are NOT flagged. The flagged APIs belong in connectedCallback() or a lifecycle hook (firstUpdated/updated), which SSR never calls; seed first-paint defaults in the constructor (or derive them in willUpdate) only from server-known inputs (attributes, props). Conservative: only the constructor, willUpdate, and render bodies are scanned, and only direct references, so helper indirection is not flagged (the runtime SSR error covers that case).',
   },
+  {
+    name: 'no-shadowed-native-member',
+    description:
+      'Flags a WebComponent class method whose name collides with a native DOM mutation method that WebJs relies on and INSTRUMENTS on every light-DOM host for the slot API (#1021): append, prepend, before, after, replaceWith, replaceChildren, remove, appendChild, insertBefore, removeChild, replaceChild. A method of the same name is SHADOWED at runtime (the instrumented native method wins), so the component method silently never runs, while TypeScript stays green because a zero/one-arg override is assignable to the native signature. Found dogfooding the stream demo (#248): a component named its button handler `append()`, so clicking Append called the slot-append no-op instead of the handler. Rename the handler to a non-native name (appendRow / prependRow / removeItem). The `render` / lifecycle hooks are MEANT to be overridden and are not flagged; only the native DOM mutation members are.',
+  },
   {
     name: 'no-server-import-in-browser-module',
     description:
@@ -659,6 +664,38 @@ export async function checkConventions(appDir) {
     }
   }
 
+  // --- Rule: no-shadowed-native-member ---
+  // A WebComponent method named after a native DOM mutation method WebJs
+  // instruments on every light-DOM host for the slot API (#1021) is SHADOWED at
+  // runtime (the native/instrumented method wins), so the component method never
+  // runs, while TypeScript stays green (a shorter override is assignable). Rename
+  // the handler. The lifecycle hooks are meant to be overridden, so only the DOM
+  // mutation members are reserved.
+  {
+    const NATIVE_MEMBERS = [
+      'append', 'prepend', 'before', 'after', 'replaceWith', 'replaceChildren', 'remove',
+      'appendChild', 'insertBefore', 'removeChild', 'replaceChild',
+    ];
+    for (const { rel, scan } of files) {
+      if (!/class\s+\w+\s+extends\s+WebComponent/.test(scan)) continue;
+      for (const { body } of extractWebComponentClassBodies(scan)) {
+        for (const name of NATIVE_MEMBERS) {
+          // Same method-definition shape methodBodyOf() matches (name followed by
+          // a param list then `{`), preceded by a class-body boundary.
+          const re = new RegExp(`(?:^|[\\s;}])(?:async\\s+)?${name}\\s*\\([^)]*\\)\\s*(?::[^{]*)?\\{`);
+          if (re.test(body)) {
+            violations.push({
+              rule: 'no-shadowed-native-member',
+              file: rel,
+              message: `Component method \`${name}()\` shadows the native DOM method WebJs instruments for the slot API, so it silently never runs (the native method wins) and TypeScript does not catch it.`,
+              fix: `Rename the method to a non-native name (e.g. \`${name}Row()\` / \`${name}Item()\`) and update its call sites.`,
+            });
+          }
+        }
+      }
+    }
+  }
+
   // --- Rule: no-redirect-in-api-route ---
   // `redirect()` from `@webjsdev/core` throws a control-flow signal designed
   // for the SSR page renderer. In a `route.ts` API handler it goes uncaught
diff --git a/packages/server/test/check/no-shadowed-native-member.test.js b/packages/server/test/check/no-shadowed-native-member.test.js
new file mode 100644
index 000000000..3d23850fa
--- /dev/null
+++ b/packages/server/test/check/no-shadowed-native-member.test.js
@@ -0,0 +1,75 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { checkConventions, RULES } from '../../src/check.js';
+
+/**
+ * Tests for `no-shadowed-native-member`: a WebComponent method named after a
+ * native DOM mutation method WebJs instruments for the light-DOM slot API (#1021)
+ * is shadowed at runtime and silently never runs, while TypeScript stays green.
+ * Found dogfooding the stream demo (a button handler named `append()`).
+ */
+const RULE = 'no-shadowed-native-member';
+
+async function makeApp(files) {
+  const dir = await mkdtemp(join(tmpdir(), 'webjs-shadow-native-'));
+  for (const [rel, contents] of Object.entries(files)) {
+    const abs = join(dir, rel);
+    await mkdir(abs.slice(0, abs.lastIndexOf('/')), { recursive: true });
+    await writeFile(abs, contents);
+  }
+  return dir;
+}
+const hits = (v) => v.filter((x) => x.rule === RULE);
+
+test('the rule is registered', () => {
+  assert.ok(RULES.some((r) => r.name === RULE), 'RULES lists no-shadowed-native-member');
+});
+
+test('flags a component method named after a native slot-instrumented method', async () => {
+  const dir = await makeApp({
+    'components/stream.ts': `import { WebComponent, html, renderStream } from '@webjsdev/core';
+class Stream extends WebComponent {
+  append() { renderStream('<webjs-stream action="append" target="l"></webjs-stream>'); }
+  prepend() { renderStream('x'); }
+  render() { return html\`<button @click=\${() => this.append()}>Add</button>\`; }
+}
+Stream.register('x-stream');`,
+  });
+  const v = hits(await checkConventions(dir));
+  const names = v.map((x) => x.message.match(/`(\w+)\(\)`/)[1]).sort();
+  assert.deepEqual(names, ['append', 'prepend'], 'flags both append and prepend');
+  assert.match(v[0].fix, /Rename/);
+});
+
+test('does NOT flag a renamed handler or the lifecycle hooks (counterfactual)', async () => {
+  const dir = await makeApp({
+    'components/stream.ts': `import { WebComponent, html, renderStream } from '@webjsdev/core';
+class Stream extends WebComponent {
+  appendRow() { renderStream('x'); }
+  prependRow() { renderStream('x'); }
+  connectedCallback() { super.connectedCallback(); }
+  render() { return html\`<button @click=\${() => this.appendRow()}>Add</button>\`; }
+}
+Stream.register('x-stream');`,
+  });
+  const v = hits(await checkConventions(dir));
+  assert.equal(v.length, 0, 'appendRow/prependRow/connectedCallback/render are fine');
+});
+
+test('flags the Node-mutation members too (removeChild / insertBefore)', async () => {
+  const dir = await makeApp({
+    'components/x.ts': `import { WebComponent, html } from '@webjsdev/core';
+class X extends WebComponent {
+  removeChild() {}
+  render() { return html\`<div></div>\`; }
+}
+X.register('x-x');`,
+  });
+  const v = hits(await checkConventions(dir));
+  assert.equal(v.length, 1);
+  assert.match(v[0].message, /removeChild/);
+});

From 62e65c8642f6a8e4c4708ce69a057a8ad700734d Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 16:58:31 +0530
Subject: [PATCH 39/73] fix(gallery): crisp light theme + theme-toggle on every
 page
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Light theme was washed out: a grey #dee2e6 page with #767b80 muted text (≈2.9:1,
below AA). Give it a white background, near-black foreground (#191c20), a readable
muted grey (#565c64, ≈6.4:1), a near-black primary, and visible borders, in both
the explicit-toggle and OS-preference blocks. Move the theme-toggle from the home
into the root layout so it shows on every page (home + the feature/sidebar pages),
and strip its render (not just its import) from the layout on gallery:clear.
Verified in-browser: muted text 565c64 at ~6.4:1, toggle present on feature pages,
check + typecheck + the clear blank-slate test pass.
---
 packages/cli/lib/create.js                    | 79 ++++++++++---------
 .../cli/templates/scripts/clear-gallery.mjs   |  4 +-
 2 files changed, 43 insertions(+), 40 deletions(-)

diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
index 7e3736b34..a2dc111fe 100644
--- a/packages/cli/lib/create.js
+++ b/packages/cli/lib/create.js
@@ -1218,50 +1218,52 @@ export default function RootLayout({ children }: { children: unknown }) {
         --input: #34393e;
         --ring: #6b7075;
       }
-      /* light (explicit via the toggle) */
+      /* light (explicit via the toggle). A crisp white page with near-black
+         text, a readable muted grey, and visible borders (a washed-out light
+         theme comes from a grey page + too-light muted text + faint borders). */
       :root[data-theme='light'] {
         color-scheme: light;
-        --background: #dee2e6;
-        --foreground: #313539;
-        --card: #f0f4f7;
-        --card-foreground: #313539;
-        --popover: #f0f4f7;
-        --popover-foreground: #313539;
-        --primary: #313539;
-        --primary-foreground: #f7fbff;
-        --secondary: #f7fbff;
-        --secondary-foreground: #313539;
-        --muted: #eaeef1;
-        --muted-foreground: #767b80;
-        --accent: #f7fbff;
-        --accent-foreground: #313539;
-        --border: #c9d0d6;
-        --border-strong: #b3bbc2;
-        --input: #c9d0d6;
-        --ring: #9aa0a5;
+        --background: #ffffff;
+        --foreground: #191c20;
+        --card: #f7f8fa;
+        --card-foreground: #191c20;
+        --popover: #ffffff;
+        --popover-foreground: #191c20;
+        --primary: #1e2226;
+        --primary-foreground: #ffffff;
+        --secondary: #eef0f2;
+        --secondary-foreground: #191c20;
+        --muted: #eef0f2;
+        --muted-foreground: #565c64;
+        --accent: #e9ebef;
+        --accent-foreground: #191c20;
+        --border: #e2e5e9;
+        --border-strong: #ccd1d7;
+        --input: #e2e5e9;
+        --ring: #8b9198;
       }
       /* light (OS preference, when the user has made no explicit choice) */
       @media (prefers-color-scheme: light) {
         :root:not(.dark):not([data-theme='dark']) {
           color-scheme: light;
-          --background: #dee2e6;
-          --foreground: #313539;
-          --card: #f0f4f7;
-          --card-foreground: #313539;
-          --popover: #f0f4f7;
-          --popover-foreground: #313539;
-          --primary: #313539;
-          --primary-foreground: #f7fbff;
-          --secondary: #f7fbff;
-          --secondary-foreground: #313539;
-          --muted: #eaeef1;
-          --muted-foreground: #767b80;
-          --accent: #f7fbff;
-          --accent-foreground: #313539;
-          --border: #c9d0d6;
-          --border-strong: #b3bbc2;
-          --input: #c9d0d6;
-          --ring: #9aa0a5;
+          --background: #ffffff;
+          --foreground: #191c20;
+          --card: #f7f8fa;
+          --card-foreground: #191c20;
+          --popover: #ffffff;
+          --popover-foreground: #191c20;
+          --primary: #1e2226;
+          --primary-foreground: #ffffff;
+          --secondary: #eef0f2;
+          --secondary-foreground: #191c20;
+          --muted: #eef0f2;
+          --muted-foreground: #565c64;
+          --accent: #e9ebef;
+          --accent-foreground: #191c20;
+          --border: #e2e5e9;
+          --border-strong: #ccd1d7;
+          --input: #e2e5e9;
+          --ring: #8b9198;
         }
       }
     </style>
@@ -1277,6 +1279,7 @@ export default function RootLayout({ children }: { children: unknown }) {
         -moz-osx-font-smoothing: grayscale;
       }
     </style>
+    <div class="fixed top-4 right-4 z-10"><theme-toggle></theme-toggle></div>
     <main class="min-h-dvh max-w-5xl mx-auto px-4 sm:px-6 py-8">
       \${children}
     </main>
@@ -1302,8 +1305,6 @@ export const metadata = {
 
 export default function Home() {
   return html\`
-    <div class="fixed top-4 right-4 z-10"><theme-toggle></theme-toggle></div>
-
     <div class="py-8 flex flex-col items-center gap-16">
       <!-- Masthead -->
       <section class="flex flex-col items-center text-center gap-5">
diff --git a/packages/cli/templates/scripts/clear-gallery.mjs b/packages/cli/templates/scripts/clear-gallery.mjs
index de2611cb9..44b32dc33 100644
--- a/packages/cli/templates/scripts/clear-gallery.mjs
+++ b/packages/cli/templates/scripts/clear-gallery.mjs
@@ -108,7 +108,9 @@ if (existsSync(schemaPath)) {
 // still honours light/dark, just without the manual toggle button.
 const layoutPath = join(root, 'app/layout.ts');
 if (existsSync(layoutPath)) {
-  const l = readFileSync(layoutPath, 'utf8').replace(/^import '#components\/theme-toggle\.ts';\n/m, '');
+  const l = readFileSync(layoutPath, 'utf8')
+    .replace(/^import '#components\/theme-toggle\.ts';\n/m, '')
+    .replace(/^\s*<div class="fixed top-4 right-4 z-10"><theme-toggle><\/theme-toggle><\/div>\n/m, '');
   writeFileSync(layoutPath, l);
 }
 

From 17956726ac448b267ce039e56d92018f32a31e76 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 17:03:09 +0530
Subject: [PATCH 40/73] refactor(gallery): add bareInputClass for the
 borderless in-card input

The greeter + todo add-forms compose a borderless input inside a cardClass() pill
(a search-bar), a genuinely distinct pattern from the standalone bordered
inputClass (a bordered field in a bordered card would be a box-in-a-box). It
appeared identically in both, so centralize it as bareInputClass() rather than
inline Tailwind. Verified: check + typecheck pass, no inline bare inputs remain.
---
 .../cli/templates/gallery/components/ui/input.ts    | 13 +++++++++++++
 .../modules/server-actions/components/greeter.ts    |  3 ++-
 .../gallery/modules/todo/components/todo-app.ts     |  3 ++-
 3 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/packages/cli/templates/gallery/components/ui/input.ts b/packages/cli/templates/gallery/components/ui/input.ts
index c8def4b50..81df2731e 100644
--- a/packages/cli/templates/gallery/components/ui/input.ts
+++ b/packages/cli/templates/gallery/components/ui/input.ts
@@ -35,3 +35,16 @@ const BASE =
 export function inputClass(extra?: string): string {
   return cn(BASE, extra);
 }
+
+// A BORDERLESS field for composing INSIDE a card/pill: a `cardClass()` form with a
+// button (a search-bar). The card is the bordered container, so the field is
+// seamless (transparent, no border), and it flexes to fill the row. Distinct from
+// inputClass (a standalone bordered field); a bordered input inside a bordered
+// card would be a box-in-a-box.
+const BARE =
+  'flex-1 min-w-0 bg-transparent border-0 outline-none py-1.5 text-[15px] text-foreground placeholder:text-muted-foreground';
+
+/** Compose the classes for a borderless text field composed inside a card pill. */
+export function bareInputClass(extra?: string): string {
+  return cn(BARE, extra);
+}
diff --git a/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts b/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts
index 0d49e7b1e..00d794a21 100644
--- a/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts
+++ b/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts
@@ -3,6 +3,7 @@
 import { WebComponent, signal, html } from '@webjsdev/core';
 import { cardClass } from '#components/ui/card.ts';
 import { buttonClass } from '#components/ui/button.ts';
+import { bareInputClass } from '#components/ui/input.ts';
 import { greet } from '../actions/greet.server.ts';
 
 export class Greeter extends WebComponent {
@@ -25,7 +26,7 @@ export class Greeter extends WebComponent {
         <form @submit=${(e: SubmitEvent) => this.run(e)}
           class="${cardClass()} flex items-center gap-2 p-2 pl-4">
           <input name="name" placeholder="your name" autocomplete="off"
-            class="flex-1 min-w-0 bg-transparent border-0 outline-none text-foreground text-[15px] placeholder:text-muted-foreground py-1.5" />
+            class=${bareInputClass()} />
           <button type="submit"
             class="${buttonClass()} shrink-0">Greet</button>
         </form>
diff --git a/packages/cli/templates/gallery/modules/todo/components/todo-app.ts b/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
index 4cdfe520d..49ab8259a 100644
--- a/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
+++ b/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
@@ -12,6 +12,7 @@
 import { WebComponent, prop, optimistic, html } from '@webjsdev/core';
 import { cardClass } from '#components/ui/card.ts';
 import { buttonClass } from '#components/ui/button.ts';
+import { bareInputClass } from '#components/ui/input.ts';
 import { cn } from '#lib/utils/cn.ts';
 import { createTodo } from '../actions/create-todo.server.ts';
 import { toggleTodo } from '../actions/toggle-todo.server.ts';
@@ -100,7 +101,7 @@ export class TodoApp extends WebComponent({
           class="${cardClass()} flex items-center gap-2 p-2 pl-4 shadow-[0_1px_0_0_color-mix(in_oklch,var(--foreground)_5%,transparent)]">
           <input type="hidden" name="intent" value="create" />
           <input name="title" required maxlength="280" autocomplete="off" placeholder="What needs doing?"
-            class="flex-1 min-w-0 bg-transparent border-0 outline-none text-foreground text-[15px] placeholder:text-muted-foreground py-1.5" />
+            class=${bareInputClass()} />
           <button type="submit"
             class="${buttonClass()} shrink-0">Add</button>
         </form>

From 4f2d1d69fe8c8d82aaa903f37a762522115b85a2 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 17:34:36 +0530
Subject: [PATCH 41/73] feat(gallery): floating WebJs Gallery navbar + DRY
 light-dark tokens

Add a floating top navbar (brand + Docs/GitHub + theme toggle) on every page, so
the toggle lives in the header instead of a fixed corner and the brand is always
present. Collapse the three duplicated token blocks (dark default + [data-theme]
light + @media light) into ONE definition per colour via CSS light-dark(), driven
by color-scheme (Baseline 2024): a palette change now lands in a single place.
Simplify the home to an 'Explore the gallery' hero (the navbar carries the
brand), open external links in new tabs, and subtract the navbar height from
main + the features sidebar cap so a short page has no spurious scrollbar.
Verified in-browser: both themes correct via the real toggle, navbar floats,
metadata page overflow 0.
---
 packages/cli/lib/create.js                    | 172 ++++++++----------
 .../templates/gallery/app/features/layout.ts  |   5 +-
 2 files changed, 76 insertions(+), 101 deletions(-)

diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
index a2dc111fe..f687981c4 100644
--- a/packages/cli/lib/create.js
+++ b/packages/cli/lib/create.js
@@ -1126,20 +1126,21 @@ export default function RootLayout({ children }: { children: unknown }) {
   const nonce = cspNonce();
   return html\`
     <script nonce="\${nonce}">
-      // Light/dark theme: read the saved or OS choice and set data-theme plus the
-      // .dark class the tokens key off. Delete this block (and the light blocks
-      // below) for a single-theme app.
+      // Light/dark theme: apply the saved choice before paint (no flash). The
+      // tokens follow color-scheme, which [data-theme] forces and otherwise
+      // follows the OS, so an unset choice needs NO inline work here. The .dark
+      // class is synced only for @webjsdev/ui components (they key off .dark).
+      // Delete this block and the [data-theme] rules below for a single-theme app.
       (function(){
         try {
-          var mq = window.matchMedia('(prefers-color-scheme: light)');
+          var mq = window.matchMedia('(prefers-color-scheme: dark)');
           function apply(){
             var t = null;
             try { t = localStorage.getItem('webjs_theme'); } catch (_) {}
             var el = document.documentElement;
             if (t === 'light' || t === 'dark') el.dataset.theme = t;
             else delete el.dataset.theme;
-            var dark = t === 'dark' || (t !== 'light' && !mq.matches);
-            el.classList.toggle('dark', dark);
+            el.classList.toggle('dark', t === 'dark' || (t !== 'light' && mq.matches));
           }
           apply();
           mq.addEventListener('change', apply);
@@ -1153,7 +1154,9 @@ export default function RootLayout({ children }: { children: unknown }) {
         function measure(){
           try {
             var hdr = document.querySelector('header');
-            if (!hdr) return;
+            // Only a FIXED header leaves normal flow and needs its height
+            // reserved; a normal in-flow header (the gallery's navbar) does not.
+            if (!hdr || getComputedStyle(hdr).position !== 'fixed') return;
             var apply = function(){
               document.documentElement.style.setProperty('--header-h', hdr.offsetHeight + 'px');
             };
@@ -1181,91 +1184,51 @@ export default function RootLayout({ children }: { children: unknown }) {
 
     <link rel="stylesheet" href="/public/tailwind.css">
     <style>
-      /* Design tokens. The token NAMES are infrastructure (public/input.css maps
-         them into Tailwind via @theme). The VALUES are a cool neutral-grey palette
-         with a monospaced type system: change them here to give the app its own
-         look. bg-background / text-foreground / bg-card / bg-primary / border-border
-         all resolve from these. */
+      /* Design tokens: ONE definition per colour via light-dark(LIGHT, DARK), so
+         a palette change lands in a single place (DRY). The token NAMES are
+         infrastructure (public/input.css maps them into Tailwind via @theme); the
+         VALUES are a cool neutral-grey palette with a monospaced type system.
+         color-scheme decides which side of each light-dark() applies: the default
+         'light dark' follows the OS, and the toggle FORCES one via [data-theme]
+         below. The light theme is a crisp WHITE page with near-black text, a
+         readable muted grey, and visible borders (a washed-out light theme comes
+         from a grey page + too-light muted text + faint borders). For a
+         single-theme app, delete the [data-theme] rules and give each token a
+         single colour instead of light-dark(). */
       :root {
         --font-sans:  'JetBrains Mono', ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, monospace;
         --font-serif: ui-serif, 'Iowan Old Style', Palatino, Georgia, serif;
         --font-mono:  'JetBrains Mono', ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, monospace;
         --font-display: 'Bricolage Grotesque', 'JetBrains Mono', ui-sans-serif, system-ui, sans-serif;
         --header-h: 0px;
+
+        color-scheme: light dark;                              /* default: follow the OS */
+        --background:         light-dark(#ffffff, #1e2226);
+        --foreground:         light-dark(#191c20, #dee2e6);
+        --card:               light-dark(#f7f8fa, #313539);
+        --card-foreground:    light-dark(#191c20, #dee2e6);
+        --popover:            light-dark(#ffffff, #313539);
+        --popover-foreground: light-dark(#191c20, #dee2e6);
+        --primary:            light-dark(#1e2226, #dee2e6);
+        --primary-foreground: light-dark(#ffffff, #1e2226);
+        --secondary:          light-dark(#eef0f2, #363a3e);
+        --secondary-foreground: light-dark(#191c20, #dee2e6);
+        --muted:              light-dark(#eef0f2, #313539);
+        --muted-foreground:   light-dark(#565c64, #94989c);
+        --accent:             light-dark(#e9ebef, #363a3e);
+        --accent-foreground:  light-dark(#191c20, #f7fbff);
+        --border:             light-dark(#e2e5e9, #34393e);
+        --border-strong:      light-dark(#ccd1d7, #454b51);
+        --input:              light-dark(#e2e5e9, #34393e);
+        --ring:               light-dark(#8b9198, #6b7075);
         /* A translucent tint of the primary, tracked automatically across
            light/dark. Used for focus rings (ring-primary-tint). */
         --primary-tint: color-mix(in srgb, var(--primary) 22%, transparent);
       }
-      /* dark (the default, and the explicit .dark the toggle sets) */
-      :root, .dark {
-        color-scheme: dark;
-        --background: #1e2226;
-        --foreground: #dee2e6;
-        --card: #313539;
-        --card-foreground: #dee2e6;
-        --popover: #313539;
-        --popover-foreground: #dee2e6;
-        --primary: #dee2e6;
-        --primary-foreground: #1e2226;
-        --secondary: #363a3e;
-        --secondary-foreground: #dee2e6;
-        --muted: #313539;
-        --muted-foreground: #94989c;
-        --accent: #363a3e;
-        --accent-foreground: #f7fbff;
-        --border: #34393e;
-        --border-strong: #454b51;
-        --input: #34393e;
-        --ring: #6b7075;
-      }
-      /* light (explicit via the toggle). A crisp white page with near-black
-         text, a readable muted grey, and visible borders (a washed-out light
-         theme comes from a grey page + too-light muted text + faint borders). */
-      :root[data-theme='light'] {
-        color-scheme: light;
-        --background: #ffffff;
-        --foreground: #191c20;
-        --card: #f7f8fa;
-        --card-foreground: #191c20;
-        --popover: #ffffff;
-        --popover-foreground: #191c20;
-        --primary: #1e2226;
-        --primary-foreground: #ffffff;
-        --secondary: #eef0f2;
-        --secondary-foreground: #191c20;
-        --muted: #eef0f2;
-        --muted-foreground: #565c64;
-        --accent: #e9ebef;
-        --accent-foreground: #191c20;
-        --border: #e2e5e9;
-        --border-strong: #ccd1d7;
-        --input: #e2e5e9;
-        --ring: #8b9198;
-      }
-      /* light (OS preference, when the user has made no explicit choice) */
-      @media (prefers-color-scheme: light) {
-        :root:not(.dark):not([data-theme='dark']) {
-          color-scheme: light;
-          --background: #ffffff;
-          --foreground: #191c20;
-          --card: #f7f8fa;
-          --card-foreground: #191c20;
-          --popover: #ffffff;
-          --popover-foreground: #191c20;
-          --primary: #1e2226;
-          --primary-foreground: #ffffff;
-          --secondary: #eef0f2;
-          --secondary-foreground: #191c20;
-          --muted: #eef0f2;
-          --muted-foreground: #565c64;
-          --accent: #e9ebef;
-          --accent-foreground: #191c20;
-          --border: #e2e5e9;
-          --border-strong: #ccd1d7;
-          --input: #e2e5e9;
-          --ring: #8b9198;
-        }
-      }
+      /* The toggle writes data-theme to FORCE a scheme; with neither attribute
+         the default 'color-scheme: light dark' above follows the OS. */
+      :root[data-theme='light'] { color-scheme: light; }
+      :root[data-theme='dark']  { color-scheme: dark; }
     </style>
     <style>
       /* Base styles utility classes can't reach. */
@@ -1279,8 +1242,24 @@ export default function RootLayout({ children }: { children: unknown }) {
         -moz-osx-font-smoothing: grayscale;
       }
     </style>
-    <div class="fixed top-4 right-4 z-10"><theme-toggle></theme-toggle></div>
-    <main class="min-h-dvh max-w-5xl mx-auto px-4 sm:px-6 py-8">
+    <!-- Top navbar, on every page: brand on the left, links + theme toggle on
+         the right. It floats (no separator) and is in normal flow, so it just
+         scrolls with the page; make it a fixed header only if you want it pinned
+         (position: fixed, never sticky, which flickers on iOS during a nav). -->
+    <header class="max-w-5xl mx-auto px-4 sm:px-6 h-14 flex items-center justify-between gap-4">
+      <a href="/" class="inline-flex items-center gap-2 no-underline text-foreground font-bold tracking-tight" style="font-family: var(--font-display)">
+        <span class="w-[22px] h-[22px] rounded-[7px] bg-gradient-to-br from-foreground to-muted-foreground" aria-hidden="true"></span>
+        WebJs Gallery
+      </a>
+      <nav class="flex items-center gap-4 text-sm" aria-label="Primary">
+        <a href="https://docs.webjs.dev" target="_blank" rel="noopener" class="hidden sm:inline text-muted-foreground hover:text-foreground no-underline transition-colors">Docs</a>
+        <a href="https://github.com/webjsdev/webjs" target="_blank" rel="noopener" class="hidden sm:inline text-muted-foreground hover:text-foreground no-underline transition-colors">GitHub</a>
+        <theme-toggle></theme-toggle>
+      </nav>
+    </header>
+    <!-- Fill the viewport minus the h-14 (3.5rem) navbar, so a short page has no
+         spurious scrollbar (min-h-dvh alone would overflow by the navbar height). -->
+    <main class="min-h-[calc(100dvh-3.5rem)] max-w-5xl mx-auto px-4 sm:px-6 py-8">
       \${children}
     </main>
   \`;
@@ -1306,26 +1285,18 @@ export const metadata = {
 export default function Home() {
   return html\`
     <div class="py-8 flex flex-col items-center gap-16">
-      <!-- Masthead -->
+      <!-- Hero -->
       <section class="flex flex-col items-center text-center gap-5">
-        <p class="text-xs font-semibold uppercase tracking-[0.22em] text-muted-foreground m-0">Welcome to</p>
-        <h1 class="text-6xl sm:text-7xl font-bold uppercase tracking-tight leading-none m-0 break-words bg-gradient-to-b from-foreground to-muted-foreground bg-clip-text text-transparent" style="font-family: var(--font-display); word-spacing: 0.08em; letter-spacing: -0.02em;">
-          WebJs Gallery
+        <h1 class="text-5xl sm:text-6xl font-bold tracking-tight leading-none m-0 break-words bg-gradient-to-b from-foreground to-muted-foreground bg-clip-text text-transparent" style="font-family: var(--font-display); letter-spacing: -0.02em;">
+          Explore the gallery
         </h1>
         <p class="text-base sm:text-lg text-muted-foreground max-w-lg leading-relaxed m-0">
-          AI-first and web-components-first. Server-rendered, progressively enhanced, and buildless.
+          Each demo isolates a single WebJs capability in real, runnable code. Read the ones you need, then build your app on the same patterns.
         </p>
       </section>
 
       <!-- Gallery: every feature demo + the example app -->
       <section class="w-full flex flex-col gap-6">
-        <div class="flex flex-col items-center gap-2 text-center">
-          <h2 class="text-xs font-semibold uppercase tracking-[0.16em] text-muted-foreground m-0">Explore the gallery</h2>
-          <p class="text-sm text-muted-foreground max-w-lg leading-relaxed m-0">
-            One WebJs concept per demo under <code class="text-[0.9em] text-foreground">app/features/</code>, with logic
-            in <code class="text-[0.9em] text-foreground">modules/</code>.
-          </p>
-        </div>
         <div class="grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
           \${FEATURES.map(f => html\`
             <a href="\${f.href}" class=\${cardClass('group flex flex-col gap-1.5 rounded-xl p-4 no-underline transition-colors hover:border-border-strong hover:bg-accent')}>
@@ -1352,8 +1323,8 @@ export default function Home() {
       <!-- Footer: docs + source -->
       <footer class="flex flex-col items-center gap-3">
         <nav class="flex items-center gap-6 text-sm text-muted-foreground" aria-label="WebJs links">
-          <a href="https://docs.webjs.dev" class="inline-flex items-center gap-2 hover:text-foreground transition-colors no-underline">\${iconBook()}<span>Docs</span></a>
-          <a href="https://github.com/webjsdev/webjs" class="inline-flex items-center gap-2 hover:text-foreground transition-colors no-underline">\${iconGithub()}<span>GitHub</span></a>
+          <a href="https://docs.webjs.dev" target="_blank" rel="noopener" class="inline-flex items-center gap-2 hover:text-foreground transition-colors no-underline">\${iconBook()}<span>Docs</span></a>
+          <a href="https://github.com/webjsdev/webjs" target="_blank" rel="noopener" class="inline-flex items-center gap-2 hover:text-foreground transition-colors no-underline">\${iconGithub()}<span>GitHub</span></a>
         </nav>
         <p class="text-[0.7rem] uppercase tracking-[0.15em] text-muted-foreground m-0 text-center">
           Built with WebJs &middot; MIT License
@@ -1414,9 +1385,10 @@ export class ThemeToggle extends WebComponent {
     const el = document.documentElement;
     if (next === 'system') delete el.dataset.theme;
     else el.dataset.theme = next;
-    // Keep the .dark class the @webjsdev/ui kit uses in sync so the ui-* components follow the theme.
+    // Our own tokens follow color-scheme via data-theme (set above). Keep the
+    // .dark class in sync only for @webjsdev/ui components, which key off it.
     const dark = next === 'dark'
-      || (next === 'system' && !window.matchMedia('(prefers-color-scheme: light)').matches);
+      || (next === 'system' && window.matchMedia('(prefers-color-scheme: dark)').matches);
     el.classList.toggle('dark', dark);
   }
 
diff --git a/packages/cli/templates/gallery/app/features/layout.ts b/packages/cli/templates/gallery/app/features/layout.ts
index b056b0554..601a3caca 100644
--- a/packages/cli/templates/gallery/app/features/layout.ts
+++ b/packages/cli/templates/gallery/app/features/layout.ts
@@ -28,7 +28,10 @@ export default function FeaturesLayout({ children, url }: { children: unknown; u
     <style>${SIDENAV_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">
-      <aside class="hidden lg:flex lg:flex-col sticky top-6 self-start max-h-[calc(100dvh-3rem)] text-sm">
+      <!-- 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-2 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">

From ee9704eb56fab66d763af810515c02c3feddad3f Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 17:49:26 +0530
Subject: [PATCH 42/73] feat(gallery): gallery:clear resets to a token-free
 blank slate

The blank slate should carry NO design system: the agent builds its own palette,
guided by the skill, rather than inheriting the gallery's. So gallery:clear now
overwrites app/layout.ts wholesale with a minimal layout that uses the OS
light/dark system colours (Canvas / CanvasText) and ships no design tokens,
navbar, toggle, or Google Fonts; the reset home is token-free too. Also document
the light-dark() edge cases (colour-only, derived tokens track for free, a
non-colour per-theme token needs a [data-theme] + @media override) in the gallery
layout. Scaffold tests updated for the navbar, the light-dark() palette, the new
hero, and the token-free reset; all 23 green.
---
 packages/cli/lib/create.js                    | 10 +-
 .../cli/templates/scripts/clear-gallery.mjs   | 92 +++++++++++++------
 test/scaffolds/scaffold-gallery.test.js       |  8 +-
 test/scaffolds/scaffold-integration.test.js   | 20 ++--
 .../scaffolds/scaffold-ui-integration.test.js |  4 +-
 5 files changed, 92 insertions(+), 42 deletions(-)

diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
index f687981c4..3460c5b16 100644
--- a/packages/cli/lib/create.js
+++ b/packages/cli/lib/create.js
@@ -1194,7 +1194,15 @@ export default function RootLayout({ children }: { children: unknown }) {
          readable muted grey, and visible borders (a washed-out light theme comes
          from a grey page + too-light muted text + faint borders). For a
          single-theme app, delete the [data-theme] rules and give each token a
-         single colour instead of light-dark(). */
+         single colour instead of light-dark().
+         EDGE CASES: light-dark() is COLOUR-only. A colour needed in just one
+         theme sets the unused side to a no-op, e.g. light-dark(#fff, transparent).
+         A DERIVED token that references a light-dark() one (like --primary-tint
+         below) tracks both themes for free. A NON-colour token that must differ
+         per theme (a shadow's geometry, a gradient, a size, an image) cannot use
+         light-dark(); give it a :root[data-theme='dark'] override plus an
+         @media (prefers-color-scheme: dark) { :root:not([data-theme]) { ... } }
+         rule for the OS default. */
       :root {
         --font-sans:  'JetBrains Mono', ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, monospace;
         --font-serif: ui-serif, 'Iowan Old Style', Palatino, Georgia, serif;
diff --git a/packages/cli/templates/scripts/clear-gallery.mjs b/packages/cli/templates/scripts/clear-gallery.mjs
index 44b32dc33..d31e4d7ea 100644
--- a/packages/cli/templates/scripts/clear-gallery.mjs
+++ b/packages/cli/templates/scripts/clear-gallery.mjs
@@ -11,14 +11,17 @@
 //
 // It strips the app down to a TRULY BAREBONES blank slate: it removes the
 // gallery routes + modules + demo metadata routes, the gallery's example design
-// system (components/ui/), the example theme-toggle component + its wiring, the
-// example test suite (test/hello/), and every empty leftover dir, then resets
-// app/page.ts to a minimal home and drops the demo `todos` table plus the auth
-// card's `passwordHash` column from the schema. It KEEPS only the buildable
-// base: the agent skill (.agents/skills/webjs/), the root layout (with its
-// design-token palette + OS-preference dark mode, minus the toggle widget), the
-// database wiring, the example `users` table, and `lib/utils/cn.ts` (the
-// `webjs ui add` prerequisite).
+// system (components/ui/), the example theme-toggle component, the example test
+// suite (test/hello/), and every empty leftover dir, then resets app/page.ts to
+// a minimal home AND app/layout.ts to a blank-slate base (the gallery's navbar,
+// theme toggle, Google Fonts, AND design-token palette dropped: the reset layout
+// carries NO design system, just the OS light/dark system colours, so the agent
+// builds the palette as its own, guided by the skill), and drops the demo `todos`
+// table plus the auth card's `passwordHash` column from the schema. It KEEPS only
+// the buildable base: the agent skill (.agents/skills/webjs/), the reset root
+// layout (the Tailwind wiring + a system-colour base, no tokens), the database
+// wiring, the example `users` table, and `lib/utils/cn.ts` (the `webjs ui add`
+// prerequisite).
 //
 // Why strip so much: the demos, the design system, and the example component /
 // tests are all EXAMPLES to learn FROM, not a base to inherit. Leaving them
@@ -63,8 +66,8 @@ const galleryPaths = [
   'components/ui',
   // Example scaffold artifacts (invariant 2): the theme-toggle component and the
   // example test suite are things to learn from, not the agent's app. Removed
-  // for a true blank slate; the layout's theme import is stripped separately
-  // below. The agent writes its own tests + components for the real app.
+  // for a true blank slate; the root layout is reset to a minimal base below
+  // (which drops its toggle wiring). The agent writes its own tests + components.
   'components/theme-toggle.ts', 'test/hello',
   // The gallery's markup-chunk helpers. Their only users (the feature pages +
   // the features/examples layouts) are removed above, so drop the example file
@@ -101,18 +104,16 @@ if (existsSync(schemaPath)) {
   writeFileSync(schemaPath, s);
 }
 
-// 5) Strip the example theme-toggle from the root layout. The component file was
-// removed above; here the layout's registration import is removed so it does not
-// reference a missing module. The OS-preference dark-mode inline script + the
-// design tokens STAY (they need no component and work with JS off), so the app
-// still honours light/dark, just without the manual toggle button.
+// 5) Reset the root layout to a blank-slate base. The gallery layout ships a
+// navbar, a theme toggle, Google Fonts, and a full design-token palette; a blank
+// slate should inherit NONE of that, so OVERWRITE it with a minimal layout that
+// carries no design system: the Tailwind stylesheet + OS light/dark system
+// colours (Canvas / CanvasText) + a bare <main>. The agent then builds the
+// palette (CSS tokens + @theme + a light-dark() theme) as its own, guided by
+// .agents/skills/webjs/references/styling.md. (Safe under the app/features/ guard
+// above: the gallery is still present, so the layout is not hand-customised yet.)
 const layoutPath = join(root, 'app/layout.ts');
-if (existsSync(layoutPath)) {
-  const l = readFileSync(layoutPath, 'utf8')
-    .replace(/^import '#components\/theme-toggle\.ts';\n/m, '')
-    .replace(/^\s*<div class="fixed top-4 right-4 z-10"><theme-toggle><\/theme-toggle><\/div>\n/m, '');
-  writeFileSync(layoutPath, l);
-}
+if (existsSync(layoutPath)) writeFileSync(layoutPath, MINIMAL_LAYOUT());
 
 // 6) Drop generated migrations + the dev database so the next db:generate is
 // clean against the reset schema (safe: the scaffold has no real data yet).
@@ -141,16 +142,53 @@ export default function Home() {
   return html\`
     <div class="max-w-2xl mx-auto px-6 py-24 flex flex-col items-center text-center gap-6">
       <h1 class="text-4xl font-bold tracking-tight m-0">Your app</h1>
-      <p class="text-base text-muted-foreground leading-relaxed m-0">
-        The gallery is cleared. This is <code class="text-[0.9em] text-foreground">app/page.ts</code>. Build your
-        app from here. The guide is <code class="text-[0.9em] text-foreground">.agents/skills/webjs/SKILL.md</code>.
+      <p class="text-base leading-relaxed m-0 opacity-70">
+        The gallery is cleared. This is <code class="text-[0.9em]">app/page.ts</code>. Build your
+        app from here. The guide is <code class="text-[0.9em]">.agents/skills/webjs/SKILL.md</code>.
       </p>
-      <nav class="flex items-center gap-5 text-sm text-muted-foreground">
-        <a href="https://docs.webjs.dev" class="hover:text-foreground transition-colors no-underline">Docs</a>
-        <a href="https://github.com/webjsdev/webjs" class="hover:text-foreground transition-colors no-underline">GitHub</a>
+      <nav class="flex items-center gap-5 text-sm opacity-70">
+        <a href="https://docs.webjs.dev" target="_blank" rel="noopener" class="hover:opacity-100 transition-opacity no-underline">Docs</a>
+        <a href="https://github.com/webjsdev/webjs" target="_blank" rel="noopener" class="hover:opacity-100 transition-opacity no-underline">GitHub</a>
       </nav>
     </div>
   \`;
 }
 `;
 }
+
+function MINIMAL_LAYOUT() {
+  return `import { html } from '@webjsdev/core';
+
+/**
+ * Root layout: the ONLY file that writes the document shell. It links the
+ * Tailwind stylesheet and renders \${children} in a bare container. This is a
+ * BLANK SLATE with no design system: it uses the OS light/dark system colours
+ * (Canvas / CanvasText) so it reads fine immediately, and it is where YOU build
+ * the app's look. The recommended setup, CSS custom-property tokens mapped into
+ * Tailwind via @theme (so bg-background / text-foreground work), a DRY
+ * light-dark() palette, a header/nav, and the ui class helpers, is taught in
+ * .agents/skills/webjs/references/styling.md. Run \\\`npx webjsdev ui add <name>\\\`
+ * to pull primitives, then theme them here.
+ */
+export default function RootLayout({ children }: { children: unknown }) {
+  return html\`
+    <meta name="color-scheme" content="light dark">
+    <link rel="icon" href="/public/favicon.svg" type="image/svg+xml">
+    <link rel="stylesheet" href="/public/tailwind.css">
+    <style>
+      html, body { margin: 0; }
+      body {
+        background: Canvas;
+        color: CanvasText;
+        font: 15px/1.6 ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+        -webkit-font-smoothing: antialiased;
+        -moz-osx-font-smoothing: grayscale;
+      }
+    </style>
+    <main class="min-h-dvh max-w-3xl mx-auto px-6 py-10">
+      \${children}
+    </main>
+  \`;
+}
+`;
+}
diff --git a/test/scaffolds/scaffold-gallery.test.js b/test/scaffolds/scaffold-gallery.test.js
index 38254ce80..fde6fe833 100644
--- a/test/scaffolds/scaffold-gallery.test.js
+++ b/test/scaffolds/scaffold-gallery.test.js
@@ -221,11 +221,13 @@ test('full-stack gallery:clear strips the app to a barebones blank slate', async
     assert.deepEqual(componentsLeft, [], `components/ must be empty after clear, found: ${componentsLeft.join(', ')}`);
     assert.ok(has('app', 'layout.ts'), 'root layout kept');
 
-    // The layout no longer references the removed theme-toggle, but keeps its
-    // OS-preference dark-mode script (works with no component, JS off).
+    // The layout is reset to a blank-slate base: no theme-toggle, no design-token
+    // palette, just the OS light/dark system colours (Canvas / CanvasText). The
+    // design system is taught in the skill, not baked into the blank slate.
     const layout = await readFile(join(appDir, 'app', 'layout.ts'), 'utf8');
     assert.doesNotMatch(layout, /theme-toggle/, 'layout theme-toggle import stripped');
-    assert.match(layout, /prefers-color-scheme/, 'layout keeps OS-preference dark mode');
+    assert.doesNotMatch(layout, /--(?:background|foreground|primary):/, 'reset layout ships no design-token palette');
+    assert.match(layout, /background:\s*Canvas/, 'reset layout uses OS system colours');
 
     // The reset home is minimal: no <theme-toggle>, no gallery links.
     const home = await readFile(join(appDir, 'app', 'page.ts'), 'utf8');
diff --git a/test/scaffolds/scaffold-integration.test.js b/test/scaffolds/scaffold-integration.test.js
index 25a941752..023512342 100644
--- a/test/scaffolds/scaffold-integration.test.js
+++ b/test/scaffolds/scaffold-integration.test.js
@@ -120,20 +120,22 @@ test('scaffoldApp full-stack: writes the canonical full-stack app layout', async
       'theme-toggle must toggle the .dark class (shadcn dark-mode signal)');
 
     // Re-skinned shell: a JetBrains Mono type system on a cool neutral-grey
-    // surface palette (not the old orange brand), a full-height main, no chrome.
-    assert.match(layoutSrc, /<main class="min-h-dvh[^"]*">/,
-      'layout renders a full-height main');
-    assert.doesNotMatch(layoutSrc, /<header\b/, 'the shell ships no built-in header');
+    // surface palette (not the old orange brand), a floating top navbar, and a
+    // main that fills the viewport minus the navbar.
+    assert.match(layoutSrc, /<main class="min-h-\[calc\(100dvh-3\.5rem\)\][^"]*">/,
+      'layout main fills the viewport minus the navbar');
+    assert.match(layoutSrc, /<header\b/, 'the shell ships a floating top navbar');
     assert.match(layoutSrc, /JetBrains\+Mono/, 'layout loads the JetBrains Mono font');
-    assert.match(layoutSrc, /--primary:\s*#dee2e6/, 'layout ships the neutral surface palette');
+    assert.match(layoutSrc, /--primary:\s*light-dark\(#1e2226, #dee2e6\)/,
+      'layout ships the DRY light-dark() surface palette');
     assert.doesNotMatch(layoutSrc, /oklch\(0\.7 0\.16 52\)/,
       'no orange brand color survives in the neutral scaffold');
 
-    // The home page is a gallery index: a masthead, a grid linking every feature
-    // demo + the example app, and a footer with the docs + source links.
+    // The home page is a gallery index: an 'Explore the gallery' hero, a grid
+    // linking every feature demo + the example app, and a footer with the docs +
+    // source links.
     const pageSrc = readFileSync(join(appDir, 'app', 'page.ts'), 'utf8');
-    assert.match(pageSrc, /Welcome to/, 'home is a welcome page');
-    assert.match(pageSrc, /Explore the gallery/, 'home indexes the gallery');
+    assert.match(pageSrc, /Explore the gallery/, 'home hero indexes the gallery');
     assert.match(pageSrc, /from '#modules\/gallery\/nav\.ts'/, 'home reads the shared gallery nav (the feature + example index)');
     assert.match(pageSrc, /docs\.webjs\.dev/, 'footer links the docs');
     assert.match(pageSrc, /github\.com\/webjsdev\/webjs/, 'footer links the source');
diff --git a/test/scaffolds/scaffold-ui-integration.test.js b/test/scaffolds/scaffold-ui-integration.test.js
index 4bae774d0..886a32d43 100644
--- a/test/scaffolds/scaffold-ui-integration.test.js
+++ b/test/scaffolds/scaffold-ui-integration.test.js
@@ -50,7 +50,7 @@ test('full-stack scaffold pre-initialises the Webjs UI kit', async () => {
     // The gallery home builds its feature/example cards on the design system.
     const layout = await readFile(join(appDir, 'app', 'layout.ts'), 'utf8');
     const page = await readFile(join(appDir, 'app', 'page.ts'), 'utf8');
-    assert.match(page, /Welcome to/, 'home is the gallery welcome page');
+    assert.match(page, /Explore the gallery/, 'home is the gallery index page');
     assert.match(page, /cardClass|badgeClass/, 'the home cards use the design-system helpers');
 
     // CSS delivery (#947): the layout links a STATIC compiled stylesheet (works
@@ -63,7 +63,7 @@ test('full-stack scaffold pre-initialises the Webjs UI kit', async () => {
     const inputCss = await readFile(join(appDir, 'public', 'input.css'), 'utf8');
     assert.match(inputCss, /@import "tailwindcss"/, 'input.css imports Tailwind');
     assert.match(inputCss, /color-primary/, 'input.css carries the @theme color maps');
-    assert.match(layout, /--primary:\s*#[0-9a-f]{6}/i, 'the palette VALUES stay inline (JS-off safe)');
+    assert.match(layout, /--primary:\s*light-dark\(#[0-9a-f]{6}, #[0-9a-f]{6}\)/i, 'the palette VALUES stay inline via light-dark() (JS-off safe)');
   } finally {
     await rm(cwd, { recursive: true, force: true });
   }

From 55e792cb4cecf2b0e05e0653a483304dcf33c585 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 17:51:41 +0530
Subject: [PATCH 43/73] docs(skill): teach the design-token + light-dark()
 theming setup

The blank slate (post gallery:clear) ships no design system, so the skill must
teach how to build one. Expand styling.md's design-tokens section into a full
theming guide: the two halves (the @theme mapping in input.css vs the palette
values in the layout), the DRY light-dark() pattern driven by color-scheme, a
manual toggle (data-theme plus the .dark sync for @webjsdev/ui), the edge cases
(colour-only, derived tokens track for free, non-colour per-theme override), and
how the ui class helpers ride the same tokens.
---
 .agents/skills/webjs/references/styling.md | 35 ++++++++++++++++++++--
 1 file changed, 33 insertions(+), 2 deletions(-)

diff --git a/.agents/skills/webjs/references/styling.md b/.agents/skills/webjs/references/styling.md
index a24d5cb9b..7ebf389f1 100644
--- a/.agents/skills/webjs/references/styling.md
+++ b/.agents/skills/webjs/references/styling.md
@@ -103,9 +103,40 @@ A cleared, growing app hand-authors its own controls, so accessibility is your j
 
 Native `<button>` / `<a>` / `<input>` already have correct focus + keyboard behaviour, which is the main reason to prefer them (and the `buttonClass()` / `inputClass()` class helpers) over a custom `<div role>` element.
 
-## Design tokens
+## Design tokens and theming
 
-The default stack is a static compiled Tailwind stylesheet (`css:build` compiles `public/input.css` to the linked `public/tailwind.css`, so it works with JS off) plus `@theme` design tokens (palette, fonts, fluid type, motion durations) declared once in the root layout. Consume them as utility classes (`text-foreground`, `bg-card`, `font-serif`, `duration-fast`). If you wire your own theme switch, drive BOTH signals on `<html>` (the `data-theme` attribute for the app palette blocks AND the `.dark` class for the `@webjsdev/ui` kit), or half the UI renders stale tokens. Verify dark mode in a real browser, light mode passing proves nothing about dark.
+The default stack is a static compiled Tailwind stylesheet (`css:build` compiles `public/input.css` to the linked `public/tailwind.css`, so it works with JS off) plus `@theme` design tokens declared once in the root layout. You consume them as utility classes (`bg-background`, `text-foreground`, `bg-card`, `border-border`, `font-serif`).
+
+**Two halves.** (1) `public/input.css` MAPS token names into Tailwind with `@theme inline` (`--color-background: var(--background)`), so `bg-background` resolves to `var(--background)`. That is infrastructure; leave it. (2) The root layout (`app/layout.ts`) DEFINES the values as plain CSS custom properties in a `<style>` block. That is your palette; make it your own. A freshly cleared app (after `npm run gallery:clear`) ships only the OS system-colour base (`Canvas` / `CanvasText`) with NO tokens, so building this palette is your first styling step.
+
+**Light and dark, defined once (DRY).** Write each colour token ONE time with the native CSS `light-dark(LIGHT, DARK)` function and let `color-scheme` pick the side. The default `color-scheme: light dark` follows the OS; a `[data-theme]` attribute forces one. No duplicated light/dark blocks:
+
+```html
+<style>
+  :root {
+    --font-sans: ui-sans-serif, system-ui, sans-serif;
+    color-scheme: light dark;                        /* follow the OS by default */
+    --background:       light-dark(#ffffff, #1e2226);
+    --foreground:       light-dark(#191c20, #dee2e6);
+    --card:             light-dark(#f7f8fa, #313539);
+    --muted-foreground: light-dark(#565c64, #94989c);
+    --border:           light-dark(#e2e5e9, #34393e);
+    --primary:          light-dark(#1e2226, #dee2e6);
+    /* a derived token tracks BOTH themes for free via var(--primary) */
+    --primary-tint: color-mix(in srgb, var(--primary) 22%, transparent);
+  }
+  :root[data-theme='light'] { color-scheme: light; }  /* the toggle forces a scheme */
+  :root[data-theme='dark']  { color-scheme: dark; }
+</style>
+```
+
+`light-dark()` is a native CSS function (CSS Color 5, Baseline 2024), not a library, so nothing to import. A single-theme app drops the `[data-theme]` rules and gives each token one colour.
+
+**A manual theme toggle** writes `data-theme` on `<html>` (`light` / `dark`, or removes it for "follow the OS"). If you use `@webjsdev/ui` components, ALSO keep the `.dark` class in sync (the ui kit keys its own tokens off `.dark`), and apply the saved choice in a tiny inline `<script>` in the layout head so there is no first-paint flash. Verify dark mode in a real browser. Light mode passing proves nothing about dark.
+
+**Edge cases.** `light-dark()` is COLOUR-only. A colour needed in just one theme sets the unused side to a no-op (`light-dark(#fff, transparent)`). A derived token that references a `light-dark()` one (like `--primary-tint` above) tracks both themes automatically. A NON-colour token that must differ per theme (a shadow's geometry, a gradient, a size, an image) cannot use `light-dark()`; give it a `:root[data-theme='dark']` override plus an `@media (prefers-color-scheme: dark) { :root:not([data-theme]) { ... } }` rule for the OS default.
+
+**The ui class helpers build on these tokens.** `buttonClass()` / `cardClass()` / `inputClass()` / `badgeClass()` emit Tailwind utilities that reference the same tokens (`bg-primary`, `border-border`), so theming the tokens re-skins every helper at once.
 
 ## Light-DOM host display, and shadow hosts
 

From 93f9dd1aaf53fdfe06c03050dcafdbaa840e4b4e Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 18:07:41 +0530
Subject: [PATCH 44/73] style(gallery): widen the gap between explanatory prose
 paragraphs

The trailing explanatory notes on the demos (the text-muted-foreground text-sm
paragraphs) sat only 8-12px apart with inconsistent per-paragraph margins, so a
multi-paragraph block read as a wall of text. Widen the between-paragraph margins
to a uniform ~20px (mb-2/mt-3/mt-4 -> mb-5/mt-5) across every demo, scoped to the
prose lines only so headings, back links, and code-intro captions are untouched.
Verified in-browser: Routing's four notes now sit at an even 20px.
---
 .../cli/templates/gallery/app/features/boundaries/page.ts   | 4 ++--
 packages/cli/templates/gallery/app/features/caching/page.ts | 2 +-
 .../templates/gallery/app/features/client-router/page.ts    | 2 +-
 .../cli/templates/gallery/app/features/rate-limit/page.ts   | 2 +-
 .../cli/templates/gallery/app/features/routing/[id]/page.ts | 4 ++--
 packages/cli/templates/gallery/app/features/routing/page.ts | 6 +++---
 .../cli/templates/gallery/app/features/sessions/page.ts     | 2 +-
 7 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/packages/cli/templates/gallery/app/features/boundaries/page.ts b/packages/cli/templates/gallery/app/features/boundaries/page.ts
index 1aa2b3177..29d37e5d9 100644
--- a/packages/cli/templates/gallery/app/features/boundaries/page.ts
+++ b/packages/cli/templates/gallery/app/features/boundaries/page.ts
@@ -51,13 +51,13 @@ export default function BoundariesExample() {
         <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 mb-5">
       <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 mb-5">
       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
diff --git a/packages/cli/templates/gallery/app/features/caching/page.ts b/packages/cli/templates/gallery/app/features/caching/page.ts
index a55f9d9c2..cc915a45f 100644
--- a/packages/cli/templates/gallery/app/features/caching/page.ts
+++ b/packages/cli/templates/gallery/app/features/caching/page.ts
@@ -36,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 mt-6 mb-5">
       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
diff --git a/packages/cli/templates/gallery/app/features/client-router/page.ts b/packages/cli/templates/gallery/app/features/client-router/page.ts
index 9875d20d4..2565455ef 100644
--- a/packages/cli/templates/gallery/app/features/client-router/page.ts
+++ b/packages/cli/templates/gallery/app/features/client-router/page.ts
@@ -26,7 +26,7 @@ export default function ClientRouterExample() {
       <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 mb-5">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>,
diff --git a/packages/cli/templates/gallery/app/features/rate-limit/page.ts b/packages/cli/templates/gallery/app/features/rate-limit/page.ts
index 433c7f6fa..56c1e7d00 100644
--- a/packages/cli/templates/gallery/app/features/rate-limit/page.ts
+++ b/packages/cli/templates/gallery/app/features/rate-limit/page.ts
@@ -20,7 +20,7 @@ export default function RateLimitExample() {
       <code class="font-mono">Retry-After</code> header.
     `)}
     <rate-probe></rate-probe>
-    <p class="text-muted-foreground text-sm mt-4">
+    <p class="text-muted-foreground text-sm mt-5">
       With JavaScript off, hit
       <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).
diff --git a/packages/cli/templates/gallery/app/features/routing/[id]/page.ts b/packages/cli/templates/gallery/app/features/routing/[id]/page.ts
index 55119ab37..e47b419d8 100644
--- a/packages/cli/templates/gallery/app/features/routing/[id]/page.ts
+++ b/packages/cli/templates/gallery/app/features/routing/[id]/page.ts
@@ -26,14 +26,14 @@ export default async function RoutingParam({ params }: PageProps<'/features/rout
   return html`
     ${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 mt-5">
       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">
+    <p class="text-muted-foreground text-sm mt-5">
       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
diff --git a/packages/cli/templates/gallery/app/features/routing/page.ts b/packages/cli/templates/gallery/app/features/routing/page.ts
index 64b4e9917..45517e7c1 100644
--- a/packages/cli/templates/gallery/app/features/routing/page.ts
+++ b/packages/cli/templates/gallery/app/features/routing/page.ts
@@ -16,7 +16,7 @@ export default function RoutingExample() {
       <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 mb-5">
       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
@@ -24,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 mb-5">
       Programmatic navigation is checked too:
       <code class="font-mono">navigate(url)</code> takes that
       <code class="font-mono">Route</code> union, so
@@ -44,7 +44,7 @@ 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 mt-5">
       A page can also THROW to short-circuit rendering:
       <code class="font-mono">notFound()</code> (404),
       <code class="font-mono">forbidden()</code> (403), and
diff --git a/packages/cli/templates/gallery/app/features/sessions/page.ts b/packages/cli/templates/gallery/app/features/sessions/page.ts
index 9814e6e18..f6a6ed5c2 100644
--- a/packages/cli/templates/gallery/app/features/sessions/page.ts
+++ b/packages/cli/templates/gallery/app/features/sessions/page.ts
@@ -14,6 +14,6 @@ export default function SessionsExample() {
     ${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 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>
+    <p class="text-muted-foreground text-sm mt-5">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>
   `;
 }

From 3159d315ca8fd6528f47e7eec534bf1fe12d0745 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 18:57:05 +0530
Subject: [PATCH 45/73] style(gallery): widen prose paragraph gap further to
 ~32px

Bump the between-paragraph margins on the explanatory notes from ~20px to ~32px
(mb-5/mt-5 -> mb-8/mt-8), still scoped to the text-muted-foreground text-sm prose
lines. Verified in-browser: Routing's notes sit at an even 32px.
---
 .../cli/templates/gallery/app/features/boundaries/page.ts   | 4 ++--
 packages/cli/templates/gallery/app/features/caching/page.ts | 2 +-
 .../templates/gallery/app/features/client-router/page.ts    | 2 +-
 .../cli/templates/gallery/app/features/rate-limit/page.ts   | 2 +-
 .../cli/templates/gallery/app/features/routing/[id]/page.ts | 4 ++--
 packages/cli/templates/gallery/app/features/routing/page.ts | 6 +++---
 .../cli/templates/gallery/app/features/sessions/page.ts     | 2 +-
 7 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/packages/cli/templates/gallery/app/features/boundaries/page.ts b/packages/cli/templates/gallery/app/features/boundaries/page.ts
index 29d37e5d9..f4dfbb71d 100644
--- a/packages/cli/templates/gallery/app/features/boundaries/page.ts
+++ b/packages/cli/templates/gallery/app/features/boundaries/page.ts
@@ -51,13 +51,13 @@ export default function BoundariesExample() {
         <code class="font-mono">not-found.ts</code> (404).
       </li>
     </ul>
-    <p class="text-muted-foreground text-sm mb-5">
+    <p class="text-muted-foreground text-sm mb-8">
       <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-5">
+    <p class="text-muted-foreground text-sm mb-8">
       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
diff --git a/packages/cli/templates/gallery/app/features/caching/page.ts b/packages/cli/templates/gallery/app/features/caching/page.ts
index cc915a45f..2c83dd887 100644
--- a/packages/cli/templates/gallery/app/features/caching/page.ts
+++ b/packages/cli/templates/gallery/app/features/caching/page.ts
@@ -36,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-5">
+    <p class="text-muted-foreground text-sm mt-6 mb-8">
       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
diff --git a/packages/cli/templates/gallery/app/features/client-router/page.ts b/packages/cli/templates/gallery/app/features/client-router/page.ts
index 2565455ef..79d0fda67 100644
--- a/packages/cli/templates/gallery/app/features/client-router/page.ts
+++ b/packages/cli/templates/gallery/app/features/client-router/page.ts
@@ -26,7 +26,7 @@ export default function ClientRouterExample() {
       <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-5">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 mb-8">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>,
diff --git a/packages/cli/templates/gallery/app/features/rate-limit/page.ts b/packages/cli/templates/gallery/app/features/rate-limit/page.ts
index 56c1e7d00..beccf046e 100644
--- a/packages/cli/templates/gallery/app/features/rate-limit/page.ts
+++ b/packages/cli/templates/gallery/app/features/rate-limit/page.ts
@@ -20,7 +20,7 @@ export default function RateLimitExample() {
       <code class="font-mono">Retry-After</code> header.
     `)}
     <rate-probe></rate-probe>
-    <p class="text-muted-foreground text-sm mt-5">
+    <p class="text-muted-foreground text-sm mt-8">
       With JavaScript off, hit
       <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).
diff --git a/packages/cli/templates/gallery/app/features/routing/[id]/page.ts b/packages/cli/templates/gallery/app/features/routing/[id]/page.ts
index e47b419d8..b653a686a 100644
--- a/packages/cli/templates/gallery/app/features/routing/[id]/page.ts
+++ b/packages/cli/templates/gallery/app/features/routing/[id]/page.ts
@@ -26,14 +26,14 @@ export default async function RoutingParam({ params }: PageProps<'/features/rout
   return html`
     ${pageHeading('Route param')}
     <p>The <code>[id]</code> segment is: <strong>${id}</strong></p>
-    <p class="text-muted-foreground text-sm mt-5">
+    <p class="text-muted-foreground text-sm mt-8">
       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-5">
+    <p class="text-muted-foreground text-sm mt-8">
       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
diff --git a/packages/cli/templates/gallery/app/features/routing/page.ts b/packages/cli/templates/gallery/app/features/routing/page.ts
index 45517e7c1..88a2e1ada 100644
--- a/packages/cli/templates/gallery/app/features/routing/page.ts
+++ b/packages/cli/templates/gallery/app/features/routing/page.ts
@@ -16,7 +16,7 @@ export default function RoutingExample() {
       <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-5">
+    <p class="text-muted-foreground text-sm mb-8">
       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
@@ -24,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-5">
+    <p class="text-muted-foreground text-sm mb-8">
       Programmatic navigation is checked too:
       <code class="font-mono">navigate(url)</code> takes that
       <code class="font-mono">Route</code> union, so
@@ -44,7 +44,7 @@ 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-5">
+    <p class="text-muted-foreground text-sm mt-8">
       A page can also THROW to short-circuit rendering:
       <code class="font-mono">notFound()</code> (404),
       <code class="font-mono">forbidden()</code> (403), and
diff --git a/packages/cli/templates/gallery/app/features/sessions/page.ts b/packages/cli/templates/gallery/app/features/sessions/page.ts
index f6a6ed5c2..59738bf79 100644
--- a/packages/cli/templates/gallery/app/features/sessions/page.ts
+++ b/packages/cli/templates/gallery/app/features/sessions/page.ts
@@ -14,6 +14,6 @@ export default function SessionsExample() {
     ${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 mt-5">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>
+    <p class="text-muted-foreground text-sm mt-8">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>
   `;
 }

From 5a6f3a78fa7a93cab32d73f1a0e67a7851f772b3 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 18:59:54 +0530
Subject: [PATCH 46/73] style(gallery): make caching's inter-paragraph gap
 consistent (32px)

Its second note used mt-6 (24px) where every other multi-paragraph demo now sits
at 32px; bump to mt-8 so the whole gallery is uniform.
---
 packages/cli/templates/gallery/app/features/caching/page.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/cli/templates/gallery/app/features/caching/page.ts b/packages/cli/templates/gallery/app/features/caching/page.ts
index 2c83dd887..95790acbd 100644
--- a/packages/cli/templates/gallery/app/features/caching/page.ts
+++ b/packages/cli/templates/gallery/app/features/caching/page.ts
@@ -36,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-8">
+    <p class="text-muted-foreground text-sm mt-8 mb-8">
       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

From edd5c976ffe9614d1b2ea2ddb21d2fe4eaa08e96 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 19:14:50 +0530
Subject: [PATCH 47/73] feat(gallery): uniform section rhythm via a single
 stack container

Per-paragraph inline margins can never be consistent: each element controls only
one side, so a note's gap-above (the previous element's margin) differs from its
gap-below (its own). Replace that with a design-system approach: the demo content
column is a .demo-stack that zeroes every direct child's block margins and puts
ONE uniform gap (--section-gap: 2rem) before every section after the first, so a
heading, lede, paragraph, component, or list are all equally spaced from one
place. Children are forced display:block so a shadow-DOM host (inline by default)
also honours the gap. Verified: routing + components pages show a uniform 32px
between every top-level section, including the reactive-meter shadow component.
---
 .../templates/gallery/app/features/layout.ts  | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/packages/cli/templates/gallery/app/features/layout.ts b/packages/cli/templates/gallery/app/features/layout.ts
index 601a3caca..f93734315 100644
--- a/packages/cli/templates/gallery/app/features/layout.ts
+++ b/packages/cli/templates/gallery/app/features/layout.ts
@@ -16,6 +16,21 @@ const SIDENAV_CSS = `
   .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. It zeroes each direct child's own
+// block margins, then puts an equal gap before every child after the first. This
+// is the single place that controls demo spacing. A group that must stay tight (a
+// caption directly above its code) is wrapped in ONE child <div>, which keeps its
+// own inner spacing (the reset only reaches DIRECT children of .demo-stack).
+const STACK_CSS = `
+  .demo-stack { --section-gap: 2rem; }
+  /* block so vertical gaps apply even to a shadow-DOM host (inline by default,
+     and inline elements ignore block margins). */
+  .demo-stack > * { display: block; margin-block: 0; }
+  .demo-stack > * + * { margin-block-start: var(--section-gap); }
+`;
+
 // 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
@@ -25,7 +40,7 @@ const SIDENAV_CSS = `
 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}</style>
+    <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
@@ -38,7 +53,7 @@ export default function FeaturesLayout({ children, url }: { children: unknown; u
           <gallery-nav current=${path}></gallery-nav>
         </div>
       </aside>
-      <div class="min-w-0">${children}</div>
+      <div class="min-w-0 demo-stack">${children}</div>
     </div>
   `;
 }

From 917c02dd21bc460ee9a550e12d9988939bd3254f Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 19:17:40 +0530
Subject: [PATCH 48/73] style(gallery): tighten section gap to 1.5rem (24px)

One-line change to --section-gap, so it reflows every demo uniformly.
---
 packages/cli/templates/gallery/app/features/layout.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/cli/templates/gallery/app/features/layout.ts b/packages/cli/templates/gallery/app/features/layout.ts
index f93734315..fa0a5c7ad 100644
--- a/packages/cli/templates/gallery/app/features/layout.ts
+++ b/packages/cli/templates/gallery/app/features/layout.ts
@@ -24,7 +24,7 @@ const SIDENAV_CSS = `
 // caption directly above its code) is wrapped in ONE child <div>, which keeps its
 // own inner spacing (the reset only reaches DIRECT children of .demo-stack).
 const STACK_CSS = `
-  .demo-stack { --section-gap: 2rem; }
+  .demo-stack { --section-gap: 1.5rem; }
   /* block so vertical gaps apply even to a shadow-DOM host (inline by default,
      and inline elements ignore block margins). */
   .demo-stack > * { display: block; margin-block: 0; }

From 2a8f3e5574e65f28e06b94e5126c304568791129 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 19:20:29 +0530
Subject: [PATCH 49/73] fix(gallery): streaming demo reserves its output box
 only while streaming

The <pre> always rendered with mt-4 + min-h-[3rem], leaving an empty box below
the button before any stream. Render it only when busy or output is present, so
an idle demo has no dead space and the area fills on click.
---
 .../gallery/modules/streaming/components/token-stream.ts   | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/packages/cli/templates/gallery/modules/streaming/components/token-stream.ts b/packages/cli/templates/gallery/modules/streaming/components/token-stream.ts
index 6fabdaab7..458cdafba 100644
--- a/packages/cli/templates/gallery/modules/streaming/components/token-stream.ts
+++ b/packages/cli/templates/gallery/modules/streaming/components/token-stream.ts
@@ -31,6 +31,9 @@ export class TokenStream extends WebComponent {
 
   render() {
     const busy = this.busy.get();
+    const output = this.output.get();
+    // Only reserve the output area once streaming starts (or has produced text),
+    // so an idle demo has no empty box below the button.
     return html`
       <div class="${cardClass()} p-5">
         <button
@@ -40,7 +43,9 @@ export class TokenStream extends WebComponent {
         >
           ${busy ? 'streaming…' : 'Stream tokens'}
         </button>
-        <pre class="mt-4 whitespace-pre-wrap font-mono text-sm text-foreground min-h-[3rem]">${this.output.get()}</pre>
+        ${busy || output
+          ? html`<pre class="mt-4 whitespace-pre-wrap font-mono text-sm text-foreground min-h-[3rem]">${output}</pre>`
+          : ''}
       </div>
     `;
   }

From e05fc2ac2d2207f299129c1153653deb6364151f Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 19:25:33 +0530
Subject: [PATCH 50/73] fix(gallery): streaming output box fits its content,
 not a fixed min-height

The <pre> had min-h-[3rem], so a short completed stream left empty space below the
text, making the card's bottom gap larger than its top. Drop the min-height (the
box now only appears on click, so no reservation is needed); the card padding is
symmetric again. Verified: 21px above the button matches 21px below the output.
---
 .../gallery/modules/streaming/components/token-stream.ts        | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/cli/templates/gallery/modules/streaming/components/token-stream.ts b/packages/cli/templates/gallery/modules/streaming/components/token-stream.ts
index 458cdafba..0b7364b0d 100644
--- a/packages/cli/templates/gallery/modules/streaming/components/token-stream.ts
+++ b/packages/cli/templates/gallery/modules/streaming/components/token-stream.ts
@@ -44,7 +44,7 @@ export class TokenStream extends WebComponent {
           ${busy ? 'streaming…' : 'Stream tokens'}
         </button>
         ${busy || output
-          ? html`<pre class="mt-4 whitespace-pre-wrap font-mono text-sm text-foreground min-h-[3rem]">${output}</pre>`
+          ? html`<pre class="mt-4 whitespace-pre-wrap font-mono text-sm text-foreground">${output}</pre>`
           : ''}
       </div>
     `;

From dd716fe3a71efdba1dc068d60c44f3de7cb66cd1 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 19:47:14 +0530
Subject: [PATCH 51/73] fix(gallery): section rhythm survives streaming +
 display:contents

The soft-nav Suspense fallback had no top gap: while streaming, <webjs-suspense>
is display:contents (no box, so the stack's margin is ignored), and the streaming
<script>/<template> nodes, forced visible by the blanket display:block, gained
phantom gaps. Skip script/style/template in the stack rules, use ~ (not +) so an
interleaved streaming node can't break the adjacency, and force <webjs-suspense>
to a block box so it carries its gap (CSS-only, so streaming's DOM moves are
untouched). Verified: fallback now has the 24px gap on soft-nav, resolved fact
keeps it, and static demos stay uniform.
---
 .../cli/templates/gallery/app/features/layout.ts   | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/packages/cli/templates/gallery/app/features/layout.ts b/packages/cli/templates/gallery/app/features/layout.ts
index fa0a5c7ad..deec0d2d0 100644
--- a/packages/cli/templates/gallery/app/features/layout.ts
+++ b/packages/cli/templates/gallery/app/features/layout.ts
@@ -25,10 +25,16 @@ const SIDENAV_CSS = `
 // own inner spacing (the reset only reaches DIRECT children of .demo-stack).
 const STACK_CSS = `
   .demo-stack { --section-gap: 1.5rem; }
-  /* block so vertical gaps apply even to a shadow-DOM host (inline by default,
-     and inline elements ignore block margins). */
-  .demo-stack > * { display: block; margin-block: 0; }
-  .demo-stack > * + * { margin-block-start: var(--section-gap); }
+  /* Space only RENDERED sections; skip streaming <script>/<style>/<template>
+     nodes (a forced-visible script would otherwise gain a phantom gap). block so
+     a shadow-DOM host (inline by default) honours the gap; ~ (not +) so an
+     interleaved streaming script cannot break the adjacency. */
+  .demo-stack > :not(script):not(style):not(template) { display: block; margin-block: 0; }
+  .demo-stack > :not(script):not(style):not(template) ~ :not(script):not(style):not(template) { margin-block-start: var(--section-gap); }
+  /* <webjs-suspense> is display:contents while streaming (no box, so it would
+     drop its section gap). Force a block box so the gap applies; streaming only
+     moves its children, so a CSS-level display change does not affect it. */
+  .demo-stack > webjs-suspense { display: block !important; }
 `;
 
 // Shared layout for every gallery feature demo under /features/*. A docs-style

From 932c890f7da74e7e5919b8c68c47608d811a0354 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 19:48:07 +0530
Subject: [PATCH 52/73] =?UTF-8?q?style(gallery):=20more=20bottom=20spacing?=
 =?UTF-8?q?=20under=20the=20pinned=20'=E2=86=90=20Gallery'=20link?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Bump its mb-2 to mb-4 so the sidebar's back link is not cramped against the demo
list below it.
---
 packages/cli/templates/gallery/app/features/layout.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/cli/templates/gallery/app/features/layout.ts b/packages/cli/templates/gallery/app/features/layout.ts
index deec0d2d0..def2247e0 100644
--- a/packages/cli/templates/gallery/app/features/layout.ts
+++ b/packages/cli/templates/gallery/app/features/layout.ts
@@ -54,7 +54,7 @@ export default function FeaturesLayout({ children, url }: { children: unknown; u
            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-2 rounded-lg no-underline text-muted-foreground hover:text-foreground transition-colors">&larr; Gallery</a>
+        <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>

From 37e8aa71187f5602110023266df88785d501383e Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 19:53:32 +0530
Subject: [PATCH 53/73] fix(gallery): section rhythm via flex column, not
 forced display:block

The display:block on stack children clobbered a grid/flex direct child (the forms
card collapsed to block and distorted), and the :not() pseudos even out-specified
Tailwind's .grid. Switch the stack to a flex column with gap: it spaces sections
uniformly WITHOUT touching each child's display, so a grid/flex child keeps its
layout, an inline shadow host is blockified as a flex item (gets the gap), a
display:contents <webjs-suspense> is replaced by its children which become the
items (gap applies, no !important needed), and display:none scripts/templates are
not items (no phantom gap). Verified: forms grid intact, components + suspense +
routing all uniform 24px.
---
 .../templates/gallery/app/features/layout.ts  | 31 +++++++++----------
 1 file changed, 15 insertions(+), 16 deletions(-)

diff --git a/packages/cli/templates/gallery/app/features/layout.ts b/packages/cli/templates/gallery/app/features/layout.ts
index def2247e0..186c3715e 100644
--- a/packages/cli/templates/gallery/app/features/layout.ts
+++ b/packages/cli/templates/gallery/app/features/layout.ts
@@ -18,23 +18,22 @@ const SIDENAV_CSS = `
 
 // 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. It zeroes each direct child's own
-// block margins, then puts an equal gap before every child after the first. This
-// is the single place that controls demo spacing. A group that must stay tight (a
-// caption directly above its code) is wrapped in ONE child <div>, which keeps its
-// own inner spacing (the reset only reaches DIRECT children of .demo-stack).
+// 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; }
-  /* Space only RENDERED sections; skip streaming <script>/<style>/<template>
-     nodes (a forced-visible script would otherwise gain a phantom gap). block so
-     a shadow-DOM host (inline by default) honours the gap; ~ (not +) so an
-     interleaved streaming script cannot break the adjacency. */
-  .demo-stack > :not(script):not(style):not(template) { display: block; margin-block: 0; }
-  .demo-stack > :not(script):not(style):not(template) ~ :not(script):not(style):not(template) { margin-block-start: var(--section-gap); }
-  /* <webjs-suspense> is display:contents while streaming (no box, so it would
-     drop its section gap). Force a block box so the gap applies; streaming only
-     moves its children, so a CSS-level display change does not affect it. */
-  .demo-stack > webjs-suspense { display: block !important; }
+  .demo-stack {
+    --section-gap: 1.5rem;
+    display: flex;
+    flex-direction: column;
+    gap: var(--section-gap);
+  }
+  /* Zero any inline margins so ONLY the flex gap spaces sections. */
+  .demo-stack > * { margin: 0; }
 `;
 
 // Shared layout for every gallery feature demo under /features/*. A docs-style

From 3e40f28a39147993ae0dd157fe1fefdea4117d3d Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 19:58:20 +0530
Subject: [PATCH 54/73] fix(gallery): make the dark-mode border visible against
 the card fill

In dark mode --border (#34393e) was nearly identical to --card (#313539), so a
bg-card element with a border (an inactive secondary tab/button) looked
borderless until hovered. Lift the dark --border to #3d434b so the rest-state
border reads against the card, keeping --border-strong for the hover step.
---
 packages/cli/lib/create.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
index 3460c5b16..9aa27ec85 100644
--- a/packages/cli/lib/create.js
+++ b/packages/cli/lib/create.js
@@ -1225,7 +1225,7 @@ export default function RootLayout({ children }: { children: unknown }) {
         --muted-foreground:   light-dark(#565c64, #94989c);
         --accent:             light-dark(#e9ebef, #363a3e);
         --accent-foreground:  light-dark(#191c20, #f7fbff);
-        --border:             light-dark(#e2e5e9, #34393e);
+        --border:             light-dark(#e2e5e9, #3d434b);
         --border-strong:      light-dark(#ccd1d7, #454b51);
         --input:              light-dark(#e2e5e9, #34393e);
         --ring:               light-dark(#8b9198, #6b7075);

From 7563036ab8cd3a535ca3b15652ff08938a0f277d Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 20:02:02 +0530
Subject: [PATCH 55/73] fix(gallery): restore a clear hover step for the dark
 border

Lifting --border narrowed its gap to --border-strong, so a hover:border-strong
step was barely visible. Lift dark --border-strong to #545c66 so the hover border
is clearly stronger than the (now more visible) rest border.
---
 packages/cli/lib/create.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
index 9aa27ec85..16f1987e6 100644
--- a/packages/cli/lib/create.js
+++ b/packages/cli/lib/create.js
@@ -1226,7 +1226,7 @@ export default function RootLayout({ children }: { children: unknown }) {
         --accent:             light-dark(#e9ebef, #363a3e);
         --accent-foreground:  light-dark(#191c20, #f7fbff);
         --border:             light-dark(#e2e5e9, #3d434b);
-        --border-strong:      light-dark(#ccd1d7, #454b51);
+        --border-strong:      light-dark(#ccd1d7, #545c66);
         --input:              light-dark(#e2e5e9, #34393e);
         --ring:               light-dark(#8b9198, #6b7075);
         /* A translucent tint of the primary, tracked automatically across

From 64cf1eacbfd6fc1a4db54b66a8fec753847518ff Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 20:02:02 +0530
Subject: [PATCH 56/73] fix(gallery): themed focus ring for the shadow-DOM
 component's buttons

Tailwind's outline-none + focus ring do not cross the shadow boundary, so the
reactive-meter buttons fell back to the browser's default outline (thick, shown
on window-refocus, and light-coloured on a dark theme). Add a button:focus-visible
ring to the component's static styles so a shadow component owns its focus look,
matching the app's ring.
---
 .../gallery/modules/components/components/reactive-meter.ts   | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/packages/cli/templates/gallery/modules/components/components/reactive-meter.ts b/packages/cli/templates/gallery/modules/components/components/reactive-meter.ts
index 68f14f0b6..fbb6d69e2 100644
--- a/packages/cli/templates/gallery/modules/components/components/reactive-meter.ts
+++ b/packages/cli/templates/gallery/modules/components/components/reactive-meter.ts
@@ -13,6 +13,10 @@ export class ReactiveMeter extends WebComponent {
       padding: 6px 12px; border-radius: 10px; border: 1px solid var(--color-border);
       background: transparent; color: inherit; cursor: pointer; font: inherit;
     }
+    /* Tailwind's focus styles do NOT cross the shadow boundary, so a shadow-DOM
+       component styles its own focus, else the browser's default outline (thick,
+       shown on window-refocus) appears. Match the app's themed ring. */
+    button:focus-visible { outline: 2px solid var(--color-ring); outline-offset: 2px; }
     .val { font-variant-numeric: tabular-nums; font-weight: 600; }
     .muted { opacity: 0.6; font-size: 13px; }
   `;

From 75f2055add6bac559dad48b6d392ac58c7a7a19a Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 20:02:34 +0530
Subject: [PATCH 57/73] fix(gallery): revert dark --border-strong to #454b51

A subtle border -> border-strong hover step is consistent with light mode, so the
earlier lift over-corrected. Keep the --border rest-visibility fix; restore the
original border-strong.
---
 packages/cli/lib/create.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
index 16f1987e6..9aa27ec85 100644
--- a/packages/cli/lib/create.js
+++ b/packages/cli/lib/create.js
@@ -1226,7 +1226,7 @@ export default function RootLayout({ children }: { children: unknown }) {
         --accent:             light-dark(#e9ebef, #363a3e);
         --accent-foreground:  light-dark(#191c20, #f7fbff);
         --border:             light-dark(#e2e5e9, #3d434b);
-        --border-strong:      light-dark(#ccd1d7, #545c66);
+        --border-strong:      light-dark(#ccd1d7, #454b51);
         --input:              light-dark(#e2e5e9, #34393e);
         --ring:               light-dark(#8b9198, #6b7075);
         /* A translucent tint of the primary, tracked automatically across

From 64b3d7781e8dbcd01f31f9e73831ffbdb74be0b1 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 20:36:14 +0530
Subject: [PATCH 58/73] fix(gallery): buttons use the design-system global
 focus ring

buttonClass carried its own outline-none + box-shadow ring, so buttons showed a
different focus indicator than links/inputs (which use the design system's global
outline-ring/50). Drop the per-button focus so every element shares one themed,
keyboard-only, never-removed focus ring from the design system. Document that
convention in the ui theme, incl. the shadow-DOM caveat (a document rule can't
cross the shadow boundary, so a shadow component sets its own, as reactive-meter
now does). Verified: button + input + link all share the --ring/50 focus colour.
---
 packages/cli/templates/gallery/components/ui/button.ts | 4 +++-
 packages/ui/packages/registry/themes/index.css         | 4 ++++
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/packages/cli/templates/gallery/components/ui/button.ts b/packages/cli/templates/gallery/components/ui/button.ts
index ca1b3156c..68720737b 100644
--- a/packages/cli/templates/gallery/components/ui/button.ts
+++ b/packages/cli/templates/gallery/components/ui/button.ts
@@ -34,8 +34,10 @@ import { cn } from '#lib/utils/cn.ts';
 
 // BASE: shared by every variant + size, so a fix here (e.g. the focus ring, or
 // cursor-pointer) applies to the whole button system at once.
+// Focus is handled ONCE by the app's global :focus-visible ring (in the root
+// layout), so buttons need no per-element focus style here.
 const BASE =
-  'inline-flex shrink-0 cursor-pointer items-center justify-center gap-2 whitespace-nowrap text-sm transition-all outline-none focus-visible:ring-2 focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-60';
+  'inline-flex shrink-0 cursor-pointer items-center justify-center gap-2 whitespace-nowrap text-sm transition-all disabled:pointer-events-none disabled:opacity-60';
 
 // VARIANTS carry COLOR + weight + hover (what the button IS). Add a variant here
 // and it is instantly available to every demo.
diff --git a/packages/ui/packages/registry/themes/index.css b/packages/ui/packages/registry/themes/index.css
index cfdf60b69..93171ad45 100644
--- a/packages/ui/packages/registry/themes/index.css
+++ b/packages/ui/packages/registry/themes/index.css
@@ -135,6 +135,10 @@
 }
 
 @layer base {
+  /* Focus: a themed, keyboard-only (:focus-visible), never-removed outline, in
+     the --ring colour, applied globally (shadcn convention). A shadow-DOM
+     component sets its own focus (a document rule cannot cross the shadow
+     boundary). */
   * {
     @apply border-border outline-ring/50;
   }

From 5ff4a706db8358f091d751367aa58a8481117a4e Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 20:37:03 +0530
Subject: [PATCH 59/73] docs(skill): document the focus-ring convention (incl.
 shadow-DOM)

Explain the design-system focus model: one global themed keyboard-only outline
(outline-ring/50), never remove it (WCAG 2.4.7), don't re-add per-element, and
the shadow-DOM exception (a document rule can't cross the boundary, so a shadow
component styles its own :focus-visible).
---
 .agents/skills/webjs/references/styling.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.agents/skills/webjs/references/styling.md b/.agents/skills/webjs/references/styling.md
index 7ebf389f1..7d630f50d 100644
--- a/.agents/skills/webjs/references/styling.md
+++ b/.agents/skills/webjs/references/styling.md
@@ -138,6 +138,8 @@ The default stack is a static compiled Tailwind stylesheet (`css:build` compiles
 
 **The ui class helpers build on these tokens.** `buttonClass()` / `cardClass()` / `inputClass()` / `badgeClass()` emit Tailwind utilities that reference the same tokens (`bg-primary`, `border-border`), so theming the tokens re-skins every helper at once.
 
+**Focus rings.** The design system applies ONE themed, keyboard-only focus ring globally (the shadcn convention `@layer base { * { @apply border-border outline-ring/50 } }` in the theme CSS), so every focusable element (button, link, input) shares a `--ring`-coloured `:focus-visible` outline with no per-element styling. Do NOT re-add a focus style on a light-DOM element (`buttonClass` deliberately carries none), and NEVER remove it (`outline: none` with no replacement fails WCAG 2.4.7). `:focus-visible` already limits the ring to keyboard / programmatic focus, not a mouse click. A SHADOW-DOM component is the ONE exception: a document rule cannot cross the shadow boundary, so it styles its own focus in `static styles` (`button:focus-visible { outline: 2px solid var(--color-ring); outline-offset: 2px }`); without it, its controls fall back to the raw browser outline (thick, light on a dark theme, and shown on window-refocus).
+
 ## Light-DOM host display, and shadow hosts
 
 A custom element is `display: inline` in plain CSS, which collapses a component used as a block container to its content size. WebJs marks every LIGHT-DOM host `data-wj-host` and defaults it to `display: block` via one head rule in a low-priority cascade layer (`@layer webjs-host { :where([data-wj-host]) { display: block } }`), so a container component does not collapse. The layer keeps it overridable: any author style INCLUDING a Tailwind utility (`class="flex"`, `grid`, `hidden`) wins over it, and `[hidden]` still hides the host so `?hidden=${cond}` works. Opt into an inline light component with a tag-prefixed rule (`my-badge { display: inline }`).

From d5a7e7a8b182a513b05608c51e1bb106473157af Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 21:24:38 +0530
Subject: [PATCH 60/73] fix(gallery): shadow focus ring matches the
 design-system --ring/50

The reactive-meter's own focus outline used FULL --color-ring while the global
design-system ring (outline-ring/50) is --ring at 50%, so the shadow ring was
more opaque than everything else. Use color-mix(--color-ring 50%) to match it
exactly; update the skill doc to the same. Verified: light-DOM and shadow focus
colours are now identical.
---
 .agents/skills/webjs/references/styling.md                | 2 +-
 .../modules/components/components/reactive-meter.ts       | 8 ++++++--
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/.agents/skills/webjs/references/styling.md b/.agents/skills/webjs/references/styling.md
index 7d630f50d..e0eb6422b 100644
--- a/.agents/skills/webjs/references/styling.md
+++ b/.agents/skills/webjs/references/styling.md
@@ -138,7 +138,7 @@ The default stack is a static compiled Tailwind stylesheet (`css:build` compiles
 
 **The ui class helpers build on these tokens.** `buttonClass()` / `cardClass()` / `inputClass()` / `badgeClass()` emit Tailwind utilities that reference the same tokens (`bg-primary`, `border-border`), so theming the tokens re-skins every helper at once.
 
-**Focus rings.** The design system applies ONE themed, keyboard-only focus ring globally (the shadcn convention `@layer base { * { @apply border-border outline-ring/50 } }` in the theme CSS), so every focusable element (button, link, input) shares a `--ring`-coloured `:focus-visible` outline with no per-element styling. Do NOT re-add a focus style on a light-DOM element (`buttonClass` deliberately carries none), and NEVER remove it (`outline: none` with no replacement fails WCAG 2.4.7). `:focus-visible` already limits the ring to keyboard / programmatic focus, not a mouse click. A SHADOW-DOM component is the ONE exception: a document rule cannot cross the shadow boundary, so it styles its own focus in `static styles` (`button:focus-visible { outline: 2px solid var(--color-ring); outline-offset: 2px }`); without it, its controls fall back to the raw browser outline (thick, light on a dark theme, and shown on window-refocus).
+**Focus rings.** The design system applies ONE themed, keyboard-only focus ring globally (the shadcn convention `@layer base { * { @apply border-border outline-ring/50 } }` in the theme CSS), so every focusable element (button, link, input) shares a `--ring`-coloured `:focus-visible` outline with no per-element styling. Do NOT re-add a focus style on a light-DOM element (`buttonClass` deliberately carries none), and NEVER remove it (`outline: none` with no replacement fails WCAG 2.4.7). `:focus-visible` already limits the ring to keyboard / programmatic focus, not a mouse click. A SHADOW-DOM component is the ONE exception: a document rule cannot cross the shadow boundary, so it styles its own focus in `static styles`, matching the global ring EXACTLY (`--ring` at 50%, the same as `outline-ring/50`): `button:focus-visible { outline: 2px solid color-mix(in oklab, var(--color-ring) 50%, transparent); outline-offset: 2px }`. Without it, its controls fall back to the raw browser outline (thick, light on a dark theme, and shown on window-refocus).
 
 ## Light-DOM host display, and shadow hosts
 
diff --git a/packages/cli/templates/gallery/modules/components/components/reactive-meter.ts b/packages/cli/templates/gallery/modules/components/components/reactive-meter.ts
index fbb6d69e2..16ec6402f 100644
--- a/packages/cli/templates/gallery/modules/components/components/reactive-meter.ts
+++ b/packages/cli/templates/gallery/modules/components/components/reactive-meter.ts
@@ -15,8 +15,12 @@ export class ReactiveMeter extends WebComponent {
     }
     /* Tailwind's focus styles do NOT cross the shadow boundary, so a shadow-DOM
        component styles its own focus, else the browser's default outline (thick,
-       shown on window-refocus) appears. Match the app's themed ring. */
-    button:focus-visible { outline: 2px solid var(--color-ring); outline-offset: 2px; }
+       shown on window-refocus) appears. Match the design system's global ring
+       EXACTLY: the --ring colour at 50% (the same as outline-ring/50). */
+    button:focus-visible {
+      outline: 2px solid color-mix(in oklab, var(--color-ring) 50%, transparent);
+      outline-offset: 2px;
+    }
     .val { font-variant-numeric: tabular-nums; font-weight: 600; }
     .muted { opacity: 0.6; font-size: 13px; }
   `;

From 0066c71fbe3f8c4cfcd32394d7fdccc1ebd998e2 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 21:32:40 +0530
Subject: [PATCH 61/73] fix(gallery): force a SOLID focus outline so the themed
 colour renders

outline-ring/50 themed only the outline COLOUR and left outline-style: auto, so
the browser drew its own focus ring (thick, white on some platforms) and ignored
the colour, every light-DOM button showed that white ring while the shadow
reactive-meter (which already had an explicit solid outline) looked correct.
Add a global :focus-visible { outline: 2px solid color-mix(--color-ring 50%);
outline-offset: 2px } to the ui theme so the themed --ring/50 ring actually
renders on every element. Verified: the directives Add button is now themed, not
white. (A native button renders it a touch wider than a link, a Chromium
form-control quirk, but the colour matches.)
---
 .agents/skills/webjs/references/styling.md     |  2 +-
 packages/ui/packages/registry/themes/index.css | 13 ++++++++++---
 2 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/.agents/skills/webjs/references/styling.md b/.agents/skills/webjs/references/styling.md
index e0eb6422b..db2f8a17a 100644
--- a/.agents/skills/webjs/references/styling.md
+++ b/.agents/skills/webjs/references/styling.md
@@ -138,7 +138,7 @@ The default stack is a static compiled Tailwind stylesheet (`css:build` compiles
 
 **The ui class helpers build on these tokens.** `buttonClass()` / `cardClass()` / `inputClass()` / `badgeClass()` emit Tailwind utilities that reference the same tokens (`bg-primary`, `border-border`), so theming the tokens re-skins every helper at once.
 
-**Focus rings.** The design system applies ONE themed, keyboard-only focus ring globally (the shadcn convention `@layer base { * { @apply border-border outline-ring/50 } }` in the theme CSS), so every focusable element (button, link, input) shares a `--ring`-coloured `:focus-visible` outline with no per-element styling. Do NOT re-add a focus style on a light-DOM element (`buttonClass` deliberately carries none), and NEVER remove it (`outline: none` with no replacement fails WCAG 2.4.7). `:focus-visible` already limits the ring to keyboard / programmatic focus, not a mouse click. A SHADOW-DOM component is the ONE exception: a document rule cannot cross the shadow boundary, so it styles its own focus in `static styles`, matching the global ring EXACTLY (`--ring` at 50%, the same as `outline-ring/50`): `button:focus-visible { outline: 2px solid color-mix(in oklab, var(--color-ring) 50%, transparent); outline-offset: 2px }`. Without it, its controls fall back to the raw browser outline (thick, light on a dark theme, and shown on window-refocus).
+**Focus rings.** The design system applies ONE themed, keyboard-only focus ring globally in the theme CSS: `@layer base { * { @apply border-border outline-ring/50 } }` themes the outline COLOUR to `--ring/50`, and a `:focus-visible { outline: 2px solid color-mix(in oklab, var(--color-ring) 50%, transparent); outline-offset: 2px }` forces a SOLID outline. That second rule matters: `outline-ring/50` alone leaves `outline-style: auto`, so the browser draws its OWN focus ring (which can look thick and white and ignore the colour). So every focusable element (button, link, input) shares one `--ring`-coloured ring with no per-element styling (a native `<button>` renders it a touch wider than a link, a Chromium form-control quirk, but the colour is the same). Do NOT re-add a focus style on a light-DOM element (`buttonClass` deliberately carries none), and NEVER remove it (`outline: none` with no replacement fails WCAG 2.4.7). `:focus-visible` already limits the ring to keyboard / programmatic focus, not a mouse click. A SHADOW-DOM component is the ONE exception: a document rule cannot cross the shadow boundary, so it styles its own focus in `static styles`, matching the global ring EXACTLY (`--ring` at 50%, the same as `outline-ring/50`): `button:focus-visible { outline: 2px solid color-mix(in oklab, var(--color-ring) 50%, transparent); outline-offset: 2px }`. Without it, its controls fall back to the raw browser outline (thick, light on a dark theme, and shown on window-refocus).
 
 ## Light-DOM host display, and shadow hosts
 
diff --git a/packages/ui/packages/registry/themes/index.css b/packages/ui/packages/registry/themes/index.css
index 93171ad45..e368f6f48 100644
--- a/packages/ui/packages/registry/themes/index.css
+++ b/packages/ui/packages/registry/themes/index.css
@@ -136,10 +136,17 @@
 
 @layer base {
   /* Focus: a themed, keyboard-only (:focus-visible), never-removed outline, in
-     the --ring colour, applied globally (shadcn convention). A shadow-DOM
-     component sets its own focus (a document rule cannot cross the shadow
-     boundary). */
+     the --ring colour, applied globally. `outline-ring/50` themes only the
+     COLOUR and leaves outline-style: auto, which the browser draws as its OWN
+     ring (it can look thick/white and ignore the colour). So force a SOLID
+     outline on focus, at a consistent width + offset, so the themed --ring/50
+     colour actually renders the same on every element. A shadow-DOM component
+     sets its own focus (a document rule cannot cross the shadow boundary). */
   * {
     @apply border-border outline-ring/50;
   }
+  :focus-visible {
+    outline: 2px solid color-mix(in oklab, var(--color-ring) 50%, transparent);
+    outline-offset: 2px;
+  }
 }

From 963e1c0cdcfdce28efdd0f33b1924730f60eb908 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 21:59:44 +0530
Subject: [PATCH 62/73] fix(scaffold): favicon actually shows (emit the link
 into <head>)

The layout hand-wrote <link rel=icon> in its template body, and the framework
splices only importmap/title/meta into <head>, so the icon link stayed in <body>
where browsers ignore it, the favicon never rendered (and app/icon.ts is not
auto-linked, /favicon.ico maps to a .ico the scaffold does not ship). Declare it
via metadata.icons instead, which the framework emits into <head>; fix both the
gallery layout and the gallery:clear MINIMAL_LAYOUT. Re-draw favicon.svg to match
the navbar brand mark (neutral foreground->muted-foreground gradient rounded
square, not the old chevron). Add a regression test (metadata.icons present, no
body <link rel=icon>, favicon.svg shipped). Verified in-browser: link in <head>,
serves 200, renders the neutral mark.
---
 packages/cli/lib/create.js                       |  8 +++++++-
 packages/cli/templates/public/favicon.svg        | 12 +++++++++---
 packages/cli/templates/scripts/clear-gallery.mjs |  6 +++++-
 test/scaffolds/scaffold-integration.test.js      |  9 +++++++++
 4 files changed, 30 insertions(+), 5 deletions(-)

diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
index 9aa27ec85..556b300bd 100644
--- a/packages/cli/lib/create.js
+++ b/packages/cli/lib/create.js
@@ -1120,6 +1120,13 @@ import '#components/theme-toggle.ts';
  * mapped into Tailwind via @theme in public/input.css, so bg-background,
  * text-foreground, bg-card, bg-primary, and border-border all work.
  */
+
+// Declare the favicon via metadata.icons (NOT a hand-written <link> in the
+// template): the framework emits metadata links into <head>, whereas a <link>
+// written in the layout body stays in <body>, where browsers ignore it. The SVG
+// lives at public/favicon.svg and serves at /public/favicon.svg.
+export const metadata = { icons: '/public/favicon.svg' };
+
 export default function RootLayout({ children }: { children: unknown }) {
   // Read the in-flight request's CSP nonce so the theme-detection inline script
   // passes strict CSP. Returns '' when no CSP nonce is set.
@@ -1169,7 +1176,6 @@ export default function RootLayout({ children }: { children: unknown }) {
       })();
     </script>
     <meta name="color-scheme" content="light dark">
-    <link rel="icon" href="/public/favicon.svg" type="image/svg+xml">
     <!-- JetBrains Mono for body/UI (its monospaced, developer-console feel) and
          Bricolage Grotesque for the display wordmark. Swap these for your own
          fonts (and update --font-sans / --font-display below). -->
diff --git a/packages/cli/templates/public/favicon.svg b/packages/cli/templates/public/favicon.svg
index 1bc26f829..49fcef6e7 100644
--- a/packages/cli/templates/public/favicon.svg
+++ b/packages/cli/templates/public/favicon.svg
@@ -1,5 +1,11 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" width="32" height="32" role="img" aria-label="WebJs">
-  <rect width="32" height="32" rx="7" fill="#e9edf0"/>
-  <path d="M8 11.5l4.5 4.5L8 20.5" fill="none" stroke="#1e2226" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round"/>
-  <line x1="15.5" y1="21.5" x2="23" y2="21.5" stroke="#1e2226" stroke-width="2.6" stroke-linecap="round"/>
+  <!-- Matches the gallery navbar brand mark: a rounded square with a neutral
+       foreground -> muted-foreground gradient (bg-gradient-to-br). -->
+  <defs>
+    <linearGradient id="wj" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#191c20"/>
+      <stop offset="1" stop-color="#565c64"/>
+    </linearGradient>
+  </defs>
+  <rect width="32" height="32" rx="10" fill="url(#wj)"/>
 </svg>
diff --git a/packages/cli/templates/scripts/clear-gallery.mjs b/packages/cli/templates/scripts/clear-gallery.mjs
index d31e4d7ea..e950bb182 100644
--- a/packages/cli/templates/scripts/clear-gallery.mjs
+++ b/packages/cli/templates/scripts/clear-gallery.mjs
@@ -170,10 +170,14 @@ function MINIMAL_LAYOUT() {
  * .agents/skills/webjs/references/styling.md. Run \\\`npx webjsdev ui add <name>\\\`
  * to pull primitives, then theme them here.
  */
+
+// Favicon via metadata.icons so the framework emits the <link> into <head> (a
+// hand-written <link> in the template body is ignored by browsers).
+export const metadata = { icons: '/public/favicon.svg' };
+
 export default function RootLayout({ children }: { children: unknown }) {
   return html\`
     <meta name="color-scheme" content="light dark">
-    <link rel="icon" href="/public/favicon.svg" type="image/svg+xml">
     <link rel="stylesheet" href="/public/tailwind.css">
     <style>
       html, body { margin: 0; }
diff --git a/test/scaffolds/scaffold-integration.test.js b/test/scaffolds/scaffold-integration.test.js
index 023512342..a440e4ef1 100644
--- a/test/scaffolds/scaffold-integration.test.js
+++ b/test/scaffolds/scaffold-integration.test.js
@@ -131,6 +131,15 @@ test('scaffoldApp full-stack: writes the canonical full-stack app layout', async
     assert.doesNotMatch(layoutSrc, /oklch\(0\.7 0\.16 52\)/,
       'no orange brand color survives in the neutral scaffold');
 
+    // Favicon: declared via metadata.icons (the framework emits it into <head>).
+    // A hand-written <link rel="icon"> in the layout body lands in <body>, where
+    // browsers ignore it, the recurring "favicon never shows" bug this guards.
+    assert.match(layoutSrc, /export const metadata = \{ icons: '\/public\/favicon\.svg' \}/,
+      'layout declares the favicon via metadata.icons');
+    assert.doesNotMatch(layoutSrc, /<link rel="icon"/,
+      'layout must NOT hand-write a <link rel=icon> (it lands in <body>, ignored)');
+    assert.ok(existsSync(join(appDir, 'public', 'favicon.svg')), 'ships public/favicon.svg');
+
     // The home page is a gallery index: an 'Explore the gallery' hero, a grid
     // linking every feature demo + the example app, and a footer with the docs +
     // source links.

From f36cbfcdb9e4443f4d417e6f6d067bfa578cc026 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 22:10:53 +0530
Subject: [PATCH 63/73] fix(gallery): favicon uses the dark-theme brand mark

Switch the favicon gradient to the DARK-theme token values (#dee2e6 -> #94989c,
foreground -> muted-foreground in dark) so it reads on a dark browser tab bar,
matching how the navbar mark looks in dark mode.
---
 packages/cli/templates/public/favicon.svg | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/packages/cli/templates/public/favicon.svg b/packages/cli/templates/public/favicon.svg
index 49fcef6e7..18151a183 100644
--- a/packages/cli/templates/public/favicon.svg
+++ b/packages/cli/templates/public/favicon.svg
@@ -1,10 +1,11 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" width="32" height="32" role="img" aria-label="WebJs">
-  <!-- Matches the gallery navbar brand mark: a rounded square with a neutral
-       foreground -> muted-foreground gradient (bg-gradient-to-br). -->
+  <!-- Matches the gallery navbar brand mark (a rounded square with a
+       foreground -> muted-foreground gradient), using the DARK-theme token
+       values (#dee2e6 -> #94989c) so it reads on a dark browser tab bar. -->
   <defs>
     <linearGradient id="wj" x1="0" y1="0" x2="1" y2="1">
-      <stop offset="0" stop-color="#191c20"/>
-      <stop offset="1" stop-color="#565c64"/>
+      <stop offset="0" stop-color="#dee2e6"/>
+      <stop offset="1" stop-color="#94989c"/>
     </linearGradient>
   </defs>
   <rect width="32" height="32" rx="10" fill="url(#wj)"/>

From e401f376ab4586e71d80f46468ce9a9f37931fb9 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 22:11:09 +0530
Subject: [PATCH 64/73] fix(server): hoist <meta> so it doesn't strand head
 tags in <body>

The head-tag hoister (whose stated purpose is to put a layout's leading
<link rel=icon>/<link rel=stylesheet> into <head> where browsers honour them)
matched <script>/<style>/<link>/comments but NOT <meta>. A <meta> in the leading
run (e.g. the scaffold's <meta name=color-scheme> between the theme <script> and
the stylesheet <link>) terminated the run, stranding the favicon <link> (ignored
by browsers in <body>, so it never rendered) and the stylesheet (FOUC) in <body>.
<meta> is void like <link>; add it to the run regex, exactly as #406 did for
comments. Definitively a framework bug: a framework-only change hoists the
scaffold's stranded tags, proven by a counterfactual test that fails without it.

Runtime-agnostic (a pure regex in the shared Node+Bun SSR string path); covered
by the Node unit test + counterfactual. No regressions across 263 SSR + scaffold
tests.
---
 packages/server/src/ssr.js                  | 20 +++++++++-------
 packages/server/test/ssr/head-hoist.test.js | 26 +++++++++++++++++++++
 2 files changed, 38 insertions(+), 8 deletions(-)

diff --git a/packages/server/src/ssr.js b/packages/server/src/ssr.js
index 367d78d91..bad391411 100644
--- a/packages/server/src/ssr.js
+++ b/packages/server/src/ssr.js
@@ -1124,18 +1124,22 @@ function wrapInDocument(body, opts) {
  */
 function collectHoistedHeadTags(bodyHtml) {
   const tags = [];
-  // <script>…</script> and <style>…</style> are paired; <link …> is void.
-  // A plain HTML comment (<!-- … -->) is consumed but NOT hoisted, so a
-  // comment interleaved with head-bound tags (e.g. "<!-- Self-hosted fonts -->"
+  // <script>…</script> and <style>…</style> are paired; <link …> and <meta …>
+  // are void. A plain HTML comment (<!-- … -->) is consumed but NOT hoisted, so
+  // a comment interleaved with head-bound tags (e.g. "<!-- Self-hosted fonts -->"
   // between a favicon <link> and the stylesheet <link>) does not terminate
   // the leading run and strand the stylesheet in <body>, which caused FOUC
   // because a <link rel="stylesheet"> in <body> is not reliably
-  // render-blocking (#406). The `(?!/?wj:)` guard exempts client-router
-  // markers (<!--wj:children:…-->, <!--/wj:children-->) so a layout that
-  // renders children directly after its head tags still terminates the run
-  // there rather than swallowing the nesting marker.
+  // render-blocking (#406). A <meta …> is treated the same way for the same
+  // reason: a <meta name="color-scheme"> between the theme <script> and the
+  // stylesheet <link> would otherwise terminate the run and strand the
+  // stylesheet AND a <link rel="icon"> in <body> (a favicon in <body> is
+  // ignored by browsers, so the icon silently never renders). The `(?!/?wj:)`
+  // guard exempts client-router markers (<!--wj:children:…-->,
+  // <!--/wj:children-->) so a layout that renders children directly after its
+  // head tags still terminates the run there rather than swallowing the marker.
   const re =
-    /^\s*(<!--(?!\/?wj:)[\s\S]*?-->|<script[\s>][\s\S]*?<\/script>|<style[\s>][\s\S]*?<\/style>|<link\b[^>]*>)/i;
+    /^\s*(<!--(?!\/?wj:)[\s\S]*?-->|<script[\s>][\s\S]*?<\/script>|<style[\s>][\s\S]*?<\/style>|<link\b[^>]*>|<meta\b[^>]*>)/i;
   let remaining = bodyHtml;
   // `body` only advances to just-past the LAST hoisted head tag. Comments
   // are scanned through (so they don't terminate the run) but a comment that
diff --git a/packages/server/test/ssr/head-hoist.test.js b/packages/server/test/ssr/head-hoist.test.js
index aaa2cf72e..e1cf67594 100644
--- a/packages/server/test/ssr/head-hoist.test.js
+++ b/packages/server/test/ssr/head-hoist.test.js
@@ -70,6 +70,32 @@ test('multiple comments interleaved still hoist every tag', () => {
   assert.equal(out.includes('rel="stylesheet"'), false);
 });
 
+test('a <meta> between head-bound tags does NOT strand the later tags (favicon + stylesheet)', () => {
+  // The scaffold layout writes the theme <script>, then <meta name="color-scheme">,
+  // then the favicon <link> + the Tailwind stylesheet + the token <style>. A
+  // <meta> is void like a <link>, so it must be hoisted (not terminate the run),
+  // or the favicon lands in <body> (browsers ignore it, so it never renders) and
+  // the stylesheet + styles strand (FOUC). Fails without <meta> in the hoist regex.
+  const body =
+    '<script>/*theme*/</script>' +
+    '<meta name="color-scheme" content="light dark">' +
+    '<link rel="icon" href="/public/favicon.svg" type="image/svg+xml">' +
+    '<link rel="stylesheet" href="/public/tailwind.css">' +
+    '<style>:root{--x:1}</style>' +
+    '<main>content</main>';
+  const { head, body: out } = _hoistHeadTags(HEAD, body);
+
+  assert.ok(head.includes('name="color-scheme"'), 'meta hoisted');
+  assert.ok(head.includes('rel="icon"'), 'favicon hoisted past the meta');
+  assert.ok(head.includes('rel="stylesheet"'), 'stylesheet hoisted past the meta');
+  assert.ok(head.includes('<style>:root{--x:1}</style>'), 'token style hoisted');
+
+  assert.equal(out.includes('rel="icon"'), false, 'favicon must not stay in body');
+  assert.equal(out.includes('rel="stylesheet"'), false, 'stylesheet must not strand (FOUC)');
+  assert.equal((out.match(/name="color-scheme"/g) || []).length, 0, 'meta not duplicated into the body');
+  assert.ok(out.includes('<main>content</main>'));
+});
+
 test('a webjs client-router marker terminates the run (not swallowed)', () => {
   // A pathological layout that renders children right after its head tags:
   // the <!--wj:children:…--> marker must stay in the body so the client

From bd6b49e77dfecd6ff08db2a3b78bf03476c5b090 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 23:22:33 +0530
Subject: [PATCH 65/73] docs(skill): sync styling.md with the gallery (border
 hex, section rhythm)

The light-dark example's dark --border drifted from the gallery's #3d434b (the
dark-border visibility fix), and the section-rhythm stack pattern the gallery's
features layout now uses (one flex gap, children margins zeroed, the display
edge cases) was taught nowhere. Sync the hex and add the pattern with the
gallery as the worked example.
---
 .agents/skills/webjs/references/styling.md | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/.agents/skills/webjs/references/styling.md b/.agents/skills/webjs/references/styling.md
index db2f8a17a..9759ff2e2 100644
--- a/.agents/skills/webjs/references/styling.md
+++ b/.agents/skills/webjs/references/styling.md
@@ -120,7 +120,7 @@ The default stack is a static compiled Tailwind stylesheet (`css:build` compiles
     --foreground:       light-dark(#191c20, #dee2e6);
     --card:             light-dark(#f7f8fa, #313539);
     --muted-foreground: light-dark(#565c64, #94989c);
-    --border:           light-dark(#e2e5e9, #34393e);
+    --border:           light-dark(#e2e5e9, #3d434b);
     --primary:          light-dark(#1e2226, #dee2e6);
     /* a derived token tracks BOTH themes for free via var(--primary) */
     --primary-tint: color-mix(in srgb, var(--primary) 22%, transparent);
@@ -152,6 +152,17 @@ static styles = css`:host { display: block }`;   // a shadow host with no :host
 
 **Size the HOST, not just an inner wrapper.** The host custom element is the box the parent lays out. A host that is a flex/grid item in a centering parent (`flex justify-center`, `grid place-items-center`) is sized to its content unless it carries width itself. Put the sizing classes on the host (`w-full max-w-[400px]`), not only on an inner `<div>`. Symptom: a board or card renders tiny even though its inner grid says `w-full max-w-[400px]`. Fix: move the sizing onto the host.
 
+## Section rhythm: one gap, defined once
+
+Per-element margins can never give consistent vertical spacing: each element controls only one side, so a block's gap-above (the previous element's margin) drifts from its gap-below (its own). For a content column (a docs page, a demo page, an article), make the COLUMN own the spacing with a flex stack, and zero the children's own margins so only the one gap applies:
+
+```css
+.stack { --section-gap: 1.5rem; display: flex; flex-direction: column; gap: var(--section-gap); }
+.stack > * { margin: 0; }
+```
+
+Every top-level child (heading, paragraph, component, list) is then equally spaced from ONE variable, and a spacing change is a one-line edit. Flex `gap` beats forcing `display: block` + margins on children: a `grid`/`flex` child keeps its own layout (a blanket `display: block` clobbers it), an inline shadow-DOM host is blockified as a flex item so it honours the gap, a `display: contents` element (a streaming `<webjs-suspense>`) is replaced by its children which become the flex items, and a `display: none` node (a streaming `<script>`/`<template>`) is not an item at all, so it gets no phantom gap. A group that must stay tight (a caption directly above its code block) wraps in one child `<div>` and keeps its own inner spacing. The gallery's `/features` layout (`demo-stack`) is the worked example.
+
 ## Even grids, no reflow
 
 The reflow bug (a cell grows when it gets content while the others shrink) comes from `auto`-sized grid rows. Size the tracks explicitly so every cell is an equal fraction regardless of content:

From 874a9b6e657e21340f2536375cad627c58d54c83 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 23:28:06 +0530
Subject: [PATCH 66/73] fix(gallery): metadata routes use the neutral palette,
 drop dead comments

The icon / apple-icon / OG / twitter-image / manifest / global-error files still
carried the OLD amber-on-brown brand (#1c1613 / #ff8a3d / #f5f0eb) while the app
went neutral, so the favicon route, social cards, manifest theme_color, and the
last-resort error page clashed with the actual look. Sync them to the neutral
dark tokens (#1e2226 surface, #dee2e6 foreground, #94989c muted). These files
legitimately hardcode values (metadata routes emit static assets; global-error
must not depend on the token system), only the values were stale. Also strip the
dangling head comments referencing the retired placeholder-marker gate (they
started mid-sentence after the marker line itself was removed). All 7 routes
verified serving 200 with the new palette; check + typecheck pass.
---
 packages/cli/templates/gallery/app/apple-icon.ts       | 7 ++-----
 packages/cli/templates/gallery/app/global-error.ts     | 7 ++-----
 packages/cli/templates/gallery/app/global-not-found.ts | 3 ---
 packages/cli/templates/gallery/app/icon.ts             | 7 ++-----
 packages/cli/templates/gallery/app/manifest.ts         | 5 +----
 packages/cli/templates/gallery/app/opengraph-image.ts  | 9 +++------
 packages/cli/templates/gallery/app/robots.ts           | 3 ---
 packages/cli/templates/gallery/app/sitemap.ts          | 3 ---
 packages/cli/templates/gallery/app/twitter-image.ts    | 9 +++------
 9 files changed, 13 insertions(+), 40 deletions(-)

diff --git a/packages/cli/templates/gallery/app/apple-icon.ts b/packages/cli/templates/gallery/app/apple-icon.ts
index f46a87e9b..4b63111df 100644
--- a/packages/cli/templates/gallery/app/apple-icon.ts
+++ b/packages/cli/templates/gallery/app/apple-icon.ts
@@ -1,14 +1,11 @@
-// (delete this file), then delete this marker line. webjs check fails while the
-// marker remains.
-//
 // app/apple-icon.ts serves /apple-icon (the Apple touch icon iOS uses when a
 // visitor adds the site to their home screen). Apple expects a 180x180 square
 // with no rounded corners (iOS rounds them). Same shape as icon.ts: return a
 // Response with the exact content type. Swap the inline SVG for your real mark.
 export default function AppleIcon() {
   const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="180" height="180" viewBox="0 0 180 180">
-    <rect width="180" height="180" fill="#1c1613"/>
-    <text x="90" y="120" font-family="system-ui, sans-serif" font-size="104" font-weight="700" fill="#ff8a3d" text-anchor="middle">w</text>
+    <rect width="180" height="180" fill="#1e2226"/>
+    <text x="90" y="120" font-family="system-ui, sans-serif" font-size="104" 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' },
diff --git a/packages/cli/templates/gallery/app/global-error.ts b/packages/cli/templates/gallery/app/global-error.ts
index aeea6561e..3e46e3433 100644
--- a/packages/cli/templates/gallery/app/global-error.ts
+++ b/packages/cli/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>
diff --git a/packages/cli/templates/gallery/app/global-not-found.ts b/packages/cli/templates/gallery/app/global-not-found.ts
index 80405c4d2..565b20c14 100644
--- a/packages/cli/templates/gallery/app/global-not-found.ts
+++ b/packages/cli/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
diff --git a/packages/cli/templates/gallery/app/icon.ts b/packages/cli/templates/gallery/app/icon.ts
index 4d62628ef..676e391b4 100644
--- a/packages/cli/templates/gallery/app/icon.ts
+++ b/packages/cli/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' },
diff --git a/packages/cli/templates/gallery/app/manifest.ts b/packages/cli/templates/gallery/app/manifest.ts
index 01007f43a..db245d5ea 100644
--- a/packages/cli/templates/gallery/app/manifest.ts
+++ b/packages/cli/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' },
     ],
diff --git a/packages/cli/templates/gallery/app/opengraph-image.ts b/packages/cli/templates/gallery/app/opengraph-image.ts
index be55b3399..9d0a0cab1 100644
--- a/packages/cli/templates/gallery/app/opengraph-image.ts
+++ b/packages/cli/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' },
diff --git a/packages/cli/templates/gallery/app/robots.ts b/packages/cli/templates/gallery/app/robots.ts
index 4638c5880..271d8a7c9 100644
--- a/packages/cli/templates/gallery/app/robots.ts
+++ b/packages/cli/templates/gallery/app/robots.ts
@@ -1,6 +1,3 @@
-// (delete this file), then delete this marker line. webjs check fails while the
-// marker remains.
-//
 // app/robots.ts serves /robots.txt. The default export returns a string (served
 // as text/plain) or an object. This example allows all crawlers and points them
 // at the sitemap. Tighten the rules (Disallow paths) for a real app.
diff --git a/packages/cli/templates/gallery/app/sitemap.ts b/packages/cli/templates/gallery/app/sitemap.ts
index f00f513f4..f65fb47d0 100644
--- a/packages/cli/templates/gallery/app/sitemap.ts
+++ b/packages/cli/templates/gallery/app/sitemap.ts
@@ -1,6 +1,3 @@
-// routes, or prune it (delete this file), then delete this marker line. webjs
-// check fails while the marker remains.
-//
 // app/sitemap.ts serves /sitemap.xml. The default export is a (possibly async)
 // server function; `sitemap(entries)` from @webjsdev/server serializes a
 // spec-valid XML sitemap. In a real app, build the entries from your content
diff --git a/packages/cli/templates/gallery/app/twitter-image.ts b/packages/cli/templates/gallery/app/twitter-image.ts
index 440b074f6..c7e6b237b 100644
--- a/packages/cli/templates/gallery/app/twitter-image.ts
+++ b/packages/cli/templates/gallery/app/twitter-image.ts
@@ -1,6 +1,3 @@
-// (delete this file), then delete this marker line. webjs check fails while the
-// marker remains.
-//
 // app/twitter-image.ts serves /twitter-image (the card image shown when the
 // site is shared on Twitter/X). Its own route so the Twitter card can differ
 // from the Open Graph image (opengraph-image.ts); when they are identical, drop
@@ -8,9 +5,9 @@
 // roughly 1200x630. Reference it via metadata `twitter: { images: [...] }`.
 export default function TwitterImage() {
   const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630" viewBox="0 0 1200 630">
-    <rect width="1200" height="630" fill="#1c1613"/>
-    <text x="80" y="330" font-family="system-ui, sans-serif" font-size="88" font-weight="700" fill="#f5f0eb">My App</text>
-    <text x="80" y="410" font-family="system-ui, sans-serif" font-size="36" fill="#ff8a3d">Build on the platform, not against it</text>
+    <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' },

From 7f60ccb6adb06e44ba5fb5059495eb8f54773398 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 23:33:41 +0530
Subject: [PATCH 67/73] docs(scaffold): rule files match the token-free
 gallery:clear blank slate

The shipped AGENTS.md + workflow.md still said gallery:clear keeps 'the layout'
and told the agent to theme 'via the tokens in app/layout.ts', contradicting the
reset (the layout is overwritten to a token-free Canvas/CanvasText blank slate,
and the design system + tests are removed too). Sync both in lockstep: list what
is actually removed vs kept, and point the build step at defining tokens from
scratch guided by the skill.
---
 packages/cli/templates/.agents/rules/workflow.md |  9 ++++++---
 packages/cli/templates/AGENTS.md                 | 15 ++++++++++-----
 2 files changed, 16 insertions(+), 8 deletions(-)

diff --git a/packages/cli/templates/.agents/rules/workflow.md b/packages/cli/templates/.agents/rules/workflow.md
index 0172f2f83..afee4c6a0 100644
--- a/packages/cli/templates/.agents/rules/workflow.md
+++ b/packages/cli/templates/.agents/rules/workflow.md
@@ -16,7 +16,8 @@ Read `AGENTS.md` first. Full hosted docs are at https://docs.webjs.dev.
   the demos relevant to your task under `app/features/<x>` for the runnable idiom
   (the skill teaches the same and SURVIVES the clear, so you never lose it);
   (2) run `npm run gallery:clear` to shed the whole gallery in one step (it keeps
-  the agent skill, the layout, and the database wiring, and resets the home);
+  the agent skill and the database wiring, and resets the home AND the root
+  layout to a token-free blank slate, no gallery palette or navbar survives);
   (3) regenerate the database and grow the app in place under `app/`,
   `components/`, and `modules/<feature>/`. Keep the gallery only while exploring,
   never ship it.
@@ -27,8 +28,10 @@ Read `AGENTS.md` first. Full hosted docs are at https://docs.webjs.dev.
 - **`app/` is routing-only.** Only routing files live in `app/` (page, layout,
   route, middleware, metadata routes). Browser-safe helpers go in `lib/utils/`,
   feature logic in `modules/`, server-only code behind `.server.ts`.
-- **Give a UI app its own design.** Set the design-token values in `app/layout.ts`
-  to a palette that fits the app. Render the app and LOOK before calling UI work
+- **Give a UI app its own design.** Define design tokens in `app/layout.ts` with
+  a palette that fits the app (after `gallery:clear` the layout is a token-free
+  blank slate; `.agents/skills/webjs/references/styling.md` is the guide).
+  Render the app and LOOK before calling UI work
   done: `webjs check` and `webjs typecheck` pass even when a layout collapses, so
   open every route you changed in a real browser and play through its states.
 
diff --git a/packages/cli/templates/AGENTS.md b/packages/cli/templates/AGENTS.md
index 0d8caa36a..8dae171cf 100644
--- a/packages/cli/templates/AGENTS.md
+++ b/packages/cli/templates/AGENTS.md
@@ -30,14 +30,19 @@ The order matters:
    `.agents/skills/webjs/` teaches the same patterns and SURVIVES the clear, so
    clearing is not a knowledge-loss event, the gallery is just a runnable bonus.
 2. **Clear it.** Run `npm run gallery:clear` to shed the whole gallery in one
-   step (removes `app/features/`, `app/examples/`, the demo `modules/`, the demo
-   `todos` table, and resets `app/page.ts` to a minimal home), while KEEPING the
-   agent skill, the layout, and the database wiring.
+   step: it removes `app/features/`, `app/examples/`, the demo `modules/`, the
+   gallery's example design system (`components/ui/`, the theme-toggle), the
+   example tests, and the demo `todos` table, and resets `app/page.ts` to a
+   minimal home AND `app/layout.ts` to a token-free blank slate (OS system
+   colours, no navbar, no palette). It KEEPS the agent skill, the database
+   wiring, and `lib/utils/cn.ts` (the `webjs ui add` prerequisite).
 3. **Build.** Regenerate the database (`npm run db:generate` then `npm run
    db:migrate`), then grow the app in place: routes under `app/`, components
    under `components/`, features under `modules/<feature>/`, server-only code
-   behind `.server.ts`, and the app's own palette via the tokens in
-   `app/layout.ts`.
+   behind `.server.ts`. Build the app's OWN design system from the blank slate:
+   define design tokens in `app/layout.ts` and pull primitives with
+   `npx webjsdev ui add <name>`, following
+   `.agents/skills/webjs/references/styling.md`.
 
 If you are only exploring, keep the gallery and browse it.
 

From 244e0f3956c7f2d724cb0371fe98ea7c62661ff2 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 23:35:31 +0530
Subject: [PATCH 68/73] fix(gallery): stack zeroes only block margins, so
 mx-auto centering lives

The .demo-stack reset used margin: 0, and the layout's unlayered <style> beats
Tailwind's layered utilities, so an mx-auto direct child (the auth login/signup
card) lost its auto side margins and hugged the left edge. Zero margin-block
only. Also strip the now-inert mt-8/mb-8 from page-level prose (direct stack
children, where the stack owns spacing); component-internal margins are live and
untouched. Verified: login card centered (equal side gaps), routing rhythm still
a uniform 24px.
---
 .../cli/templates/gallery/app/features/boundaries/page.ts  | 4 ++--
 .../cli/templates/gallery/app/features/caching/page.ts     | 2 +-
 .../templates/gallery/app/features/client-router/page.ts   | 2 +-
 packages/cli/templates/gallery/app/features/layout.ts      | 7 +++++--
 .../cli/templates/gallery/app/features/rate-limit/page.ts  | 2 +-
 .../templates/gallery/app/features/routing/[id]/page.ts    | 4 ++--
 .../cli/templates/gallery/app/features/routing/page.ts     | 6 +++---
 .../cli/templates/gallery/app/features/sessions/page.ts    | 2 +-
 8 files changed, 16 insertions(+), 13 deletions(-)

diff --git a/packages/cli/templates/gallery/app/features/boundaries/page.ts b/packages/cli/templates/gallery/app/features/boundaries/page.ts
index f4dfbb71d..720bf25cc 100644
--- a/packages/cli/templates/gallery/app/features/boundaries/page.ts
+++ b/packages/cli/templates/gallery/app/features/boundaries/page.ts
@@ -51,13 +51,13 @@ export default function BoundariesExample() {
         <code class="font-mono">not-found.ts</code> (404).
       </li>
     </ul>
-    <p class="text-muted-foreground text-sm mb-8">
+    <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-8">
+    <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
diff --git a/packages/cli/templates/gallery/app/features/caching/page.ts b/packages/cli/templates/gallery/app/features/caching/page.ts
index 95790acbd..9a80952a7 100644
--- a/packages/cli/templates/gallery/app/features/caching/page.ts
+++ b/packages/cli/templates/gallery/app/features/caching/page.ts
@@ -36,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-8 mb-8">
+    <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
diff --git a/packages/cli/templates/gallery/app/features/client-router/page.ts b/packages/cli/templates/gallery/app/features/client-router/page.ts
index 79d0fda67..c6b7150db 100644
--- a/packages/cli/templates/gallery/app/features/client-router/page.ts
+++ b/packages/cli/templates/gallery/app/features/client-router/page.ts
@@ -26,7 +26,7 @@ export default function ClientRouterExample() {
       <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-8">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>,
diff --git a/packages/cli/templates/gallery/app/features/layout.ts b/packages/cli/templates/gallery/app/features/layout.ts
index 186c3715e..4d0f7da80 100644
--- a/packages/cli/templates/gallery/app/features/layout.ts
+++ b/packages/cli/templates/gallery/app/features/layout.ts
@@ -32,8 +32,11 @@ const STACK_CSS = `
     flex-direction: column;
     gap: var(--section-gap);
   }
-  /* Zero any inline margins so ONLY the flex gap spaces sections. */
-  .demo-stack > * { margin: 0; }
+  /* 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
diff --git a/packages/cli/templates/gallery/app/features/rate-limit/page.ts b/packages/cli/templates/gallery/app/features/rate-limit/page.ts
index beccf046e..298866b1d 100644
--- a/packages/cli/templates/gallery/app/features/rate-limit/page.ts
+++ b/packages/cli/templates/gallery/app/features/rate-limit/page.ts
@@ -20,7 +20,7 @@ export default function RateLimitExample() {
       <code class="font-mono">Retry-After</code> header.
     `)}
     <rate-probe></rate-probe>
-    <p class="text-muted-foreground text-sm mt-8">
+    <p class="text-muted-foreground text-sm">
       With JavaScript off, hit
       <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).
diff --git a/packages/cli/templates/gallery/app/features/routing/[id]/page.ts b/packages/cli/templates/gallery/app/features/routing/[id]/page.ts
index b653a686a..89bc330b5 100644
--- a/packages/cli/templates/gallery/app/features/routing/[id]/page.ts
+++ b/packages/cli/templates/gallery/app/features/routing/[id]/page.ts
@@ -26,14 +26,14 @@ export default async function RoutingParam({ params }: PageProps<'/features/rout
   return html`
     ${pageHeading('Route param')}
     <p>The <code>[id]</code> segment is: <strong>${id}</strong></p>
-    <p class="text-muted-foreground text-sm mt-8">
+    <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-8">
+    <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
diff --git a/packages/cli/templates/gallery/app/features/routing/page.ts b/packages/cli/templates/gallery/app/features/routing/page.ts
index 88a2e1ada..8f748fd32 100644
--- a/packages/cli/templates/gallery/app/features/routing/page.ts
+++ b/packages/cli/templates/gallery/app/features/routing/page.ts
@@ -16,7 +16,7 @@ export default function RoutingExample() {
       <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-8">
+    <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
@@ -24,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-8">
+    <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
@@ -44,7 +44,7 @@ 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-8">
+    <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
diff --git a/packages/cli/templates/gallery/app/features/sessions/page.ts b/packages/cli/templates/gallery/app/features/sessions/page.ts
index 59738bf79..d8769b7ff 100644
--- a/packages/cli/templates/gallery/app/features/sessions/page.ts
+++ b/packages/cli/templates/gallery/app/features/sessions/page.ts
@@ -14,6 +14,6 @@ export default function SessionsExample() {
     ${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 mt-8">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>
+    <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>
   `;
 }

From fc766a377a02cd00d0d6f25e25db0a4c07699ff3 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 23:38:38 +0530
Subject: [PATCH 69/73] fix(check): scope no-shadowed-native-member to real
 instance shadowing

The rule scanned the whole class body with a bare name regex, so it
false-positived on definitions that shadow nothing: a static method (lives on
the constructor), an object-literal shorthand or named function expression
nested inside a method body (another object's property), and any member of a
static shadow = true component (the slot interception installs only on
light-DOM hosts). It also missed the class-field function form
(remove = () => {}), which the connect-time interception install clobbers just
like a method. Track brace depth over the masked class body and flag only
top-level non-static members, skip shadow classes, and add the field-function
shape. Tests grow from 3 to 7: factory-form + class-field positive, and
static / nested / shadow / mixed-file negatives. 150 check tests green; a
generated gallery app still checks clean.
---
 packages/server/src/check.js                  | 56 ++++++++++++---
 .../check/no-shadowed-native-member.test.js   | 68 ++++++++++++++++++-
 2 files changed, 113 insertions(+), 11 deletions(-)

diff --git a/packages/server/src/check.js b/packages/server/src/check.js
index 53242ad8b..9a106e554 100644
--- a/packages/server/src/check.js
+++ b/packages/server/src/check.js
@@ -679,17 +679,53 @@ export async function checkConventions(appDir) {
     for (const { rel, scan } of files) {
       if (!/class\s+\w+\s+extends\s+WebComponent/.test(scan)) continue;
       for (const { body } of extractWebComponentClassBodies(scan)) {
+        // The slot interception installs only on LIGHT-DOM hosts (the shadow
+        // branch keeps the true native methods), so a shadow component's method
+        // is never shadowed. Skip the whole class.
+        if (/static\s+shadow\s*=\s*true/.test(body)) continue;
+        // Brace-depth map over the (already string/comment-masked) class body,
+        // so only TOP-LEVEL class members flag: a same-named object-literal
+        // shorthand or function expression nested inside a method body is a
+        // different object's property and shadows nothing.
+        const depth = new Int32Array(body.length);
+        {
+          let d = 0;
+          for (let i = 0; i < body.length; i++) {
+            if (body[i] === '{') { depth[i] = d; d++; }
+            else if (body[i] === '}') { d--; depth[i] = d; }
+            else depth[i] = d;
+          }
+        }
         for (const name of NATIVE_MEMBERS) {
-          // Same method-definition shape methodBodyOf() matches (name followed by
-          // a param list then `{`), preceded by a class-body boundary.
-          const re = new RegExp(`(?:^|[\\s;}])(?:async\\s+)?${name}\\s*\\([^)]*\\)\\s*(?::[^{]*)?\\{`);
-          if (re.test(body)) {
-            violations.push({
-              rule: 'no-shadowed-native-member',
-              file: rel,
-              message: `Component method \`${name}()\` shadows the native DOM method WebJs instruments for the slot API, so it silently never runs (the native method wins) and TypeScript does not catch it.`,
-              fix: `Rename the method to a non-native name (e.g. \`${name}Row()\` / \`${name}Item()\`) and update its call sites.`,
-            });
+          // Two shadowed-definition shapes, both instance-level: the method /
+          // accessor form (`remove() {`, `get remove() {`), and the class-field
+          // FUNCTION form (`remove = () => {}` / `= function () {}`), which the
+          // connect-time interception install overwrites just the same. A
+          // `static` member lives on the constructor and shadows nothing.
+          const methodRe = new RegExp(
+            `(?:^|[\\s;}])((?:static\\s+)?)(?:async\\s+)?(?:get\\s+|set\\s+)?(${name})\\s*\\([^)]*\\)\\s*(?::[^{]*)?\\{`,
+            'g',
+          );
+          const fieldRe = new RegExp(
+            `(?:^|[\\s;}])((?:static\\s+)?)(${name})\\s*=\\s*(?:async\\s*)?(?:function\\b|\\([^)]*\\)\\s*(?::[^=]*)?=>|[\\w$]+\\s*=>)`,
+            'g',
+          );
+          let flagged = false;
+          for (const re of [methodRe, fieldRe]) {
+            let m;
+            while (!flagged && (m = re.exec(body)) !== null) {
+              if (m[1]) continue;                       // static: not shadowed
+              const nameIdx = m.index + m[0].indexOf(m[2]);
+              if (depth[nameIdx] !== 0) continue;       // nested: another object's property
+              flagged = true;
+              violations.push({
+                rule: 'no-shadowed-native-member',
+                file: rel,
+                message: `Component member \`${name}\` shadows the native DOM method WebJs instruments for the slot API, so it silently never runs (the native method wins) and TypeScript does not catch it.`,
+                fix: `Rename the member to a non-native name (e.g. \`${name}Row()\` / \`${name}Item()\`) and update its call sites.`,
+              });
+            }
+            if (flagged) break;
           }
         }
       }
diff --git a/packages/server/test/check/no-shadowed-native-member.test.js b/packages/server/test/check/no-shadowed-native-member.test.js
index 3d23850fa..18387697a 100644
--- a/packages/server/test/check/no-shadowed-native-member.test.js
+++ b/packages/server/test/check/no-shadowed-native-member.test.js
@@ -40,7 +40,7 @@ class Stream extends WebComponent {
 Stream.register('x-stream');`,
   });
   const v = hits(await checkConventions(dir));
-  const names = v.map((x) => x.message.match(/`(\w+)\(\)`/)[1]).sort();
+  const names = v.map((x) => x.message.match(/`(\w+)`/)[1]).sort();
   assert.deepEqual(names, ['append', 'prepend'], 'flags both append and prepend');
   assert.match(v[0].fix, /Rename/);
 });
@@ -73,3 +73,69 @@ X.register('x-x');`,
   assert.equal(v.length, 1);
   assert.match(v[0].message, /removeChild/);
 });
+
+test('flags the factory form and the class-field function form', async () => {
+  // The factory base (`extends WebComponent({...})`) is the shape every real
+  // gallery component uses, and a class-field arrow is clobbered by the
+  // connect-time interception install just like a method.
+  const dir = await makeApp({
+    'components/x.ts': `import { WebComponent, html, prop } from '@webjsdev/core';
+class X extends WebComponent({ items: prop(Array) }) {
+  remove = (id: number) => { this.items = this.items.filter((t) => t.id !== id); };
+  render() { return html\`<div></div>\`; }
+}
+X.register('x-x');`,
+  });
+  const v = hits(await checkConventions(dir));
+  assert.equal(v.length, 1, 'the class-field arrow on a factory-based class flags');
+  assert.match(v[0].message, /`remove`/);
+});
+
+test('does NOT flag static members, nested object properties, or shadow components', async () => {
+  const dir = await makeApp({
+    // static: lives on the constructor, never shadowed.
+    'components/a.ts': `import { WebComponent, html } from '@webjsdev/core';
+class A extends WebComponent {
+  static remove(id: string) { return id; }
+  render() { return html\`<div></div>\`; }
+}
+A.register('x-a');`,
+    // nested: an object-literal shorthand and a named function expression inside
+    // a method body are another object's properties, not class members.
+    'components/b.ts': `import { WebComponent, html } from '@webjsdev/core';
+class B extends WebComponent {
+  handlers() { return { remove(id: string) { return id; }, append() {} }; }
+  wire() { this.addEventListener('x', function remove() {}); }
+  render() { return html\`<div></div>\`; }
+}
+B.register('x-b');`,
+    // shadow DOM: the slot interception installs only on light-DOM hosts.
+    'components/c.ts': `import { WebComponent, html } from '@webjsdev/core';
+class C extends WebComponent {
+  static shadow = true;
+  append() {}
+  render() { return html\`<div></div>\`; }
+}
+C.register('x-c');`,
+  });
+  const v = hits(await checkConventions(dir));
+  assert.equal(v.length, 0, `no false positives, got: ${v.map((x) => x.file).join(', ')}`);
+});
+
+test('does NOT flag a plain helper class sharing a file with a clean component', async () => {
+  // Mixed file: the scan must stay scoped to WebComponent class bodies, so a
+  // non-component helper class may use the native names freely.
+  const dir = await makeApp({
+    'components/mixed.ts': `import { WebComponent, html } from '@webjsdev/core';
+class Registry {
+  append(item: string) { return item; }
+  remove(item: string) { return item; }
+}
+class Mixed extends WebComponent {
+  render() { return html\`<div>\${new Registry().append('x')}</div>\`; }
+}
+Mixed.register('x-mixed');`,
+  });
+  const v = hits(await checkConventions(dir));
+  assert.equal(v.length, 0, 'the helper class next to a component does not flag');
+});

From 3776556cbbe7db7d1ef993ca1766458bc4250a23 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 23:39:33 +0530
Subject: [PATCH 70/73] fix(server): head hoist is quote-aware, a > in an
 attribute cannot truncate

The <link>/<meta> void-tag matchers used [^>]*, so a > inside a quoted attribute
value (a description meta like content="Guides > API") cut the tag early:
the truncated half hoisted into <head>, the remainder leaked as visible body
text, and the run terminated, stranding the stylesheet (the #406 FOUC again).
Match quoted attribute values atomically. Counterfactual proven (test red on the
old regex); 129 SSR tests green.
---
 packages/server/src/ssr.js                  |  7 ++++++-
 packages/server/test/ssr/head-hoist.test.js | 20 ++++++++++++++++++++
 2 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/packages/server/src/ssr.js b/packages/server/src/ssr.js
index bad391411..f451990af 100644
--- a/packages/server/src/ssr.js
+++ b/packages/server/src/ssr.js
@@ -1138,8 +1138,13 @@ function collectHoistedHeadTags(bodyHtml) {
   // guard exempts client-router markers (<!--wj:children:…-->,
   // <!--/wj:children-->) so a layout that renders children directly after its
   // head tags still terminates the run there rather than swallowing the marker.
+  // The void-tag matchers are QUOTE-AWARE ((?:[^>"']|"[^"]*"|'[^']*')*): a `>`
+  // inside a quoted attribute value (a description meta like
+  // content="Guides > API") must not terminate the tag early, which would hoist
+  // a truncated tag, leak the remainder as visible body text, and strand the
+  // stylesheet (the #406 FOUC this hoist exists to prevent).
   const re =
-    /^\s*(<!--(?!\/?wj:)[\s\S]*?-->|<script[\s>][\s\S]*?<\/script>|<style[\s>][\s\S]*?<\/style>|<link\b[^>]*>|<meta\b[^>]*>)/i;
+    /^\s*(<!--(?!\/?wj:)[\s\S]*?-->|<script[\s>][\s\S]*?<\/script>|<style[\s>][\s\S]*?<\/style>|<link\b(?:[^>"']|"[^"]*"|'[^']*')*>|<meta\b(?:[^>"']|"[^"]*"|'[^']*')*>)/i;
   let remaining = bodyHtml;
   // `body` only advances to just-past the LAST hoisted head tag. Comments
   // are scanned through (so they don't terminate the run) but a comment that
diff --git a/packages/server/test/ssr/head-hoist.test.js b/packages/server/test/ssr/head-hoist.test.js
index e1cf67594..e446aacc4 100644
--- a/packages/server/test/ssr/head-hoist.test.js
+++ b/packages/server/test/ssr/head-hoist.test.js
@@ -96,6 +96,26 @@ test('a <meta> between head-bound tags does NOT strand the later tags (favicon +
   assert.ok(out.includes('<main>content</main>'));
 });
 
+test('a > inside a quoted attribute value does not truncate the tag', () => {
+  // A description meta with free text (content="Guides > API") must hoist as a
+  // WHOLE tag: a naive [^>]* matcher would cut it at the inner >, hoist the
+  // truncated half, leak ` API">` as visible body text, and terminate the run
+  // (stranding the stylesheet, the FOUC again).
+  const body =
+    '<meta name="description" content="Guides > API">' +
+    '<link rel="alternate" title=\'a > b\' href="/feed.xml">' +
+    '<link rel="stylesheet" href="/s.css">' +
+    '<main>content</main>';
+  const { head, body: out } = _hoistHeadTags(HEAD, body);
+
+  assert.ok(head.includes('content="Guides > API"'), 'meta hoisted whole, not truncated');
+  assert.ok(head.includes("title='a > b'"), 'single-quoted attr with > hoisted whole');
+  assert.ok(head.includes('rel="stylesheet"'), 'stylesheet hoisted past both');
+  assert.equal(out.includes('API">'), false, 'no truncated remainder leaks into the body');
+  assert.equal(out.includes('rel="stylesheet"'), false, 'stylesheet not stranded');
+  assert.ok(out.includes('<main>content</main>'));
+});
+
 test('a webjs client-router marker terminates the run (not swallowed)', () => {
   // A pathological layout that renders children right after its head tags:
   // the <!--wj:children:…--> marker must stay in the body so the client

From 8953ea1e1427a980b680e9d1eda0ee39e3105a7b Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 23:40:33 +0530
Subject: [PATCH 71/73] fix(gallery): clear keeps a hand-customised layout;
 polish emitted text

Guard the gallery:clear layout overwrite on the gallery's own navbar brand: a
layout the user already themed (brand gone) is KEPT, with only the dangling
theme-toggle wiring stripped, instead of being silently clobbered. Fix the
over-escaped backtick that leaked a literal backslash into the reset layout's
comment, and correct the buttonClass comment about where the global focus ring
lives (the ui theme's @layer base, not the root layout). Both clear paths
verified: blank slate on a pristine layout, kept + surgically stripped on a
customised one (check + typecheck pass).
---
 .../templates/gallery/components/ui/button.ts |  5 ++--
 .../cli/templates/scripts/clear-gallery.mjs   | 24 +++++++++++++++----
 2 files changed, 23 insertions(+), 6 deletions(-)

diff --git a/packages/cli/templates/gallery/components/ui/button.ts b/packages/cli/templates/gallery/components/ui/button.ts
index 68720737b..76487f65c 100644
--- a/packages/cli/templates/gallery/components/ui/button.ts
+++ b/packages/cli/templates/gallery/components/ui/button.ts
@@ -34,8 +34,9 @@ import { cn } from '#lib/utils/cn.ts';
 
 // BASE: shared by every variant + size, so a fix here (e.g. the focus ring, or
 // cursor-pointer) applies to the whole button system at once.
-// Focus is handled ONCE by the app's global :focus-visible ring (in the root
-// layout), so buttons need no per-element focus style here.
+// Focus is handled ONCE by the design system's global :focus-visible ring (the
+// ui theme's @layer base in public/input.css), so buttons need no per-element
+// focus style here.
 const BASE =
   'inline-flex shrink-0 cursor-pointer items-center justify-center gap-2 whitespace-nowrap text-sm transition-all disabled:pointer-events-none disabled:opacity-60';
 
diff --git a/packages/cli/templates/scripts/clear-gallery.mjs b/packages/cli/templates/scripts/clear-gallery.mjs
index e950bb182..25a9893d5 100644
--- a/packages/cli/templates/scripts/clear-gallery.mjs
+++ b/packages/cli/templates/scripts/clear-gallery.mjs
@@ -110,10 +110,26 @@ if (existsSync(schemaPath)) {
 // carries no design system: the Tailwind stylesheet + OS light/dark system
 // colours (Canvas / CanvasText) + a bare <main>. The agent then builds the
 // palette (CSS tokens + @theme + a light-dark() theme) as its own, guided by
-// .agents/skills/webjs/references/styling.md. (Safe under the app/features/ guard
-// above: the gallery is still present, so the layout is not hand-customised yet.)
+// .agents/skills/webjs/references/styling.md.
+// GUARD: overwrite only while the layout still carries the gallery's own navbar
+// brand. A hand-customised layout (the brand removed / replaced) is the user's
+// work, so it is KEPT and only the dangling references to the removed
+// theme-toggle file are stripped surgically.
 const layoutPath = join(root, 'app/layout.ts');
-if (existsSync(layoutPath)) writeFileSync(layoutPath, MINIMAL_LAYOUT());
+if (existsSync(layoutPath)) {
+  const current = readFileSync(layoutPath, 'utf8');
+  if (current.includes('WebJs Gallery')) {
+    writeFileSync(layoutPath, MINIMAL_LAYOUT());
+  } else {
+    console.log('app/layout.ts looks customised; keeping it (only the theme-toggle wiring is stripped).');
+    writeFileSync(
+      layoutPath,
+      current
+        .replace(/^import '#components\/theme-toggle\.ts';\n/m, '')
+        .replace(/^\s*<theme-toggle><\/theme-toggle>\n?/m, ''),
+    );
+  }
+}
 
 // 6) Drop generated migrations + the dev database so the next db:generate is
 // clean against the reset schema (safe: the scaffold has no real data yet).
@@ -167,7 +183,7 @@ function MINIMAL_LAYOUT() {
  * the app's look. The recommended setup, CSS custom-property tokens mapped into
  * Tailwind via @theme (so bg-background / text-foreground work), a DRY
  * light-dark() palette, a header/nav, and the ui class helpers, is taught in
- * .agents/skills/webjs/references/styling.md. Run \\\`npx webjsdev ui add <name>\\\`
+ * .agents/skills/webjs/references/styling.md. Run \`npx webjsdev ui add <name>\`
  * to pull primitives, then theme them here.
  */
 

From 87643af4a555c54d7ae5cc104dd88e395591839b Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 23:48:08 +0530
Subject: [PATCH 72/73] test(scaffold): cover the gallery:clear brand guard;
 document it

Round-2 review notes: the keep-if-customised guard had no automated test and was
undocumented. Add a scaffold test (customised layout survives the clear, its
palette intact, only the theme-toggle wiring stripped, blank slate NOT applied)
and mention the guard in AGENTS.md + workflow.md in lockstep. 11 gallery tests
green.
---
 .../cli/templates/.agents/rules/workflow.md   |  3 ++-
 packages/cli/templates/AGENTS.md              |  6 +++--
 test/scaffolds/scaffold-gallery.test.js       | 27 ++++++++++++++++++-
 3 files changed, 32 insertions(+), 4 deletions(-)

diff --git a/packages/cli/templates/.agents/rules/workflow.md b/packages/cli/templates/.agents/rules/workflow.md
index afee4c6a0..b4560e622 100644
--- a/packages/cli/templates/.agents/rules/workflow.md
+++ b/packages/cli/templates/.agents/rules/workflow.md
@@ -17,7 +17,8 @@ Read `AGENTS.md` first. Full hosted docs are at https://docs.webjs.dev.
   (the skill teaches the same and SURVIVES the clear, so you never lose it);
   (2) run `npm run gallery:clear` to shed the whole gallery in one step (it keeps
   the agent skill and the database wiring, and resets the home AND the root
-  layout to a token-free blank slate, no gallery palette or navbar survives);
+  layout to a token-free blank slate, no gallery palette or navbar survives; a
+  layout you already customised is kept, only its theme-toggle wiring stripped);
   (3) regenerate the database and grow the app in place under `app/`,
   `components/`, and `modules/<feature>/`. Keep the gallery only while exploring,
   never ship it.
diff --git a/packages/cli/templates/AGENTS.md b/packages/cli/templates/AGENTS.md
index 8dae171cf..c8d82edf9 100644
--- a/packages/cli/templates/AGENTS.md
+++ b/packages/cli/templates/AGENTS.md
@@ -34,8 +34,10 @@ The order matters:
    gallery's example design system (`components/ui/`, the theme-toggle), the
    example tests, and the demo `todos` table, and resets `app/page.ts` to a
    minimal home AND `app/layout.ts` to a token-free blank slate (OS system
-   colours, no navbar, no palette). It KEEPS the agent skill, the database
-   wiring, and `lib/utils/cn.ts` (the `webjs ui add` prerequisite).
+   colours, no navbar, no palette). A layout you already customised (the gallery
+   brand removed) is KEPT, with only the theme-toggle wiring stripped. It KEEPS
+   the agent skill, the database wiring, and `lib/utils/cn.ts` (the
+   `webjs ui add` prerequisite).
 3. **Build.** Regenerate the database (`npm run db:generate` then `npm run
    db:migrate`), then grow the app in place: routes under `app/`, components
    under `components/`, features under `modules/<feature>/`, server-only code
diff --git a/test/scaffolds/scaffold-gallery.test.js b/test/scaffolds/scaffold-gallery.test.js
index fde6fe833..c3226381d 100644
--- a/test/scaffolds/scaffold-gallery.test.js
+++ b/test/scaffolds/scaffold-gallery.test.js
@@ -16,7 +16,7 @@
  */
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtemp, rm, readFile, stat } from 'node:fs/promises';
+import { mkdtemp, rm, readFile, stat, writeFile } from 'node:fs/promises';
 import { existsSync, readdirSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { join } from 'node:path';
@@ -244,6 +244,31 @@ test('full-stack gallery:clear strips the app to a barebones blank slate', async
   }
 });
 
+test('gallery:clear keeps a hand-customised root layout (brand guard)', async () => {
+  // The layout overwrite is guarded on the gallery's own navbar brand: a layout
+  // the user already themed (brand gone) is the user's work, so clear KEEPS it
+  // and strips only the dangling theme-toggle wiring (the component file is
+  // removed either way).
+  const cwd = await tempCwd();
+  try {
+    await scaffoldApp('demo', cwd, { template: 'full-stack', install: false });
+    const appDir = join(cwd, 'demo');
+    const layoutPath = join(appDir, 'app', 'layout.ts');
+    const customised = (await readFile(layoutPath, 'utf8')).replace('WebJs Gallery', 'Acme Notes');
+    await writeFile(layoutPath, customised);
+
+    execFileSync(process.execPath, ['scripts/clear-gallery.mjs'], { cwd: appDir, stdio: 'ignore' });
+
+    const kept = await readFile(layoutPath, 'utf8');
+    assert.match(kept, /Acme Notes/, 'the customised layout survives the clear');
+    assert.match(kept, /light-dark\(/, "the user's palette survives too");
+    assert.doesNotMatch(kept, /theme-toggle/, 'the dangling theme-toggle wiring is stripped');
+    assert.doesNotMatch(kept, /background:\s*Canvas/, 'the blank-slate layout was NOT applied');
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
 test('feature pages have no stale /examples/ links after the features refactor', async () => {
   // Regression guard: moving the demos from app/examples/ to app/features/ must
   // update the in-page hrefs too, not just the marker text. The ONLY valid

From bb0d3bcd39bdea4f28e2066480efd994eb286454 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 23:56:52 +0530
Subject: [PATCH 73/73] docs: explain no-shadowed-native-member in the gotcha
 reference

---
 .agents/skills/webjs/references/muscle-memory-gotchas.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/.agents/skills/webjs/references/muscle-memory-gotchas.md b/.agents/skills/webjs/references/muscle-memory-gotchas.md
index 66d6d6df9..0f4e33d25 100644
--- a/.agents/skills/webjs/references/muscle-memory-gotchas.md
+++ b/.agents/skills/webjs/references/muscle-memory-gotchas.md
@@ -153,6 +153,10 @@ Lit defaults to shadow DOM, so `static styles = css` scopes automatically. WebJs
 
 In shadow DOM the browser projects slotted content natively before `firstUpdated`, so Lit muscle memory says `this.shadowRoot.querySelector('slot').assignedNodes()` is populated there. In light DOM the first projection lands one microtask AFTER the first render, so `firstUpdated` sees the `<slot>` element with an EMPTY `assignedNodes()`. The webjs-shaped fix: read assigned content from a `slotchange` listener (fires once projection lands, and on every later change), or wait a microtask. Every later read and every mutation-driven update behaves identically in both modes; only the first-render read differs.
 
+### Naming a component method after a native DOM method (`remove`, `append`, `after`)
+
+Light-DOM slots ARE the native DOM slot API, so the framework instruments the native mutation methods (`append`, `prepend`, `before`, `after`, `replaceWith`, `replaceChildren`, `remove`, `appendChild`, `insertBefore`, `removeChild`, `replaceChild`) to keep slot projection live. A component method that shadows one of those names (for example a `remove()` handler on a list-row component, or an `append()` helper) overrides the instrumented method on the instance, so a native write that goes through it silently stops re-projecting. The webjs-shaped fix is a non-colliding name (`removeItem()`, `appendRow()`). Flagged by `no-shadowed-native-member`, which only fires on a real instance method at class-body depth, so a static member, a nested-object property, or a `static shadow = true` component (native shadow slots are not instrumented) is not flagged.
+
 ### `:host { display: block }` on a light-DOM component
 
 A custom element is `display: inline` by default, so a block container collapses. In Lit you fix this with `:host { display: block }`, which works because Lit is shadow-DOM-first. A light-DOM WebJs component has no shadow root, so there is no `:host` to write. There is nothing to do: the framework already defaults every light-DOM host to `display: block` via a low-priority `@layer webjs-host` rule, overridable by any Tailwind utility (`class="flex"` wins). A shadow-DOM component (`static shadow = true`) still sets `:host { display: block }` in `static styles` itself, exactly like Lit.