@webjsdev/cli 0.10.38 → 0.10.40

package/lib/create.js

@@ -233,9 +233,9 @@ async function writeUiBootstrap(appDir) {
 
   // 3) styles/globals.css: copy the neutral theme verbatim. components.json
   // references this path, and future `webjs ui add` calls append to it. It
-  // lives OUTSIDE app/ because app/ is routing-only; the layout inlines the
-  // same tokens into a <style type="text/tailwindcss"> block so the browser
-  // Tailwind runtime resolves them with no build step.
+  // lives OUTSIDE app/ because app/ is routing-only. The same @theme maps are
+  // written to public/input.css and compiled to the static public/tailwind.css
+  // the layout links (so the app is styled with JavaScript off).
   const css = await readFile(
     join(UI_REGISTRY_ROOT, 'themes', 'index.css'), 'utf8',
   );
@@ -244,11 +244,11 @@ async function writeUiBootstrap(appDir) {
 }
 
 /**
- * Read the @webjsdev/ui 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.
+ * Read the @webjsdev/ui theme CSS so we can write it into public/input.css,
+ * which css:build compiles into the static public/tailwind.css the layout
+ * links. The theme tokens (`--color-primary`, `--color-card`, …) the registry
+ * components consume become real utility classes in the compiled stylesheet,
+ * so the app is styled with JavaScript off.
  *
  * @returns {Promise<string>} theme CSS source
  */
@@ -344,6 +344,15 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     throw new Error(`Unknown --runtime '${runtime}'. Only ${VALID_RUNTIMES.join(' / ')} are supported.`);
   }
   const isBun = runtime === 'bun';
+  // Tailwind compile commands (#947). A UI scaffold compiles a STATIC stylesheet
+  // (not the browser runtime), so it renders styled with JavaScript off. The
+  // compiler is a node-shebang CLI, so a Bun app (whose Dockerfile is a node-less
+  // `oven/bun:1` image, #595) must run it under Bun via `bun --bun`; a Node app
+  // runs it directly (the before / regenerate steps get node_modules/.bin on PATH
+  // via envWithLocalBin). Deliberately NOT `npm run css:build` in the hooks: the
+  // Bun image has no npm, so that step would exit 127 and abort the boot.
+  const twBin = isBun ? 'bun --bun tailwindcss' : 'tailwindcss';
+  const cssBuildCmd = `${twBin} -i ./public/input.css -o ./public/tailwind.css --minify`;
   const appDir = join(cwd, name);
   if (existsSync(appDir)) {
     console.error(`Error: directory '${name}' already exists.`);
@@ -399,6 +408,13 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // / doctor) stay plain `webjs ...`: they spawn node tooling (`node --test`,
       // drizzle-kit, tsc) and forcing `--bun` there buys nothing (and `webjs
       // test` shells `node --test`, which a `bun --test` would not be).
+      // Compile Tailwind from public/input.css to a STATIC public/tailwind.css
+      // that app/layout.ts links, so the app is fully styled with JavaScript
+      // DISABLED (a real stylesheet, not an in-browser compile). Runs inside the
+      // dev and start tasks via the `before` hooks below. Runtime-aware: a Bun
+      // app runs the compiler under Bun (its image has no Node), a Node app runs
+      // it directly.
+      ...(isApi ? {} : { 'css:build': cssBuildCmd }),
       dev: isBun ? 'bun --bun webjs dev' : 'webjs dev',
       start: isBun ? 'bun --bun webjs start' : 'webjs start',
       test: 'webjs test',
@@ -447,6 +463,10 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // assertNoA11yViolations() test helper from @webjsdev/core/testing.
       // Test-only: dynamically imported, never shipped to the app runtime.
       'axe-core': '^4.10.0',
+      // The Tailwind v4 CLI that css:build runs to compile public/input.css into
+      // the static public/tailwind.css the layout links. UI templates only (the
+      // api template has no CSS). Build tooling, never shipped to the runtime.
+      ...(isApi ? {} : { '@tailwindcss/cli': '^4.1.0' }),
       // tsserver plugin, wired into tsconfig below. Gives the language
       // INTELLIGENCE (go-to-def, completions, diagnostics, hover inside html``
       // templates) in any tsserver editor with NO editor plugin installed,
@@ -466,13 +486,35 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     // `before` and run it in-process, so `npm run dev` / `start` (thin aliases
     // above) behave identically. Both apply pending migrations via `webjs db
     // migrate` (idempotent, a no-op when the db is current), so a freshly
-    // generated migration is applied without a manual step (#725). The scaffold
-    // uses the Tailwind browser runtime (no CSS build step), so there is no dev
-    // `parallel` watcher here; an app that adds the Tailwind CLI puts its
-    // `--watch` command under `webjs.dev.parallel`.
+    // generated migration is applied without a manual step (#725). For a UI
+    // template it ALSO compiles Tailwind in `before` so a freshly cloned app is
+    // styled on the very first boot with no manual step. The compile command is
+    // the runtime-aware `cssBuildCmd` (a Bun app runs it under Bun, since its
+    // image has no npm or Node), NOT `npm run css:build`. The api template has no
+    // CSS, so it gets neither.
+    //
+    // In dev the static public/tailwind.css is kept fresh by `dev.regenerate`
+    // (#967), NOT a background `tailwindcss --watch`. A watch that dies mid-
+    // session or never starts serves stale/missing CSS with no error (a newly
+    // added utility class has no backing rule, so the app renders unstyled
+    // locally while prod is fine). `regenerate` instead recompiles ON REQUEST
+    // when the output is older than a source (or missing): the framework rebuilds
+    // it before serving `/public/tailwind.css`, so there is no watch process to
+    // die and no staleness window. Same `cssBuildCmd` as prod, so dev and prod
+    // resolve classes identically (nothing to diverge). `inputs` mirrors the
+    // input.css @source globs (the dirs Tailwind scans for classes).
     webjs: {
-      dev: { before: ['webjs db migrate'] },
-      start: { before: ['webjs db migrate'] },
+      dev: {
+        before: isApi ? ['webjs db migrate'] : ['webjs db migrate', cssBuildCmd],
+        ...(isApi ? {} : {
+          regenerate: [{
+            output: 'public/tailwind.css',
+            command: cssBuildCmd,
+            inputs: ['app', 'components', 'modules', 'lib', 'public/input.css'],
+          }],
+        }),
+      },
+      start: { before: isApi ? ['webjs db migrate'] : ['webjs db migrate', cssBuildCmd] },
     },
   }, null, 2) + '\n');
 
@@ -534,6 +576,11 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     'AGENTS.md',
     'CONVENTIONS.md',
     'CLAUDE.md',
+    // A worked layout (header/nav/theme-toggle/reading-column/footer) the agent
+    // reads to learn the patterns, since app/layout.ts ships as a minimal shell
+    // so the app designs its own chrome. Shipped for every template (harmless
+    // for api, which has no app/layout.ts).
+    'LAYOUT-REFERENCE.md',
     // Starter tests under the new feature-folder layout.
     'test/hello/hello.test.ts',
     'test/hello/browser/hello.test.js',
@@ -563,6 +610,14 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     '.claude/hooks/require-tests-with-src.sh',
     '.claude/hooks/check-server-imports.sh',
     '.claude/hooks/check-server-imports.mjs',
+    // Render-and-look enforcement for UI work: a UserPromptSubmit router that
+    // points UI-building prompts at the webjs-design-review skill, a Stop-hook
+    // backstop that nudges a render-and-look before finishing UI changes, and
+    // the skill they route to. A design/layout defect has no failing test, so
+    // this vision-in-the-loop is the only thing that catches it.
+    '.claude/hooks/route-skills.sh',
+    '.claude/hooks/design-review-before-stop.sh',
+    '.claude/skills/webjs-design-review/SKILL.md',
     // Gemini CLI config + hooks
     '.gemini/settings.json',
     '.gemini/hooks/nudge-uncommitted.sh',
@@ -638,7 +693,7 @@ export async function scaffoldApp(name, cwd, opts = {}) {
 
   // Make hook scripts executable
   const { chmod } = await import('node:fs/promises');
-  for (const hook of ['block-prose-punctuation.sh', 'guard-branch-context.sh', 'nudge-uncommitted.sh', 'commit-before-stop.sh', 'cleanup-merged-worktree.sh', 'require-tests-with-src.sh']) {
+  for (const hook of ['block-prose-punctuation.sh', 'guard-branch-context.sh', 'nudge-uncommitted.sh', 'commit-before-stop.sh', 'cleanup-merged-worktree.sh', 'require-tests-with-src.sh', 'route-skills.sh', 'design-review-before-stop.sh']) {
     const hookPath = join(appDir, '.claude', 'hooks', hook);
     if (existsSync(hookPath)) await chmod(hookPath, 0o755);
   }
@@ -675,6 +730,9 @@ export const table = sqliteTableCreator((name) => name, 'snake_case');
 export const pk = () => integer().primaryKey({ autoIncrement: true });
 export const uuidPk = () => text().primaryKey().$defaultFn(() => crypto.randomUUID());
 export const uuid = () => text();
+// Structured value (array / object) stored as JSON. Type it with json<T>() so
+// the column is narrowed on read/write instead of \`unknown\`.
+export const json = <T>() => text({ mode: 'json' }).$type<T>();
 export const bool = () => integer({ mode: 'boolean' });
 export const timestamp = () => integer({ mode: 'timestamp_ms' });
 export const createdAt = () => timestamp().notNull().defaultNow();
@@ -686,7 +744,7 @@ export const index = (...cols: SQLiteColumn[]) =>
   _index(getTableName((cols[0] as unknown as { table: Table }).table) + '_' + cols.map((c) => c.name).join('_') + '_idx').on(...(cols as [SQLiteColumn, ...SQLiteColumn[]]));
 `;
 
-  const columnsPg = `import { pgTableCreator, serial, uuid as pgUuid, integer, text, real, boolean, timestamp as pgTimestamp, index as _index } from 'drizzle-orm/pg-core';
+  const columnsPg = `import { pgTableCreator, serial, uuid as pgUuid, integer, text, real, boolean, jsonb, timestamp as pgTimestamp, index as _index } from 'drizzle-orm/pg-core';
 import type { PgColumn } from 'drizzle-orm/pg-core';
 import { getTableName, type Table } from 'drizzle-orm';
 
@@ -697,6 +755,9 @@ export const table = pgTableCreator((name) => name, 'snake_case');
 export const pk = () => serial().primaryKey();
 export const uuidPk = () => pgUuid().primaryKey().defaultRandom();
 export const uuid = () => pgUuid();
+// Structured value (array / object) stored as JSON. Type it with json<T>() so
+// the column is narrowed on read/write instead of \`unknown\`.
+export const json = <T>() => jsonb().$type<T>();
 export const bool = () => boolean();
 export const timestamp = () => pgTimestamp({ withTimezone: true });
 export const createdAt = () => timestamp().notNull().defaultNow();
@@ -710,13 +771,16 @@ export const index = (...cols: PgColumn[]) =>
 
   // Example schema (dialect-agnostic). Replace the User model with your own.
   await writeFile(join(appDir, 'db', 'schema.server.ts'), `import { defineRelations } from 'drizzle-orm';
-import { table, pk, ${isFullStack ? 'uuidPk, ' : ''}text, ${isFullStack ? 'bool, ' : ''}createdAt } from './columns.server.ts';
+import { table, pk, ${isFullStack ? 'uuidPk, ' : ''}text, ${isFullStack ? 'bool, ' : ''}json, createdAt } from './columns.server.ts';
 
 // Example model. Feel free to delete or extend.
 export const users = table('users', {
   id: pk(),
   email: text().notNull().unique(),
   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 }>(),
   createdAt: createdAt(),
 });
 ${isFullStack ? `
@@ -998,15 +1062,13 @@ export type ActionResult<T> =
   if (!isApi) {
     // Full-stack and SaaS templates: layout + page + theme toggle + Tailwind
 
-    // Copy the Tailwind browser runtime + lib/utils/ui.ts helpers from
-    // the scaffold templates directory so the app boots with the exact
-    // blog example architecture: light DOM + Tailwind + JS helpers.
+    // 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
+    // are copied below, so the app boots with the exact blog example
+    // architecture: light DOM + a real Tailwind stylesheet (styled with JS off)
+    // + JS helpers.
     const publicDir = join(appDir, 'public');
     await mkdir(publicDir, { recursive: true });
-    const tailwindSrc = join(TEMPLATES, 'public', 'tailwind-browser.js');
-    if (existsSync(tailwindSrc)) {
-      await cp(tailwindSrc, join(publicDir, 'tailwind-browser.js'));
-    }
     // 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).
@@ -1051,21 +1113,46 @@ export type ActionResult<T> =
     // use. See CONVENTIONS.md "prune what the app does not use".
     if (!isApi) await copyGallery(appDir);
 
-    // The @webjsdev/ui 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 styles/globals.css for
-    // `webjsui` tooling.
-    const UI_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'), `// webjs-scaffold-placeholder. This is the example app chrome (brand, nav, content-width container). Adapt it to your app, then delete this line. webjs check fails while the marker remains.
-import { html, cspNonce } from '@webjsdev/core';
+    // The @webjsdev/ui theme (`--color-primary`, `--color-card`, the @theme maps,
+    // @custom-variant, @keyframes) plus the app @theme mappings are compiled from
+    // public/input.css into the STATIC public/tailwind.css that app/layout.ts
+    // links, so the app is fully styled with JavaScript disabled. Write input.css:
+    // `@import "tailwindcss"`, source globs, the ui theme (read from the registry
+    // themes/index.css), then the app @theme inline block. The token VALUES live
+    // on :root in app/layout.ts (plain CSS, so they resolve with JS off) and the
+    // @theme inline maps here reference them by var(), the same split the blog
+    // uses. Same theme also lives at styles/globals.css for `webjsui` tooling.
+    const uiThemeRaw = await readThemeCss();
+    await writeFile(join(publicDir, 'input.css'), `@import "tailwindcss";
+
+/* Scan app sources so their utility classes make it into the compiled bundle.
+   Tailwind v4 auto-scans the project too; these @source lines are explicit. */
+@source "../app/**/*.{ts,js}";
+@source "../components/**/*.{ts,js}";
+@source "../modules/**/*.{ts,js}";
+@source "../lib/**/*.{ts,js}";
+
+${uiThemeRaw}
+
+/* App @theme mappings. The token VALUES live on :root in app/layout.ts (plain
+   CSS custom properties, so they resolve with JavaScript disabled); these
+   @theme inline maps turn them into utilities (bg-primary, text-display, ...). */
+@theme inline {
+  --color-border-strong: var(--border-strong);
+  --color-primary-tint: var(--primary-tint);
+  --font-sans:  var(--font-sans);
+  --font-serif: var(--font-serif);
+  --font-mono:  var(--font-mono);
+  --text-display: clamp(2.6rem, 1.6rem + 3.2vw, 4.25rem);
+  --text-h1:      clamp(2rem, 1.5rem + 1.6vw, 2.85rem);
+  --text-h2:      clamp(1.35rem, 1.15rem + 0.7vw, 1.7rem);
+  --text-lede:    clamp(1.05rem, 0.95rem + 0.3vw, 1.2rem);
+  --duration-fast: 140ms;
+  --duration-slow: 380ms;
+}
+`);
+
+  await writeFile(join(appDir, 'app', 'layout.ts'), `import { html, cspNonce } from '@webjsdev/core';
 import '#components/theme-toggle.ts';
 // Webjs UI components are tiered:
 //   - Tier 1 (button, card, input, label, alert, badge, separator, etc.) are
@@ -1080,21 +1167,18 @@ import '#components/theme-toggle.ts';
 // extra needs to be registered. Add Tier-2 imports as you 'webjs ui add'.
 
 /**
- * Root layout: globals + chrome.
+ * Root layout: globals + a minimal shell.
  *
  * Light DOM + Tailwind by default. Design tokens live in :root and are
  * mapped into the Tailwind palette via @theme, so classes like
  * text-foreground, bg-card, font-serif, duration-fast, text-display all work.
  *
- * Nav + footer links repeat the same class bundle, so they're extracted
- * into small JS helpers below. Each helper runs at SSR time inside
- * html\\\`\\\`, producing static HTML in the response with no client runtime.
+ * This shell is deliberately MINIMAL: it wires the theme, tokens, and Tailwind,
+ * then renders \${children} in a bare container with no chrome, so you design the
+ * app's own layout. LAYOUT-REFERENCE.md (project root) is a complete worked
+ * layout (header, nav, theme toggle, reading column, footer) to learn from.
  */
 
-const navLink = (href: string, label: string) => html\`
-  <a href=\${href} class="text-muted-foreground no-underline font-medium text-[13px] leading-none tracking-[0.005em] transition-colors duration-fast hover:text-foreground">\${label}</a>
-\`;
-
 export default function RootLayout({ children }: { children: unknown }) {
   // Read the in-flight request's CSP nonce so the theme-detection
   // inline script below passes strict CSP (script-src 'nonce-...').
@@ -1111,7 +1195,8 @@ export default function RootLayout({ children }: { children: unknown }) {
       // Delete this IIFE, delete the dark and light style blocks below, and set
       // your palette once on the root selector. That removes the wiring so it
       // cannot fight your own colours (it will not override a plain root
-      // palette). The header-measure IIFE that follows is unrelated, keep it.
+      // palette). The header-measure IIFE that follows is unrelated, keep it
+      // (it is dormant until you add a fixed header, per LAYOUT-REFERENCE.md).
       (function(){
         try {
           var mq = window.matchMedia('(prefers-color-scheme: light)');
@@ -1132,11 +1217,13 @@ export default function RootLayout({ children }: { children: unknown }) {
         } catch (_) {}
       })();
       // ===== end optional theme apparatus =====
-      // The header is position:fixed (not sticky): a sticky header flickers on
-      // iOS WebKit during a client-router nav. fixed leaves normal flow, so
-      // --header-h reserves its height for the content below. Measured here so
-      // it tracks the real (responsive) height; degrades fine with no JS via
-      // the :root default.
+      // Header-measure script: DORMANT until you add a fixed header (the minimal
+      // shell has none). When you add one (see LAYOUT-REFERENCE.md), make it
+      // position:fixed (NOT sticky: a sticky header flickers on iOS WebKit during
+      // a client-router nav). fixed leaves normal flow, so --header-h reserves its
+      // height for the content below; this measures the real (responsive) height.
+      // With no header it is a no-op (querySelector returns null) and --header-h
+      // stays 0, so there is no phantom gap.
       (function(){
         function measure(){
           try {
@@ -1153,34 +1240,31 @@ export default function RootLayout({ children }: { children: unknown }) {
         else measure();
       })();
     </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 styles/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">
-${UI_THEME}
-    </style>
-    <style type="text/tailwindcss">
-      /* ONE theme, canonical shadcn-style tokens. The @webjsdev/ui theme above
-         provides the token STRUCTURE and the @theme inline mappings that generate
+    <!-- Tailwind: a STATIC stylesheet compiled from public/input.css to
+         public/tailwind.css by css:build (run automatically by the dev and start
+         tasks; in dev it is also recompiled on request when a source changes, so
+         it never goes stale). A real stylesheet, so the app is fully styled with
+         JavaScript DISABLED (no in-browser compile). -->
+    <link rel="stylesheet" href="/public/tailwind.css">
+    <style>
+      /* ONE theme, canonical shadcn-style tokens. These are the token VALUES as
+         plain CSS custom properties, so the palette resolves with JavaScript
+         DISABLED and needs no build. public/input.css holds the token STRUCTURE
+         and the @theme inline mappings that generate
          bg-background, text-foreground, bg-card, bg-primary, bg-accent,
          text-muted-foreground, border-border, ring-ring, and the rest. Here we
          set those tokens' VALUES to this app's brand palette, so the ui-*
-         components AND the example chrome read ONE source of truth. Any component
-         added later with webjs ui add <name> inherits it automatically. This
-         block is emitted after the ui theme, so these values win on every Tailwind
-         recompile. Dark-first, with light via the theme toggle (data-theme) or the
+         components AND your own chrome read ONE source of truth. Any component
+         added later with webjs ui add <name> inherits it automatically. The
+         stylesheet is linked before this block, so these VALUES win over the ui
+         theme defaults. Dark-first, with light via the theme toggle (data-theme) or the
          OS. Follows the shadcn model: --primary is the BRAND color (orange, used
          for primary buttons, links, and emphasis), while --accent stays a NEUTRAL
          hover tint so the ui kit's outline/ghost/dropdown hover states keep proper
          contrast. Use bg-primary / text-primary for brand, bg-accent for hovers.
-         Add a new design token the canonical way, a --x variable below plus a
-         --color-x: var(--x) line in the @theme inline block, then use it as bg-x /
-         text-x. Reach for opacity modifiers
+         Add a new design token the canonical way, a --x VALUE below plus a
+         --color-x: var(--x) line in the @theme inline block in public/input.css,
+         then use it as bg-x / text-x. Reach for opacity modifiers
          (bg-primary/10, hover:bg-primary/90, border-border/60) before inventing a
          new token, but keep body text at full opacity so it stays above the AA
          contrast floor (a faded text-muted-foreground/70 measured 3.83:1). */
@@ -1188,11 +1272,16 @@ ${UI_THEME}
         --font-sans:  -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
         --font-serif: ui-serif, 'Iowan Old Style', Palatino, Georgia, serif;
         --font-mono:  ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
-        --header-h: 56px;
+        /* 0 by default because the minimal shell has no fixed header. The
+           header-measure script below overrides it to the real height the moment
+           you add a fixed header element (see LAYOUT-REFERENCE.md), so body
+           padding tracks it automatically. */
+        --header-h: 0px;
         /* A translucent brand tint, derived from --primary so it tracks
            light/dark automatically. Used for the logo glow and focus ring. */
         --primary-tint: color-mix(in oklch, var(--primary) 20%, transparent);
       }
+      /* webjs-scaffold-placeholder. These are the scaffold's STARTER brand colors (the shadcn-style orange); they look finished on purpose. Own the palette: set the token VALUES below (dark AND light blocks) to colors that fit what THIS app IS, keeping the token NAMES. A recolor chosen for the app beats keeping the starter orange. Then delete this marker line (or run webjs check --clear-placeholders to keep the starter palette deliberately). webjs check fails while the marker remains. */
       /* dark (the default, and the explicit .dark the toggle sets) */
       :root, .dark {
         color-scheme: dark;
@@ -1270,22 +1359,6 @@ ${UI_THEME}
           --logo-to: oklch(0.44 0.11 52);
         }
       }
-      @theme inline {
-        /* Only tokens the @webjsdev/ui theme does not already map live here. It
-           already maps --color-background/foreground/card/primary/secondary/
-           muted/accent/border/input/ring/destructive. */
-        --color-border-strong: var(--border-strong);
-        --color-primary-tint: var(--primary-tint);
-        --font-sans:  var(--font-sans);
-        --font-serif: var(--font-serif);
-        --font-mono:  var(--font-mono);
-        --text-display: clamp(2.6rem, 1.6rem + 3.2vw, 4.25rem);
-        --text-h1:      clamp(2rem, 1.5rem + 1.6vw, 2.85rem);
-        --text-h2:      clamp(1.35rem, 1.15rem + 0.7vw, 1.7rem);
-        --text-lede:    clamp(1.05rem, 0.95rem + 0.3vw, 1.2rem);
-        --duration-fast: 140ms;
-        --duration-slow: 380ms;
-      }
     </style>
     <style>
       /* Base styles utility classes can't reach. */
@@ -1300,42 +1373,10 @@ ${UI_THEME}
       ::selection { background: color-mix(in oklch, var(--primary) 22%, transparent); color: var(--foreground); }
     </style>
 
-    <header class="fixed inset-x-0 top-0 z-20 flex items-center gap-6 px-4 sm:px-6 py-3 border-b border-border bg-[color-mix(in_oklch,var(--background)_75%,transparent)] backdrop-blur-[18px]">
-      <a href="/" class="mr-auto inline-flex items-center gap-2 no-underline text-foreground font-semibold text-[15px] leading-none tracking-tight">
-        <span>${displayName}</span>
-      </a>
-      <nav class="flex gap-4 items-center">
-        <!-- Example nav. Replace with the real navigation for your app. -->
-        \${navLink('/', 'Home')}
-        <theme-toggle></theme-toggle>
-      </nav>
-    </header>
-
-    <!--
-      Content shell. The max-w-[760px] cap is a comfortable READING width,
-      right for prose, forms, and marketing. For a full-bleed app, dashboard,
-      or board, REPLACE it: widen the cap (for example max-w-[1400px]) or
-      drop the cap and mx-auto for an edge-to-edge layout. A wide layout left
-      inside the 760px reading column overflows into a horizontal scrollbar.
-    -->
-    <div class="flex flex-col min-h-[calc(100dvh-var(--header-h))]">
-      <main class="flex-1 w-full max-w-[760px] mx-auto px-4 sm:px-6 pt-[72px] pb-12">
-        \${children}
-      </main>
-      <!-- webjs-scaffold-placeholder. This "Built with webjs" footer is SCAFFOLD
-           branding, not your app's. REMOVE it, or replace it with your own
-           footer, before shipping a delivered app. Delete this line once done.
-           webjs check fails while the marker remains. -->
-      <footer class="border-t border-border">
-        <div class="max-w-[760px] mx-auto px-4 sm:px-6 py-6 flex items-center justify-center">
-          <a href="https://webjs.dev" class="inline-flex items-center gap-2 no-underline text-sm text-muted-foreground hover:text-foreground transition-colors">
-            <span>Built with</span>
-            <span class="w-[18px] h-[18px] rounded-[6px] bg-gradient-to-br from-[var(--logo-from)] to-[var(--logo-to)] shadow-[0_2px_10px_var(--primary-tint)]"></span>
-            <span class="font-semibold text-foreground">webjs</span>
-          </a>
-        </div>
-      </footer>
-    </div>
+    <!-- webjs-scaffold-placeholder. MINIMAL SHELL, on purpose. Everything above (the theme apparatus, the design tokens, the linked Tailwind stylesheet) is infrastructure to keep. Below, \${children} drops into a bare full-height container with NO chrome: design THIS app's layout from scratch. Decide from what the app IS whether it needs a header, a nav, a footer, a sidebar, a centered reading column, or a full-bleed canvas, and build that here. A COMPLETE reference layout (fixed header, brand, nav, theme toggle, reading column, footer) ships at LAYOUT-REFERENCE.md in the project root: read it to learn the patterns, then write your own. Delete this line once your layout is designed. webjs check fails while the marker remains. -->
+    <main class="min-h-dvh px-4 sm:px-6 py-8">
+      \${children}
+    </main>
   \`;
 }
 `);
@@ -1406,9 +1447,9 @@ export default function Home() {
       \${rubric('welcome')}
       \${displayH1(html\`Hello from <span class="text-primary italic">${displayName}</span>.\`)}
       <p class="text-lede leading-[1.5] text-muted-foreground max-w-[56ch] m-0 mb-6">
-        This scaffold ships a gallery below: single-feature demos and one whole
-        example app, all small, idiomatic, and heavily commented. Browse them for
-        context, then replace this page with your own. See
+        This WebJs scaffold ships a gallery below: single-feature demos and one
+        whole example app, all small, idiomatic, and heavily commented. Browse
+        them for context, then replace this page with your own. See
         \${accentLink('https://docs.webjs.dev', 'the docs')} for the full reference.
       </p>
       <div class="flex gap-3 items-center">
@@ -1669,7 +1710,7 @@ ThemeToggle.register('theme-toggle');
     components/theme-toggle.ts   ← light DOM web component
     lib/utils/cn.ts              ← cn() helper for ui-* components
     lib/utils/ui.ts              ← Tailwind class-bundle helpers
-    public/tailwind-browser.js   ← Tailwind runtime
+    public/input.css             ← Tailwind entry (compiled to public/tailwind.css)
     modules/{components,server-actions,optimistic-ui,async-render,
              directives,todo}/  ← feature + example logic (prune what you skip)
     db/{schema,columns,connection}.server.ts  ← Drizzle (User + Todo)

package/lib/db-hints.js

@@ -0,0 +1,34 @@
+// Actionable hints for `webjs db` failure modes that drizzle-kit surfaces
+// opaquely. Kept as pure functions so the dispatch path in bin/webjs.js stays a
+// thin spawn and the messages are unit-testable without a child process.
+
+// drizzle-kit prints this on stderr when a rename prompt has no TTY to answer.
+// It is the reliable signal: this drizzle-kit version EXITS 0 on that failure,
+// so the exit code cannot be used, and keying on stderr also means an unrelated
+// generate failure (a schema type error, a missing config) does NOT misfire.
+const TTY_PROMPT = /require a tty|interactive prompt/i;
+
+/**
+ * `webjs db generate` off a non-interactive stdin dead-ends when a table is
+ * renamed or swapped: drizzle-kit asks "is <newTable> a rename of <oldTable>?"
+ * and, with no TTY to answer, prints "Interactive prompts require a TTY" to
+ * stderr (and exits 0). Returns the escape-hatch hint only when the captured
+ * stderr carries that signature, so it fires on exactly that case and stays
+ * silent on success, an interactive run, another subcommand, or an unrelated
+ * generate error.
+ *
+ * @param {string} sub  the `webjs db` subcommand (generate|migrate|push|studio)
+ * @param {boolean|undefined} isTTY  process.stdin.isTTY
+ * @param {string|undefined} stderr  drizzle-kit's captured stderr
+ * @returns {string|null}
+ */
+export function dbGenerateTtyHint(sub, isTTY, stderr) {
+  if (sub !== 'generate' || isTTY) return null;
+  if (!TTY_PROMPT.test(stderr || '')) return null;
+  return (
+    '\nwebjs db generate needs an interactive terminal to resolve a table rename.\n' +
+    'Run it in a real terminal to answer the prompt, or, if the dev database has no\n' +
+    'data yet, delete the db/migrations/<initial> folder and re-run to author a clean\n' +
+    'create-table migration.'
+  );
+}

package/lib/design-bar.js

@@ -0,0 +1,67 @@
+// The design bar the scaffold sets (AGENTS.md / CONVENTIONS.md item 6): a
+// delivered UI app must have its OWN design, not the scaffold's. The scaffold is
+// a teaching artifact for how to USE the framework, never a starting design.
+// This lives in one place so the `--clear-placeholders` reminder and the
+// `webjs doctor` advisory speak with one voice (the clear command strips the
+// layout marker that carried this reminder just-in-time, so it is re-surfaced
+// there, and doctor catches an app that kept the shell anyway).
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * True when the app has a root layout, i.e. it is a UI app the design bar
+ * applies to. The `api` template ships no `app/layout`, so the reminder /
+ * advisory stay quiet there.
+ * @param {string} appDir
+ * @returns {boolean}
+ */
+export function hasUiLayout(appDir) {
+  return ['ts', 'js', 'mts', 'mjs'].some((e) => existsSync(join(appDir, 'app', `layout.${e}`)));
+}
+
+export const DESIGN_REMINDER =
+  '\nDesign: the scaffold is a TEACHING artifact, not a starting design.\n' +
+  'A delivered UI app must have its OWN design chosen from what the app IS:\n' +
+  'layout, palette, typography, icons, spacing, and chrome.\n' +
+  '- Layout: app/layout.ts ships as a MINIMAL shell (no header / nav / footer /\n' +
+  '  reading column). Design your own from what the app IS. LAYOUT-REFERENCE.md\n' +
+  '  shows the mechanics; do not reproduce its example header verbatim.\n' +
+  '- Palette: the design-token NAMES (--background, --primary, --card, ...) are\n' +
+  '  infrastructure to keep, but their COLOR VALUES are yours. Set a distinctive\n' +
+  '  palette that fits the app; keeping the starter orange is not a redesign.\n' +
+  '- Verify by USING it: render the app and play through every state, and confirm\n' +
+  '  nothing resizes or shifts as it fills (even, stable cells). A glance at the\n' +
+  '  empty first paint is not enough; the layout bugs show up mid-interaction.\n' +
+  'See AGENTS.md / CONVENTIONS.md item 6.';
+
+// Distinctive strings that indicate an app kept scaffold-specific chrome or the
+// unmodified starter palette, rather than designing its own. Counting them is an
+// objective proxy for "did not own the design" without judging taste. NOTE: the
+// theme apparatus (`--header-h`, the `theme-toggle` import) is KEEP-infrastructure
+// the minimal shell ships in every app, so it is NOT a tell (it fired on every
+// finished app and made the advisory nag forever). The tells that remain are
+// genuine "reproduced the scaffold" signals: the exact 760px reading column, the
+// scaffold's own attribution footer, and the two exact default palette VALUES (a
+// verbatim match means the palette was never changed; a recolor does not match).
+const SHELL_TELLS = [
+  { key: 'reading-column (max-w-[760px])', re: /max-w-\[760px\]/ },
+  // Specific to the scaffold's own attribution (its footer links webjs.dev and
+  // says "Built with webjs"). A bare "Built with ..." is a common bespoke footer,
+  // so it is NOT a tell on its own.
+  { key: 'attribution footer', re: /webjs\.dev|Built with webjs/ },
+  { key: 'default scaffold primary color', re: /--primary:\s*oklch\(0\.7\s+0\.16\s+52\)/ },
+  { key: 'default scaffold card color', re: /--card:\s*oklch\(0\.18\s+0\.01\s+55\)/ },
+];
+
+/**
+ * The scaffold-shell tells present in a root-layout source string. Two or more
+ * is a strong signal the app kept the scaffold chrome instead of designing its
+ * own. Returns the human-readable keys that matched.
+ * @param {string} layoutSrc
+ * @returns {string[]}
+ */
+export function scaffoldShellTells(layoutSrc) {
+  if (typeof layoutSrc !== 'string' || !layoutSrc) return [];
+  return SHELL_TELLS.filter((t) => t.re.test(layoutSrc)).map((t) => t.key);
+}