@webjsdev/cli 0.10.44 → 0.10.46

package/lib/create.js

@@ -18,7 +18,6 @@ import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { spawnSync } from 'node:child_process';
 import { bunifyProse, bunifyDockerfile, bunifyCompose, bunifyCi } from './runtime-rewrite.js';
-import { leanComponentSource } from './lean-copy.js';
 
 /**
  * Detect which package manager invoked us. Reads `npm_config_user_agent`,
@@ -106,60 +105,6 @@ function resolveUiRegistryRoot() {
 }
 const UI_REGISTRY_ROOT = resolveUiRegistryRoot();
 
-/**
- * Read a single @webjsdev/ui registry component, rewrite its relative import
- * of `../lib/utils.ts` to the scaffolded app's aliased path so it resolves
- * when written to `components/ui/<name>.ts`. The scaffold puts cn() at
- * `lib/utils/cn.ts` (folder-grouped with other browser-safe helpers), so the
- * alias form is `#lib/utils/cn.ts` (#555/#556).
- *
- * @param {string} name  component name without `.ts` (e.g. 'button')
- * @returns {Promise<string>} source with import rewritten
- */
-async function readUiComponent(name) {
-  const src = join(UI_REGISTRY_ROOT, 'components', `${name}.ts`);
-  const raw = await readFile(src, 'utf8');
-  // The registry component imports cn() via a relative `../lib/utils.ts`; rewrite
-  // it to the scaffolded app's aliased path (cn lives at lib/utils/cn.ts).
-  const rewritten = raw
-    .replaceAll("'../lib/utils.ts'", "'#lib/utils/cn.ts'")
-    .replaceAll('"../lib/utils.ts"', '"#lib/utils/cn.ts"')
-    // onBeforeCache lives in its own client-only module so cn() stays pure (#819).
-    .replaceAll("'../lib/dom.ts'", "'#lib/utils/dom.ts'")
-    .replaceAll('"../lib/dom.ts"', '"#lib/utils/dom.ts"');
-  // Strip the worked @example from a Tier-1 helper (same as `webjs ui add`), so
-  // the scaffolded component is lean and the example is served on demand. The
-  // shared helper is used by the saas-template copier too, so they cannot drift.
-  return leanComponentSource(rewritten, name);
-}
-
-/**
- * Copy a list of @webjsdev/ui registry components into the scaffolded app
- * under `components/ui/`. Throws if any name is missing from the registry,
- * since the scaffold's generated pages import these by name and a missing
- * file would produce ERR_MODULE_NOT_FOUND at first request. Caller must
- * have already invoked assertUiRegistryAvailable().
- *
- * @param {string} appDir  destination app root
- * @param {string[]} names list of component file basenames (without `.ts`)
- */
-async function copyUiComponents(appDir, names) {
-  const uiDir = join(appDir, 'components', 'ui');
-  await mkdir(uiDir, { recursive: true });
-  for (const n of names) {
-    const src = join(UI_REGISTRY_ROOT, 'components', `${n}.ts`);
-    if (!existsSync(src)) {
-      throw new Error(
-        `@webjsdev/ui registry is missing component '${n}.ts' at ${src}. ` +
-        `The scaffold's example pages import this component by name. ` +
-        `Either the registry was published incompletely or the scaffold's ` +
-        `component list is out of sync with the registry.`,
-      );
-    }
-    await writeFile(join(uiDir, `${n}.ts`), await readUiComponent(n));
-  }
-}
-
 /**
  * Copy the example gallery (idiomatic, densely-commented working examples) into
  * the scaffolded app. Merges `templates/gallery/{app,modules}` over the app so
@@ -177,7 +122,18 @@ async function copyUiComponents(appDir, names) {
  */
 async function copyGallery(appDir) {
   const galleryDir = join(TEMPLATES, 'gallery');
-  for (const sub of ['app', 'modules']) {
+  // `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 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 });
   }
 }
@@ -312,21 +268,19 @@ export async function scaffoldApp(name, cwd, opts = {}) {
   const shouldInstall = opts.install === true;
   // Defence in depth. The CLI already validates this, but library
   // callers (tests, programmatic use) might pass anything.
-  const VALID_TEMPLATES = ['full-stack', 'api', 'saas'];
+  const VALID_TEMPLATES = ['full-stack', 'api'];
   if (!VALID_TEMPLATES.includes(template)) {
     throw new Error(
       `Unknown template '${template}'. Only ${VALID_TEMPLATES.join(' / ')} exist.`,
     );
   }
   const isApi = template === 'api';
-  const isSaas = template === 'saas';
-  // The example gallery ships in every UI scaffold (full-stack AND saas). The
-  // copyGallery gate below is !isApi, since only the api template has no UI. saas
-  // overwrites db/schema.server.ts with its own schema (which includes the
-  // gallery's todos table) and renders the gallery below its auth landing.
-  // isFullStack distinguishes the plain full-stack app from saas for the parts
-  // that differ (its own home page and the create.js-written schema).
-  const isFullStack = !isApi && !isSaas;
+  // The example gallery ships in the one UI template (not api, which has no UI),
+  // so the copyGallery gate below is !isApi. Auth is one of the gallery cards
+  // (app/features/auth + modules/auth), so a UI app ships a real, prunable auth
+  // baseline. `isFullStack` names the UI template for the parts that differ from
+  // api (the todos table + the passwordHash column the auth card needs).
+  const isFullStack = !isApi;
 
   // Database dialect (#563): sqlite (default) or postgres. Drizzle is the ORM;
   // the schema/queries/actions are identical across dialects, only db/columns
@@ -420,8 +374,13 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // app runs the compiler under Bun (its image has no Node), a Node app runs
       // it directly.
       ...(isApi ? {} : { 'css:build': cssBuildCmd }),
-      // Shed the demo gallery to a clean, buildable base (scripts/clear-gallery.mjs).
-      ...(isApi ? {} : { 'gallery:clear': isBun ? 'bun scripts/clear-gallery.mjs' : 'node scripts/clear-gallery.mjs' }),
+      // Shed the demo gallery / backend-features showcase to a clean, buildable
+      // base. The UI template runs clear-gallery.mjs; the api template runs
+      // clear-api-gallery.mjs (its showcase is app/api/features, not app/features).
+      'gallery:clear': (() => {
+        const script = isApi ? 'clear-api-gallery.mjs' : 'clear-gallery.mjs';
+        return isBun ? `bun scripts/${script}` : `node scripts/${script}`;
+      })(),
       dev: isBun ? 'bun --bun webjs dev' : 'webjs dev',
       start: isBun ? 'bun --bun webjs start' : 'webjs start',
       test: 'webjs test',
@@ -763,7 +722,10 @@ export const users = table('users', {
   name: text(),
   // JSON column: a structured value persisted as JSON, typed via json<T>().
   // Same helper works on SQLite and Postgres. Delete if you do not need it.
-  settings: json<{ theme?: string }>(),
+  settings: json<{ theme?: string }>(),${isFullStack ? `
+  // The auth gallery card (app/features/auth) signs credentials against this.
+  // gallery:clear removes this column with the rest of the auth surface.
+  passwordHash: text(),` : ''}
   createdAt: createdAt(),
 });
 ${isFullStack ? `
@@ -1040,10 +1002,18 @@ export type ActionResult<T> =
     // counterpart of the UI gallery. Prune what you skip.
     const { writeApiGallery } = await import('./api-gallery.js');
     await writeApiGallery(appDir);
+
+    // The showcase-reset script (wired as `gallery:clear` for the api template).
+    // It sheds app/api/features + its modules back to the health + users base.
+    const apiClearSrc = join(TEMPLATES, 'scripts', 'clear-api-gallery.mjs');
+    if (existsSync(apiClearSrc)) {
+      await mkdir(join(appDir, 'scripts'), { recursive: true });
+      await cp(apiClearSrc, join(appDir, 'scripts', 'clear-api-gallery.mjs'));
+    }
   }
 
   if (!isApi) {
-    // Full-stack and SaaS templates: layout + page + theme toggle + Tailwind
+    // The UI template: layout + page + theme toggle + Tailwind
 
     // The Tailwind stylesheet is compiled from public/input.css (written below)
     // to a STATIC public/tailwind.css by css:build, and lib/utils/ui.ts helpers
@@ -1053,8 +1023,8 @@ export type ActionResult<T> =
     const publicDir = join(appDir, 'public');
     await mkdir(publicDir, { recursive: true });
     // Progressive-enhancement service worker (#271): ship the opt-in offline
-    // primitive (the worker + its offline fallback) into the UI scaffolds
-    // (full-stack / saas; this block is api-excluded since api has no UI).
+    // primitive (the worker + its offline fallback) into the UI scaffold
+    // (this block is api-excluded since api has no UI).
     // Dormant until the app registers it (see the skill's references/service-worker.md);
     // it never changes the JS-disabled baseline.
     for (const swFile of ['sw.js', 'offline.html']) {
@@ -1087,13 +1057,9 @@ export type ActionResult<T> =
     // styles/globals.css (the @webjsdev/ui theme).
     await writeUiBootstrap(appDir);
 
-    // The saas auth pages import a few ui-* primitives. A full-stack app adds
-    // any component on demand with `webjs ui add <name>`.
-    if (isSaas) {
-      await copyUiComponents(appDir, [
-        'button', 'card', 'alert', 'badge', 'separator', 'label', 'input',
-      ]);
-    }
+    // The gallery cards style with plain Tailwind (the app is pre-initialised for
+    // `webjs ui add <name>` via writeUiBootstrap above, but ships no components
+    // until you add them on demand).
 
     // The @webjsdev/ui theme (`--color-primary`, `--color-card`, the @theme maps,
     // @custom-variant, @keyframes) plus the app @theme mappings are compiled from
@@ -1136,10 +1102,10 @@ ${uiThemeRaw}
 
     // The gallery: idiomatic, densely-commented single-feature demos under
     // app/features/ plus one whole example app under app/examples/, with logic
-    // in modules/, all linked from the home page below. Shipped in every UI
-    // scaffold (full-stack AND saas) so an agent gains context by browsing real
-    // working code; prune per-feature (delete the route + its module) for what
-    // the app does not use.
+    // in modules/, all linked from the home page below. Shipped in the UI
+    // scaffold so an agent gains context by browsing real working code; prune
+    // per-feature (delete the route + its module) for what the app does not use,
+    // or shed the whole gallery at once with `gallery:clear`.
     await copyGallery(appDir);
 
   await writeFile(join(appDir, 'app', 'layout.ts'), `import { html, cspNonce } from '@webjsdev/core';
@@ -1154,26 +1120,34 @@ 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.
   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);
@@ -1187,7 +1161,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');
             };
@@ -1200,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). -->
@@ -1215,89 +1190,59 @@ 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().
+         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;
         --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, #3d434b);
+        --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) */
-      :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;
-      }
-      /* 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;
-        }
-      }
+      /* 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. */
@@ -1311,7 +1256,24 @@ 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">
+    <!-- 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>
   \`;
@@ -1322,75 +1284,36 @@ export default function RootLayout({ children }: { children: unknown }) {
   // demo and the example app, and a footer with the docs + source links. Treat it
   // as a starting point: prune the demos you do not use (delete the
   // app/features/<x> route AND its modules/<x>), then reshape this page into the
-  // app's real landing page. For the saas template a login/signup CTA row is
-  // spliced under the tagline.
-  const homeAuthLinks = isSaas
-    ? '\n          <div class="flex flex-wrap gap-3 items-center justify-center mt-2"><a href="/login" class="inline-flex items-center px-4 py-2 rounded-lg bg-primary text-primary-foreground text-sm font-medium no-underline hover:opacity-90">Log in</a><a href="/signup" class="inline-flex items-center px-4 py-2 rounded-lg border border-border text-foreground text-sm font-medium no-underline hover:bg-accent">Create an account</a></div>'
-    : '';
+  // 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';
+// 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/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/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">
-      <!-- Masthead -->
+    <div class="py-8 flex flex-col items-center gap-16">
+      <!-- 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.
-        </p>${homeAuthLinks}
+          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="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>
@@ -1400,9 +1323,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>
@@ -1414,8 +1337,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
@@ -1439,6 +1362,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';
 
@@ -1474,9 +1399,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);
   }
 
@@ -1486,7 +1412,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()}"
@@ -1505,12 +1431,6 @@ ThemeToggle.register('theme-toggle');
 `);
   } // end if (!isApi)
 
-  // --- SaaS template extras: auth, dashboard, drizzle User model ---
-  if (isSaas) {
-    const { writeSaasFiles } = await import('./saas-template.js');
-    await writeSaasFiles(appDir, { runtime });
-  }
-
   // AGENTS.md is already in place via the shared `templateFiles` loop
   // earlier in this function, so no framework-root fallback needed.
 
@@ -1531,20 +1451,11 @@ ThemeToggle.register('theme-toggle');
     modules/users/{actions,queries,types.ts}   ← routes over server actions
     db/{schema,columns,connection}.server.ts   ← Drizzle (User model)
     ${guide}
-`);
-  } else if (isSaas) {
-    console.log(`  ${name}/
-    app/{layout,page}.ts, login/, signup/
-    app/dashboard/{page,settings,middleware}.ts  ← protected
-    app/api/auth/[...path]/route.ts              ← auth API
-    components/ui/*, components/theme-toggle.ts
-    modules/auth/*, lib/{auth,password}.server.ts
-    db/{schema,columns,connection}.server.ts     ← Drizzle (User model)
-    ${guide}
 `);
   } else {
     console.log(`  ${name}/
-    app/{layout,page}.ts          ← a minimal home to grow in place
+    app/{layout,page}.ts          ← gallery home; gallery:clear grows in place
+    app/features/*, modules/*     ← browsable demos (incl. auth: login + protected route)
     components/theme-toggle.ts
     public/input.css              ← Tailwind entry (compiles to public/tailwind.css)
     db/{schema,columns,connection}.server.ts  ← Drizzle
@@ -1593,9 +1504,9 @@ ThemeToggle.register('theme-toggle');
   // Next-steps banner prints LAST so the actionable command is the
   // final thing on screen, never buried above the AI-agent guidance.
   // Single copy-paste line so the user can move from "scaffold done"
-  // to "dev server up" in one command. The full-stack and saas
-  // templates ship with @webjsdev/ui already initialised; the api
-  // template has no UI but may add one later.
+  // to "dev server up" in one command. The full-stack template ships
+  // with @webjsdev/ui already initialised; the api template has no UI
+  // but may add one later.
   const installSegment = installed ? '' : `${pm} install && `;
   // The shipped schema is applied on the first `run dev` (webjs.*.before runs
   // `db migrate`), but only if a migration FILE exists. When we installed, we

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.44",
+  "version": "0.10.46",
   "type": "module",
   "description": "webjs CLI - dev, start, create, db",
   "bin": {