@webjskit/cli 0.4.4 → 0.5.0

package/README.md

@@ -36,13 +36,24 @@ webjs create <name> --template api   # backend-only API app
 webjs create <name> --template saas  # auth + dashboard + Prisma User model
 
 webjs dev                      # dev server with live reload
-webjs start                    # production server
-webjs build                    # production bundle
+webjs start                    # production server (no build step — serves source directly)
 webjs check                    # validate project conventions
 webjs test                     # run server + browser tests
 webjs db <prisma-subcommand>   # prisma passthrough (saas template)
+
+webjs ui init                  # initialise @webjskit/ui in this project
+webjs ui add <names...>        # copy components from the registry (https://ui.webjs.dev/registry/<name>.json)
+webjs ui list                  # list every component available in the registry
 ```
 
+`webjs ui` proxies to [`@webjskit/ui`](https://www.npmjs.com/package/@webjskit/ui),
+an AI-first component library + CLI that copies sources into your project — class
+helpers (`buttonClass`, `cardClass`, …) for the visual primitives and a small set
+of stateful custom elements (`<ui-dialog>`, `<ui-tabs>`, `<ui-popover>`) where
+state matters. The package is a hard dependency of `@webjskit/cli` — installing
+the CLI gives you `webjs ui` automatically. See
+[https://ui.webjs.dev](https://ui.webjs.dev) for the catalogue.
+
 ## Scaffolded templates
 
 The scaffold seeds opinionated defaults so AI agents produce consistent code:

package/bin/webjs.js

@@ -13,9 +13,7 @@ const TEMPLATES = ['full-stack', 'api', 'saas'];
 
 const USAGE = `webjs — commands:
   webjs dev   [--port 3000]                       Start dev server with live reload
-  webjs start [--port 3000]                       Start production server (serves source directly; no build required)
-              [--http2 --cert <path> --key <path>]  Serve HTTP/2 over TLS (falls back to h1.1)
-  webjs build                                     Optional: bundle client modules into a single file (advanced/perf opt-in)
+  webjs start [--port 3000]                       Start production server (serves source directly; no build step)
   webjs test  [--server|--browser]                 Run server + browser tests
   webjs check                                     Validate app against conventions
   webjs create <name> [--template full-stack|api|saas]  Scaffold a new webjs app
@@ -23,6 +21,9 @@ const USAGE = `webjs — commands:
   webjs db generate                               Run \`prisma generate\`
   webjs db migrate [name]                         Run \`prisma migrate dev\`
   webjs db studio                                 Run \`prisma studio\`
+  webjs ui <subcmd>                               AI-first component library CLI
+                                                  (init / add / list / view / diff / info)
+                                                  Requires @webjskit/ui installed in the project
   webjs help                                      Show this help`;
 
 /** @param {string[]} args */
@@ -79,23 +80,7 @@ async function main() {
     case 'start': {
       const { startServer } = await import('@webjskit/server');
       const port = Number(flag(rest, '--port', process.env.PORT || 3000));
-      const http2 = rest.includes('--http2');
-      const cert = flag(rest, '--cert');
-      const key = flag(rest, '--key');
-      await startServer({ appDir: process.cwd(), port, dev: false, http2, cert, key });
-      break;
-    }
-    case 'build': {
-      const { buildBundle } = await import('@webjskit/server');
-      const t = Date.now();
-      const result = await buildBundle({
-        appDir: process.cwd(),
-        minify: rest.includes('--no-minify') ? false : true,
-        sourcemap: rest.includes('--no-sourcemap') ? false : true,
-      });
-      if (result.bundleFile) {
-        console.log(`webjs: bundled ${result.entries.length} entries → ${result.bundleFile} (${Date.now() - t}ms)`);
-      }
+      await startServer({ appDir: process.cwd(), port, dev: false });
       break;
     }
     case 'db': {
@@ -108,6 +93,32 @@ async function main() {
       child.on('exit', (code) => process.exit(code ?? 0));
       break;
     }
+    case 'ui': {
+      // Delegate to @webjskit/ui. Bundled as a hard dependency of
+      // @webjskit/cli — `npm install -g @webjskit/cli` pulls it in
+      // automatically, so `webjs ui add button` works out of the box
+      // without an extra install in user projects.
+      const { createRequire } = await import('node:module');
+      const req = createRequire(import.meta.url);
+      let entry;
+      try {
+        entry = req.resolve('@webjskit/ui/bin/webjsui.js');
+      } catch {
+        // Fallback: try resolving from the user's cwd in case of weird
+        // workspace setups.
+        try {
+          const userReq = createRequire(join(process.cwd(), 'package.json'));
+          entry = userReq.resolve('@webjskit/ui/bin/webjsui.js');
+        } catch {
+          console.error('@webjskit/ui could not be resolved.');
+          console.error('Reinstall the CLI:  npm install -g @webjskit/cli');
+          process.exit(1);
+        }
+      }
+      const child = spawn('node', [entry, ...rest], { stdio: 'inherit', cwd: process.cwd() });
+      child.on('exit', (code) => process.exit(code ?? 0));
+      break;
+    }
     case 'test': {
       const cwd = process.cwd();
       const { existsSync } = await import('node:fs');

package/lib/create.js

@@ -19,6 +19,122 @@ import { existsSync } from 'node:fs';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES = resolve(__dirname, '..', 'templates');
 
+// Root of the @webjskit/ui registry workspace. We read component sources
+// directly from disk at create time so the scaffolded app boots ready for
+// `webjs ui add` without an HTTP round-trip during scaffolding.
+//
+// Layout in the monorepo:
+//   packages/cli/lib/create.js                       ← __dirname
+//   packages/ui/packages/registry/components/*.ts
+//   packages/ui/packages/registry/lib/utils.ts
+//   packages/ui/packages/registry/themes/index.css
+const UI_REGISTRY_ROOT = resolve(
+  __dirname, '..', '..', 'ui', 'packages', 'registry',
+);
+
+/**
+ * Read a single @webjskit/ui registry component, rewrite its relative import
+ * of `../lib/utils.ts` so it resolves correctly when written to
+ * `components/ui/<name>.ts` in the scaffolded app (which puts utils at
+ * `lib/utils.ts`, i.e. two levels up), and return the rewritten source.
+ *
+ * @param {string} name  component name without `.ts` (e.g. 'button')
+ * @returns {Promise<string|null>} source or null if not found
+ */
+async function readUiComponent(name) {
+  const src = join(UI_REGISTRY_ROOT, 'components', `${name}.ts`);
+  if (!existsSync(src)) return null;
+  const raw = await readFile(src, 'utf8');
+  // The registry source lives at <registry>/components/<x>.ts and imports
+  // its sibling utils via '../lib/utils.ts'. Once copied to the user's
+  // project at components/ui/<x>.ts, the equivalent path is two-up:
+  // '../../lib/utils.ts'. Same rewrite for the unquoted form.
+  return raw
+    .replaceAll("'../lib/utils.ts'", "'../../lib/utils.ts'")
+    .replaceAll('"../lib/utils.ts"', '"../../lib/utils.ts"');
+}
+
+/**
+ * Copy a list of @webjskit/ui registry components into the scaffolded app
+ * under `components/ui/`. Silently skips any name that isn't in the registry.
+ *
+ * @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 content = await readUiComponent(n);
+    if (content == null) continue;
+    await writeFile(join(uiDir, `${n}.ts`), content);
+  }
+}
+
+/**
+ * Write `lib/utils.ts` (the `cn()` helper) and `components.json` so the
+ * scaffolded app is pre-initialised for `webjs ui add`. Reads `lib/utils.ts`
+ * verbatim from the registry source so we never drift.
+ *
+ * @param {string} appDir
+ */
+async function writeUiBootstrap(appDir) {
+  // 1) lib/utils.ts — the cn() helper
+  const utilsSrc = join(UI_REGISTRY_ROOT, 'lib', 'utils.ts');
+  if (existsSync(utilsSrc)) {
+    const content = await readFile(utilsSrc, 'utf8');
+    await mkdir(join(appDir, 'lib'), { recursive: true });
+    await writeFile(join(appDir, 'lib', 'utils.ts'), content);
+  }
+
+  // 2) components.json — the same shape `webjsui init` writes for webjs
+  // projects (see packages/ui/src/utils/detect-project.js).
+  const componentsJson = {
+    $schema: 'https://ui.webjs.dev/schema.json',
+    style: 'default',
+    tailwind: {
+      css: 'app/globals.css',
+      baseColor: 'neutral',
+      cssVariables: true,
+    },
+    aliases: {
+      components: 'components',
+      utils: 'lib/utils',
+      ui: 'components/ui',
+      lib: 'lib',
+    },
+    iconLibrary: 'lucide',
+  };
+  await writeFile(
+    join(appDir, 'components.json'),
+    JSON.stringify(componentsJson, null, 2) + '\n',
+  );
+
+  // 3) app/globals.css — copy the neutral theme verbatim. components.json
+  // references this path; future `webjs ui add` calls append to it.
+  const themeSrc = join(UI_REGISTRY_ROOT, 'themes', 'index.css');
+  if (existsSync(themeSrc)) {
+    const css = await readFile(themeSrc, 'utf8');
+    await mkdir(join(appDir, 'app'), { recursive: true });
+    await writeFile(join(appDir, 'app', 'globals.css'), css);
+  }
+}
+
+/**
+ * Read the shadcn theme CSS so we can inline it into the layout's
+ * `<style type="text/tailwindcss">` block. The Tailwind browser runtime
+ * picks up inline `<style type="text/tailwindcss">` content, so the theme
+ * tokens (`--color-primary`, `--color-card`, …) the registry components
+ * consume are available at runtime without a build step.
+ *
+ * @returns {Promise<string>} theme CSS source, or '' if registry missing
+ */
+async function readThemeCss() {
+  const src = join(UI_REGISTRY_ROOT, 'themes', 'index.css');
+  if (!existsSync(src)) return '';
+  return await readFile(src, 'utf8');
+}
+
 /**
  * @param {string} name  App directory name
  * @param {string} cwd   Current working directory
@@ -91,6 +207,10 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // @webjskit/ts-plugin bundles ts-lit-plugin internally, so just one
       // plugin entry is needed in tsconfig (see below).
       '@webjskit/ts-plugin': 'latest',
+      // AI-first component library CLI — preinstalled so `webjs ui add button`
+      // works immediately after scaffold. Users can remove if they prefer
+      // to add it later.
+      '@webjskit/ui': 'latest',
     },
   }, null, 2) + '\n');
 
@@ -257,8 +377,8 @@ export async function createUser(input: { name: string; email: string }) {
  * /api/users — thin route wrapper over typed server actions.
  * Business logic lives in modules/users/, not here.
  */
-import { listUsers } from '../../../../modules/users/queries/list-users.server.ts';
-import { createUser } from '../../../../modules/users/actions/create-user.server.ts';
+import { listUsers } from '../../../modules/users/queries/list-users.server.ts';
+import { createUser } from '../../../modules/users/actions/create-user.server.ts';
 
 export async function GET() {
   return Response.json(await listUsers());
@@ -322,9 +442,45 @@ export type ActionResult<T> =
       await cp(uiSrc, join(utilsDir, 'ui.ts'));
     }
 
+    // Pre-initialise @webjskit/ui so the scaffold boots ready for
+    // `webjs ui add <name>`: writes components.json + lib/utils.ts +
+    // app/globals.css (the shadcn theme).
+    await writeUiBootstrap(appDir);
+
+    // Copy the standard ui-* component kit the scaffold's example pages
+    // use. Sources are read from packages/ui/packages/registry/ in this
+    // monorepo. Users can `webjs ui add <name>` for anything else.
+    await copyUiComponents(appDir, [
+      'button', 'card', 'alert', 'badge', 'separator', 'label', 'input',
+    ]);
+
+    // The shadcn theme tokens (`--color-primary`, `--color-card`, …) the
+    // ui-* components consume. We read the registry's themes/index.css at
+    // create time and inline it into the layout's
+    // `<style type="text/tailwindcss">` block so the Tailwind browser
+    // runtime picks it up. Same content also lives at app/globals.css for
+    // `webjsui` tooling.
+    const SHADCN_THEME = (await readThemeCss())
+      // Escape backticks + ${} so the CSS survives interpolation into the
+      // layout's template literal below.
+      .replace(/\\/g, '\\\\')
+      .replace(/`/g, '\\`')
+      .replace(/\$\{/g, '\\${');
+
   await writeFile(join(appDir, 'app', 'layout.ts'), `import { html } from '@webjskit/core';
 import '@webjskit/core/client-router';
 import '../components/theme-toggle.ts';
+// Webjs UI components are tiered:
+//   - Tier 1 (button, card, input, label, alert, badge, separator, etc.) are
+//     class-helper FUNCTIONS — no custom element to register. Each page
+//     imports the specific helpers it needs (e.g.
+//     \`import { buttonClass } from '../components/ui/button.ts'\`).
+//   - Tier 2 (dialog, popover, tooltip, tabs, accordion, etc.) ARE custom
+//     elements. Register them by side-effect-importing here once so they
+//     work transitively across every page:
+//       import '../components/ui/dialog.ts';
+// The example app/page.ts below uses only Tier-1 helpers, so nothing
+// extra needs to be registered. Add Tier-2 imports as you 'webjs ui add'.
 
 /**
  * Root layout — globals + chrome.
@@ -355,6 +511,16 @@ export default function RootLayout({ children }: { children: unknown }) {
       })();
     </script>
     <script src="/public/tailwind-browser.js"></script>
+    <!--
+      Webjs UI theme — design tokens (--color-primary,
+      --color-card, --radius, etc.) the ui-* components consume.
+      The same content is also at app/globals.css; we inline it here so
+      the Tailwind browser runtime resolves the tokens without a build step.
+      Edit base palette via the :root / .dark blocks below.
+    -->
+    <style type="text/tailwindcss">
+${SHADCN_THEME}
+    </style>
     <style type="text/tailwindcss">
       @theme {
         --color-fg:            var(--fg);
@@ -460,6 +626,17 @@ export default function RootLayout({ children }: { children: unknown }) {
 
   await writeFile(join(appDir, 'app', 'page.ts'), `import { html } from '@webjskit/core';
 import { rubric, displayH1, accentLink } from './_utils/ui.ts';
+import { buttonClass } from '../components/ui/button.ts';
+import { badgeClass } from '../components/ui/badge.ts';
+import {
+  cardClass,
+  cardHeaderClass,
+  cardTitleClass,
+  cardDescriptionClass,
+  cardContentClass,
+} from '../components/ui/card.ts';
+import { alertClass, alertTitleClass, alertDescriptionClass } from '../components/ui/alert.ts';
+import { separatorClass } from '../components/ui/separator.ts';
 
 export const metadata = {
   title: '${name} — built with webjs',
@@ -470,14 +647,42 @@ export default function Home() {
     <section class="mb-18">
       \${rubric('welcome')}
       \${displayH1(html\`Hello from <span class="text-accent italic">${name}</span>.\`)}
-      <p class="text-lede leading-[1.5] text-fg-muted max-w-[56ch] m-0">
+      <p class="text-lede leading-[1.5] text-fg-muted max-w-[56ch] m-0 mb-6">
         Edit <code class="font-mono text-[0.9em]">app/page.ts</code> to get started.
         Run \${accentLink('#', 'webjs test')} to run tests and
         \${accentLink('#', 'webjs check')} to validate conventions.
       </p>
+      <div class="flex gap-3 items-center">
+        <button class=\${buttonClass()}>Get started</button>
+        <button class=\${buttonClass({ variant: 'outline' })}>View docs</button>
+        <span class=\${badgeClass({ variant: 'secondary' })}>v0.1</span>
+      </div>
     </section>
 
-    <section class="mt-18 pt-6 border-t border-border">
+    <div class=\${cardClass()} style="margin-bottom: 3rem">
+      <div class=\${cardHeaderClass()}>
+        <h3 class=\${cardTitleClass()}>Web Components + Server Actions</h3>
+        <p class=\${cardDescriptionClass()}>
+          Drop a custom element anywhere. Call a server action like a local
+          function — webjs rewrites the import into a typed RPC stub.
+        </p>
+      </div>
+      <div class=\${cardContentClass()}>
+        <div class=\${alertClass()}>
+          <h5 class=\${alertTitleClass()}>AI-first component kit included</h5>
+          <div class=\${alertDescriptionClass()}>
+            button, card, alert, badge, separator, label, input are already
+            in <code class="font-mono text-[0.9em]">components/ui/</code> as
+            class-helper functions you call from a native element. Add more
+            with <code class="font-mono text-[0.9em]">webjs ui add &lt;name&gt;</code>.
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <div class=\${separatorClass()} style="margin: 2.5rem 0"></div>
+
+    <section class="mt-10">
       <h2 class="font-serif text-[1.6rem] tracking-[-0.02em] font-bold m-0 mb-2">Light DOM + Tailwind</h2>
       <p class="text-fg-muted text-sm m-0 mb-4">
         Components render into light DOM by default. Tailwind utility classes
@@ -592,25 +797,43 @@ ThemeToggle.register('theme-toggle');
     app/layout.ts, page.ts, login/, signup/
     app/dashboard/{page,settings,middleware}.ts  ← protected
     app/api/auth/[...path]/route.ts      ← auth API
+    app/globals.css                      ← @webjskit/ui theme tokens
+    components.json                      ← preconfigured for \`webjs ui add\`
+    components/ui/{button,card,alert,badge,separator,label,input,
+                    dialog,form,field,switch,checkbox}.ts
+    components/theme-toggle.ts
     modules/auth/{actions,queries,types.ts}
-    lib/{auth,prisma,password}.ts
+    lib/{auth,prisma,password,utils}.ts  ← utils.ts is the cn() helper
     prisma/schema.prisma                 ← User model
-    components/theme-toggle.ts
     CONVENTIONS.md, AGENTS.md, CLAUDE.md
 `);
   } else {
     console.log(`  ${name}/
     app/layout.ts, page.ts       ← light DOM + Tailwind + @theme tokens
     app/_utils/ui.ts             ← JS helpers for repeated class bundles
-    public/tailwind-browser.js   ← Tailwind runtime
+    app/globals.css              ← @webjskit/ui theme tokens
+    components.json              ← preconfigured for \`webjs ui add\`
+    components/ui/{button,card,alert,badge,separator,label,input}.ts
     components/theme-toggle.ts   ← light DOM web component
+    lib/utils.ts                 ← cn() helper for ui-* components
+    public/tailwind-browser.js   ← Tailwind runtime
     modules/
     CONVENTIONS.md, AGENTS.md, CLAUDE.md
 `);
   }
+  // Post-scaffold guidance. The full-stack and saas templates ship with
+  // @webjskit/ui already initialised (components.json, lib/utils.ts, the
+  // standard kit under components/ui/), so the user only runs `webjs dev`.
+  // The api template has no UI; we only mention `webjs ui` in case the
+  // user later adds one.
+  const uiNote = isApi
+    ? `# If you later add a UI to this API project:
+  #   webjs ui init && webjs ui add button card dialog`
+    : `webjs ui add <name>     # optional — add more ui-* components later`;
   console.log(`Next steps:
   cd ${name}
   npm install${isSaas ? '\n  npx prisma migrate dev --name init' : ''}
+  ${uiNote}
   webjs dev
 
 AI-driven development (enforced for all AI agents):

package/lib/saas-template.js

@@ -3,13 +3,53 @@
  * Extracted to avoid nested template literal escaping issues.
  */
 
-import { mkdir, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { mkdir, writeFile, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const UI_REGISTRY_ROOT = resolve(
+  __dirname, '..', '..', 'ui', 'packages', 'registry',
+);
+
+/**
+ * Read a registry component and rewrite its `'../lib/utils.ts'` import for
+ * the scaffolded app's `components/ui/<name>.ts` layout (two-up to lib/).
+ * Mirrors the helper in `create.js` — kept private here to avoid coupling.
+ */
+async function readUiComponent(name) {
+  const src = join(UI_REGISTRY_ROOT, 'components', `${name}.ts`);
+  if (!existsSync(src)) return null;
+  const raw = await readFile(src, 'utf8');
+  return raw
+    .replaceAll("'../lib/utils.ts'", "'../../lib/utils.ts'")
+    .replaceAll('"../lib/utils.ts"', '"../../lib/utils.ts"');
+}
+
+/** Copy named registry components into `<appDir>/components/ui/`. */
+async function copyUiComponents(appDir, names) {
+  const uiDir = join(appDir, 'components', 'ui');
+  await mkdir(uiDir, { recursive: true });
+  for (const n of names) {
+    const content = await readUiComponent(n);
+    if (content == null) continue;
+    await writeFile(join(uiDir, `${n}.ts`), content);
+  }
+}
 
 /**
  * @param {string} appDir
  */
 export async function writeSaasFiles(appDir) {
+  // SaaS pages use auth forms — copy the extra ui-* components on top of
+  // the standard set the full-stack scaffold already wrote. Pre-importing
+  // them in login/signup/dashboard pages below means the dev server will
+  // SSR these elements with full styling on first paint.
+  // `form` and `field` are deferred to v2 (see packages/ui/AGENTS.md) —
+  // the saas auth pages use raw <form> + label/input class helpers instead.
+  await copyUiComponents(appDir, ['dialog', 'switch', 'checkbox']);
+
   // lib/prisma.ts
   await mkdir(join(appDir, 'lib'), { recursive: true });
   await writeFile(join(appDir, 'lib', 'prisma.ts'), [
@@ -194,18 +234,39 @@ export async function writeSaasFiles(appDir) {
   await mkdir(join(appDir, 'app', 'login'), { recursive: true });
   await writeFile(join(appDir, 'app', 'login', 'page.ts'), [
     "import { html } from '@webjskit/core';",
+    "import { cardClass, cardHeaderClass, cardTitleClass, cardDescriptionClass, cardContentClass, cardFooterClass } from '../../components/ui/card.ts';",
+    "import { buttonClass } from '../../components/ui/button.ts';",
+    "import { inputClass } from '../../components/ui/input.ts';",
+    "import { labelClass } from '../../components/ui/label.ts';",
     "",
     "export const metadata = { title: 'Login' };",
     "",
     "export default function LoginPage() {",
     "  return html`",
-    "    <h1>Login</h1>",
-    "    <form method=\"POST\" action=\"/api/auth/callback/credentials\">",
-    "      <label>Email <input type=\"email\" name=\"email\" required></label>",
-    "      <label>Password <input type=\"password\" name=\"password\" required></label>",
-    "      <button type=\"submit\">Sign in</button>",
-    "    </form>",
-    "    <p>Don't have an account? <a href=\"/signup\">Sign up</a></p>",
+    "    <div class=\"max-w-sm mx-auto mt-12\">",
+    "      <div class=${cardClass()}>",
+    "        <div class=${cardHeaderClass()}>",
+    "          <h3 class=${cardTitleClass()}>Sign in</h3>",
+    "          <p class=${cardDescriptionClass()}>Welcome back — log in to continue.</p>",
+    "        </div>",
+    "        <div class=${cardContentClass()}>",
+    "          <form method=\"POST\" action=\"/api/auth/callback/credentials\" class=\"flex flex-col gap-4\">",
+    "            <div class=\"flex flex-col gap-1.5\">",
+    "              <label class=${labelClass()} for=\"email\">Email</label>",
+    "              <input class=${inputClass()} id=\"email\" name=\"email\" type=\"email\" required>",
+    "            </div>",
+    "            <div class=\"flex flex-col gap-1.5\">",
+    "              <label class=${labelClass()} for=\"password\">Password</label>",
+    "              <input class=${inputClass()} id=\"password\" name=\"password\" type=\"password\" required>",
+    "            </div>",
+    "            <button class=${buttonClass()} type=\"submit\">Sign in</button>",
+    "          </form>",
+    "        </div>",
+    "        <div class=${cardFooterClass()}>",
+    "          <p class=\"text-sm text-muted-foreground\">Don't have an account? <a href=\"/signup\" class=\"underline\">Sign up</a></p>",
+    "        </div>",
+    "      </div>",
+    "    </div>",
     "  `;",
     "}",
     "",
@@ -215,19 +276,43 @@ export async function writeSaasFiles(appDir) {
   await mkdir(join(appDir, 'app', 'signup'), { recursive: true });
   await writeFile(join(appDir, 'app', 'signup', 'page.ts'), [
     "import { html } from '@webjskit/core';",
+    "import { cardClass, cardHeaderClass, cardTitleClass, cardDescriptionClass, cardContentClass, cardFooterClass } from '../../components/ui/card.ts';",
+    "import { buttonClass } from '../../components/ui/button.ts';",
+    "import { inputClass } from '../../components/ui/input.ts';",
+    "import { labelClass } from '../../components/ui/label.ts';",
     "",
     "export const metadata = { title: 'Sign up' };",
     "",
     "export default function SignupPage() {",
     "  return html`",
-    "    <h1>Sign up</h1>",
-    "    <form id=\"signup-form\">",
-    "      <label>Name <input type=\"text\" name=\"name\" required></label>",
-    "      <label>Email <input type=\"email\" name=\"email\" required></label>",
-    "      <label>Password <input type=\"password\" name=\"password\" required minlength=\"8\"></label>",
-    "      <button type=\"submit\">Create account</button>",
-    "    </form>",
-    "    <p>Already have an account? <a href=\"/login\">Log in</a></p>",
+    "    <div class=\"max-w-sm mx-auto mt-12\">",
+    "      <div class=${cardClass()}>",
+    "        <div class=${cardHeaderClass()}>",
+    "          <h3 class=${cardTitleClass()}>Create an account</h3>",
+    "          <p class=${cardDescriptionClass()}>Get started with your new workspace.</p>",
+    "        </div>",
+    "        <div class=${cardContentClass()}>",
+    "          <form id=\"signup-form\" class=\"flex flex-col gap-4\">",
+    "            <div class=\"flex flex-col gap-1.5\">",
+    "              <label class=${labelClass()} for=\"name\">Name</label>",
+    "              <input class=${inputClass()} id=\"name\" name=\"name\" type=\"text\" required>",
+    "            </div>",
+    "            <div class=\"flex flex-col gap-1.5\">",
+    "              <label class=${labelClass()} for=\"email\">Email</label>",
+    "              <input class=${inputClass()} id=\"email\" name=\"email\" type=\"email\" required>",
+    "            </div>",
+    "            <div class=\"flex flex-col gap-1.5\">",
+    "              <label class=${labelClass()} for=\"password\">Password</label>",
+    "              <input class=${inputClass()} id=\"password\" name=\"password\" type=\"password\" required>",
+    "            </div>",
+    "            <button class=${buttonClass()} type=\"submit\">Create account</button>",
+    "          </form>",
+    "        </div>",
+    "        <div class=${cardFooterClass()}>",
+    "          <p class=\"text-sm text-muted-foreground\">Already have an account? <a href=\"/login\" class=\"underline\">Log in</a></p>",
+    "        </div>",
+    "      </div>",
+    "    </div>",
     "  `;",
     "}",
     "",
@@ -252,15 +337,28 @@ export async function writeSaasFiles(appDir) {
   await writeFile(join(appDir, 'app', 'dashboard', 'page.ts'), [
     "import { html } from '@webjskit/core';",
     "import { currentUser } from '../../modules/auth/queries/current-user.server.ts';",
+    "import { cardClass, cardHeaderClass, cardTitleClass, cardDescriptionClass, cardContentClass } from '../../components/ui/card.ts';",
+    "import { buttonClass } from '../../components/ui/button.ts';",
+    "import { badgeClass } from '../../components/ui/badge.ts';",
     "",
     "export const metadata = { title: 'Dashboard' };",
     "",
     "export default async function Dashboard() {",
     "  const user = await currentUser();",
     "  return html`",
-    "    <h1>Dashboard</h1>",
-    "    <p>Welcome, ${`\\$\\{user?.name || user?.email\\}`}!</p>",
-    "    <a href=\"/dashboard/settings\">Settings</a>",
+    "    <div class=\"flex items-center justify-between mb-6\">",
+    "      <h1 class=\"text-2xl font-semibold\">Dashboard</h1>",
+    "      <span class=${badgeClass({ variant: 'secondary' })}>Signed in</span>",
+    "    </div>",
+    "    <div class=${cardClass()}>",
+    "      <div class=${cardHeaderClass()}>",
+    "        <h3 class=${cardTitleClass()}>Welcome, ${`\\$\\{user?.name || user?.email\\}`}!</h3>",
+    "        <p class=${cardDescriptionClass()}>You're authenticated. Replace this scaffold with your real app.</p>",
+    "      </div>",
+    "      <div class=${cardContentClass()}>",
+    "        <a class=${buttonClass({ variant: 'outline' })} href=\"/dashboard/settings\">Settings</a>",
+    "      </div>",
+    "    </div>",
     "  `;",
     "}",
     "",
@@ -270,15 +368,28 @@ export async function writeSaasFiles(appDir) {
   await writeFile(join(appDir, 'app', 'dashboard', 'settings', 'page.ts'), [
     "import { html } from '@webjskit/core';",
     "import { currentUser } from '../../../modules/auth/queries/current-user.server.ts';",
+    "import { cardClass, cardHeaderClass, cardTitleClass, cardDescriptionClass, cardContentClass } from '../../../components/ui/card.ts';",
     "",
     "export const metadata = { title: 'Settings' };",
     "",
     "export default async function Settings() {",
     "  const user = await currentUser();",
     "  return html`",
-    "    <h1>Settings</h1>",
-    "    <p>Email: ${`\\$\\{user?.email\\}`}</p>",
-    "    <p>Name: ${`\\$\\{user?.name || 'Not set'\\}`}</p>",
+    "    <h1 class=\"text-2xl font-semibold mb-6\">Settings</h1>",
+    "    <div class=${cardClass()}>",
+    "      <div class=${cardHeaderClass()}>",
+    "        <h3 class=${cardTitleClass()}>Account</h3>",
+    "        <p class=${cardDescriptionClass()}>Your basic profile information.</p>",
+    "      </div>",
+    "      <div class=${cardContentClass()}>",
+    "        <dl class=\"grid grid-cols-[max-content_1fr] gap-x-6 gap-y-2 text-sm\">",
+    "          <dt class=\"text-muted-foreground\">Email</dt>",
+    "          <dd>${`\\$\\{user?.email\\}`}</dd>",
+    "          <dt class=\"text-muted-foreground\">Name</dt>",
+    "          <dd>${`\\$\\{user?.name || 'Not set'\\}`}</dd>",
+    "        </dl>",
+    "      </div>",
+    "    </div>",
     "  `;",
     "}",
     "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjskit/cli",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "type": "module",
   "description": "webjs CLI — dev, start, create, db",
   "bin": {
@@ -13,7 +13,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@webjskit/server": "0.4.2"
+    "@webjskit/server": "0.5.0",
+    "@webjskit/ui": "0.1.0"
   },
   "publishConfig": {
     "access": "public"

package/templates/AGENTS.md

@@ -112,6 +112,113 @@ layered on top:
 See [docs.webjs.com → Editor setup](https://docs.webjs.com/docs/editor-setup)
 for the full walkthrough.
 
+## UI components — Webjs UI (preinstalled)
+
+This scaffold ships with the standard Webjs UI component kit
+**already installed at `components/ui/`**. The kit is **AI-first** and
+splits into two tiers. Internalise the split — picking the wrong tier
+produces broken markup.
+
+### Tier 1 — class-helper functions (the majority)
+
+Pure functions that return Tailwind class strings. You apply them to
+**raw native HTML elements** that you write yourself. Examples:
+`button`, `card`, `input`, `label`, `alert`, `badge`, `separator`,
+`skeleton`, `kbd`, `table`, `breadcrumb`, `pagination`, `native-select`,
+`avatar`, `checkbox`, `switch`, `radio-group`, `textarea`, `toggle`,
+`aspect-ratio`.
+
+```ts
+import {
+  cardClass, cardHeaderClass, cardTitleClass,
+  cardContentClass, cardFooterClass,
+} from '../../components/ui/card.ts';
+import { inputClass } from '../../components/ui/input.ts';
+import { labelClass } from '../../components/ui/label.ts';
+import { buttonClass } from '../../components/ui/button.ts';
+
+return html`
+  <div class=${cardClass()}>
+    <div class=${cardHeaderClass()}>
+      <h3 class=${cardTitleClass()}>Profile</h3>
+    </div>
+    <div class=${cardContentClass()}>
+      <label class=${labelClass()} for="name">Name</label>
+      <input class=${inputClass()} id="name" name="name">
+    </div>
+    <div class=${cardFooterClass()}>
+      <button class=${buttonClass()}>Save</button>
+    </div>
+  </div>
+`;
+```
+
+Helpers with variants take an options object:
+`buttonClass({ variant: 'outline', size: 'sm' })`.
+
+### Tier 2 — stateful custom elements
+
+For things the browser doesn't provide natively (focus traps, portaled
+overlays, keyboard-navigated lists): `dialog`, `alert-dialog`, `popover`,
+`tooltip`, `hover-card`, `tabs`, `accordion`, `collapsible`,
+`dropdown-menu`, `progress`, `sonner`, `toggle-group`. These ARE custom
+elements — import them once (typically in `app/layout.ts`) and use
+`<ui-X>` tags:
+
+```ts
+// app/layout.ts (registers the custom elements for every page)
+import '../components/ui/dialog.ts';
+import '../components/ui/tabs.ts';
+```
+
+```ts
+// app/some-page/page.ts (uses the registered elements)
+import { buttonClass } from '../../components/ui/button.ts';
+
+return html`
+  <ui-dialog>
+    <ui-dialog-trigger>
+      <button class=${buttonClass({ variant: 'outline' })}>Edit</button>
+    </ui-dialog-trigger>
+    <ui-dialog-content>
+      <h2>Edit profile</h2>
+      ...
+    </ui-dialog-content>
+  </ui-dialog>
+`;
+```
+
+### Adding more components
+
+```sh
+webjs ui add dialog dropdown-menu tabs progress
+```
+
+Each `webjs ui add` call fetches the component source from
+`https://ui.webjs.dev/registry/<name>.json`, copies it into
+`components/ui/`, and installs any required npm deps. Run
+`webjs ui list` to browse the catalogue or visit
+[https://ui.webjs.dev](https://ui.webjs.dev).
+
+### AI agents — picking the right tier
+
+For forms, dashboards, settings pages, marketing layouts: **call the
+Tier-1 class helpers on raw native elements**. You get accessibility,
+visual consistency, and form submission semantics for free —
+`<input class=${inputClass()}>` is a real `<input>`, with native
+autofill, browser validation, and `<form>` submission unchanged.
+
+For modals, dropdowns, tooltips, tab strips, accordions: use the
+Tier-2 `<ui-X>` custom element tags after importing the corresponding
+module.
+
+The composition style is deliberately **not** shadcn's
+component-everything React API. We use native elements + class helpers
+for the visual stuff because hiding a `<button>` inside a `<Button>`
+wrapper adds zero value and obscures the real element from inspection,
+form submission, and screen readers. Custom elements are reserved for
+behavior the browser can't deliver natively.
+
 ## File conventions
 
 ```
@@ -235,18 +342,85 @@ type-safe RPC stub automatically.
 
 ## Metadata (per-page)
 
+The `metadata` export is Next.js-compatible. Common fields shown below;
+the full surface includes `title.template / .default / .absolute`,
+`metadataBase`, `alternates: { canonical, languages, media, types }`,
+`robots`, `keywords`, `authors`, `creator`, `publisher`, `verification`,
+`icons`, `manifest`, `appleWebApp`, `formatDetection`, `itunes`, and
+the typed `other: { '<meta-name>': value }` escape hatch.
+
 ```ts
 export const metadata = {
   title: 'My page',
+  // OR: title: { template: '%s — {{APP_NAME}}', default: '{{APP_NAME}}' }
   description: 'A page in {{APP_NAME}}',
-  openGraph: { type: 'website', image: 'https://...' },
+  metadataBase: 'https://example.com',           // base for relative URLs below
+  openGraph: { type: 'website', image: '/og.png' },
   twitter: { card: 'summary_large_image' },
-  cacheControl: 'public, max-age=60',  // opt into caching (default: no-store)
+  icons: { icon: '/favicon.svg', apple: '/apple.png' },
+  alternates: { canonical: '/post' },            // → <link rel="canonical">
+  robots: { index: true, follow: true },
+  cacheControl: 'public, max-age=60',            // opt into caching (default: no-store)
 };
 ```
 
 Use `generateMetadata(ctx)` when you need request-scoped values (e.g.
-absolute URLs from `ctx.url`).
+absolute URLs from `ctx.url`):
+
+```ts
+export function generateMetadata(ctx: { url: string }) {
+  return { metadataBase: new URL(ctx.url).origin, title: 'Hello' };
+}
+```
+
+Viewport may be split into its own export (Next.js 14+ pattern):
+
+```ts
+export const viewport = {
+  width: 'device-width',
+  initialScale: 1,
+  themeColor: '#1c1613',
+  colorScheme: 'light dark',
+};
+```
+
+## Document shell (`<html>` / `<head>` / `<body>`)
+
+The framework owns the shell by default. The SSR pipeline auto-emits
+`<!doctype html><html lang="en"><head>…</head><body>` around every
+composition, and auto-hoists `<link>` / `<style>` / `<meta>` / `<script>`
+tags returned anywhere in a layout/page into the real `<head>`. The
+`metadata` export drives `<title>` and `<meta>` tags.
+
+**Only `app/layout.ts` (the root layout)** may optionally write its
+own `<!doctype><html><head>…</head><body>` shell to override `<html lang>`,
+`<html dir>`, `<html data-*>`, `<body class>`, or add a custom
+`<link rel="preconnect">` etc. When the root layout supplies a shell,
+the framework respects it and splices its required tags into the
+user's `<head>`.
+
+```ts
+// app/layout.ts — root, optionally owning the shell
+export default function RootLayout({ children }) {
+  return html`
+    <!doctype html>
+    <html lang="es" data-theme="dark">
+      <head>
+        <link rel="preconnect" href="https://cdn.example.com">
+      </head>
+      <body class="min-h-screen bg-bg">
+        <main>${children}</main>
+      </body>
+    </html>
+  `;
+}
+```
+
+**Non-root layouts** (`app/<segment>/layout.ts`) and **pages**
+(`app/**/page.ts`) **must NOT** write `<!doctype>` / `<html>` / `<head>`
+/ `<body>`. The framework auto-emits the wrapper around the whole
+composition, so a nested shell ends up dropped by the HTML parser.
+`webjs check` enforces this via the `shell-in-non-root-layout` rule.
 
 ## Invariants (do not violate)
 

package/templates/CONVENTIONS.md

@@ -345,6 +345,64 @@ with puppeteer or playwright imports.
 
 ---
 
+## UI components — prefer the Webjs UI kit over raw Tailwind
+
+<!-- OVERRIDE -->
+
+This scaffold ships with the Webjs UI kit preinstalled at `components/ui/`.
+The kit splits into **two tiers** — picking the wrong tier produces
+broken markup.
+
+**Tier 1 — class helpers** (button, card, input, label, alert, badge,
+separator, skeleton, table, etc.): pure functions that return Tailwind
+class strings. Call them and spread onto a **raw native element**.
+
+**Tier 2 — custom elements** (dialog, popover, tooltip, dropdown-menu,
+tabs, accordion, collapsible, progress, etc.): real `<ui-X>` tags. Import
+the module once (typically in `app/layout.ts`) and use the tag.
+
+```ts
+// Tier 1 — class helpers on native elements (use this for forms,
+// dashboards, cards, layouts — anywhere the value is purely visual)
+import { buttonClass } from '../components/ui/button.ts';
+import { inputClass } from '../components/ui/input.ts';
+return html`
+  <button class=${buttonClass({ size: 'lg' })}>Save</button>
+  <input class=${inputClass()} placeholder="Email">
+`;
+
+// Tier 2 — custom elements (modals, dropdowns, tab strips, tooltips —
+// state the browser doesn't give you natively)
+return html`
+  <ui-dialog>
+    <ui-dialog-trigger>
+      <button class=${buttonClass({ variant: 'outline' })}>Edit</button>
+    </ui-dialog-trigger>
+    <ui-dialog-content>…</ui-dialog-content>
+  </ui-dialog>
+`;
+
+// Avoid — hand-rolled Tailwind on every <button> loses visual
+// consistency. Tier-1 helpers give you the same control with one import.
+return html`
+  <button class="px-4 py-2 rounded-md bg-accent text-accent-fg">Save</button>
+`;
+```
+
+Add more components with `webjs ui add <name>` (e.g. `webjs ui add dialog
+tabs popover`). The catalogue lives at
+[https://ui.webjs.dev](https://ui.webjs.dev).
+
+**Hand-rolled Tailwind is still appropriate for:**
+- One-off marketing pages, hero sections, landing CTAs.
+- Anywhere the visual design intentionally diverges from the kit baseline.
+- Layout primitives (`<div class="grid grid-cols-3 gap-4">`).
+
+The convention: any visual element with a Tier-1 helper uses the helper.
+Any stateful behavior with a Tier-2 element uses the element.
+
+---
+
 ## Components
 
 <!-- OVERRIDE -->