@webjsdev/cli 0.10.44 → 0.10.46

package/templates/gallery/modules/todo/components/todo-app.ts

@@ -10,6 +10,10 @@
 // one coherent theme. Prefer these tokens (and opacity modifiers like
 // bg-primary/90) over ad-hoc colors.
 import { WebComponent, prop, optimistic, html } from '@webjsdev/core';
+import { cardClass } from '#components/ui/card.ts';
+import { buttonClass } from '#components/ui/button.ts';
+import { bareInputClass } from '#components/ui/input.ts';
+import { cn } from '#lib/utils/cn.ts';
 import { createTodo } from '../actions/create-todo.server.ts';
 import { toggleTodo } from '../actions/toggle-todo.server.ts';
 import { deleteTodo } from '../actions/delete-todo.server.ts';
@@ -94,12 +98,12 @@ export class TodoApp extends WebComponent({
         <!-- Add: a real <form> so it works with JS off (posts to the page action);
              with JS, @submit intercepts and runs the optimistic path. -->
         <form method="post" action="" @submit=${(e: SubmitEvent) => this.add(e)}
-          class="flex items-center gap-2 p-2 pl-4 rounded-2xl bg-card border border-border shadow-[0_1px_0_0_color-mix(in_oklch,var(--foreground)_5%,transparent)]">
+          class="${cardClass()} flex items-center gap-2 p-2 pl-4 shadow-[0_1px_0_0_color-mix(in_oklch,var(--foreground)_5%,transparent)]">
           <input type="hidden" name="intent" value="create" />
           <input name="title" required maxlength="280" autocomplete="off" placeholder="What needs doing?"
-            class="flex-1 min-w-0 bg-transparent border-0 outline-none text-foreground text-[15px] placeholder:text-muted-foreground py-1.5" />
+            class=${bareInputClass()} />
           <button type="submit"
-            class="shrink-0 px-4 py-2 rounded-xl bg-primary text-primary-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-primary/90 active:scale-[0.97]">Add</button>
+            class="${buttonClass()} shrink-0">Add</button>
         </form>
 
         <ul class="list-none m-0 p-0 grid gap-2">
@@ -124,7 +128,7 @@ export class TodoApp extends WebComponent({
                 <!-- Delete: a proper icon button, revealed on row hover / focus. -->
                 <button type="submit" name="intent" value="delete" aria-label="Delete task"
                   @click=${(e: Event) => this.removeTodo(e, todo)}
-                  class="shrink-0 grid place-items-center w-7 h-7 rounded-lg border-0 bg-transparent text-muted-foreground cursor-pointer opacity-0 group-hover:opacity-100 focus:opacity-100 transition-all hover:text-destructive hover:bg-[color-mix(in_oklch,var(--color-destructive)_12%,transparent)]">
+                  class=${cn(buttonClass({ variant: 'destructive', size: 'none' }), 'w-7 h-7 rounded-lg opacity-0 group-hover:opacity-100 focus:opacity-100')}>
                   <svg viewBox="0 0 24 24" class="w-4 h-4 stroke-current fill-none" style="stroke-width:2;stroke-linecap:round;stroke-linejoin:round"><path d="M18 6 6 18M6 6l12 12"/></svg>
                 </button>
               </form>

package/templates/gallery/modules/websockets/components/ws-echo.ts

@@ -5,6 +5,8 @@
 // component renders its disconnected state, so with JS off the page still reads
 // (a live socket has no no-JS equivalent, which is the honest fallback here).
 import { WebComponent, signal, html, connectWS, renderStream } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
+import { inputClass } from '#components/ui/input.ts';
 
 export class WsEcho extends WebComponent {
   private connected = signal(false);
@@ -59,9 +61,9 @@ export class WsEcho extends WebComponent {
         </div>
         <form @submit=${(e: SubmitEvent) => this.send(e)} class="flex gap-2">
           <input name="msg" autocomplete="off" placeholder="Say something"
-            class="flex-1 px-3 py-2 rounded-xl bg-card border border-border text-foreground text-sm outline-none focus:border-border-strong" />
+            class=${inputClass('flex-1 min-w-0')} />
           <button type="submit"
-            class="px-3.5 py-2 rounded-xl bg-primary text-primary-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-primary/90 active:scale-[0.97]">Send</button>
+            class=${buttonClass({ size: 'sm' })}>Send</button>
         </form>
         <ul class="grid gap-1.5 list-none m-0 p-0">
           ${this.lines.get().map((line) => html`
@@ -70,7 +72,7 @@ export class WsEcho extends WebComponent {
         </ul>
         <div class="grid gap-2 border-t border-border pt-4">
           <button @click=${() => this.applyStreamUpdate()}
-            class="w-fit px-3.5 py-1.5 rounded-xl bg-card border border-border text-foreground text-sm cursor-pointer transition-colors hover:border-border-strong">renderStream() an element-level update</button>
+            class="${buttonClass({ variant: 'secondary', size: 'sm' })} w-fit">renderStream() an element-level update</button>
           <ul id="ws-stream-log" class="grid gap-1.5 list-none m-0 p-0"></ul>
         </div>
       </div>

package/templates/gallery/test/auth/auth.test.ts

@@ -0,0 +1,81 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+import { createRequestHandler } from '@webjsdev/server';
+import { testRequest, loginAndGetCookies, withSessionCookie } from '@webjsdev/server/testing';
+
+const appDir = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+// The auth pages + dashboard middleware query the users table via Drizzle. Until
+// `db:generate` has authored the migration (then `db:migrate` applies it, or
+// `dev` applies it via webjs.dev.before), a request hitting those modules 500s;
+// we detect that at the RESPONSE level (a 5xx on the dashboard) and SKIP with a
+// clear message rather than report a misleading failure. After the db is set up
+// every assertion runs for real.
+process.env.DATABASE_URL ||= 'file:./dev.db';
+process.env.AUTH_SECRET ||= 'test-secret-at-least-32-characters-long!!';
+
+function makeHandler() {
+  // createRequestHandler builds lazily, so it succeeds even before the DB is
+  // migrated; the missing table only surfaces when a request reaches a module
+  // that queries it. That is why readiness is probed per-response.
+  return createRequestHandler({ appDir, dev: true });
+}
+
+test('protected route redirects to login when unauthenticated', async (t) => {
+  const app = await makeHandler();
+  const res = await testRequest(app.handle, '/features/auth/dashboard');
+  if (res.status >= 500) {
+    t.skip('app deps not ready (run db:generate + db:migrate)');
+    return;
+  }
+  // The dashboard middleware calls auth(req); with no session cookie it 302s to
+  // login. This needs no DB row, only a cookie read, so it is always real once
+  // the modules import.
+  assert.equal(res.status, 302, 'unauthenticated dashboard is gated');
+  assert.equal(res.headers.get('location'), '/features/auth/login');
+});
+
+test('signup -> login -> dashboard renders for the authenticated user', async (t) => {
+  const app = await makeHandler();
+  // Probe readiness: a 5xx on the dashboard means deps/DB are not set up.
+  const probe = await testRequest(app.handle, '/features/auth/dashboard');
+  if (probe.status >= 500) { t.skip('app deps not ready; run db:generate + db:migrate'); return; }
+
+  const email = `harness+${Date.now()}@example.com`;
+  const password = 'password123';
+
+  // Real signup through the page server action (the no-JS form write-path).
+  let canSignup = true;
+  try {
+    const signupRes = await testRequest(app.handle, '/features/auth/signup', {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({ name: 'Harness', email, password }).toString(),
+    });
+    // Success auto-logs-in and 302s to the dashboard (carrying the session
+    // cookie); a 422 means validation failed. Either way the action ran.
+    assert.ok([302, 422].includes(signupRes.status), 'signup action ran');
+    if (signupRes.status === 302) assert.equal(signupRes.headers.get('location'), '/features/auth/dashboard', 'signup lands on the dashboard');
+    if (signupRes.status !== 302) canSignup = false;
+  } catch {
+    // No migrated DB table -> the action throws. Skip the DB-backed assertions.
+    canSignup = false;
+  }
+  if (!canSignup) { t.skip('no migrated DB; run db:migrate to enable the full flow'); return; }
+
+  // Real login captures the genuine signed session cookie.
+  const { cookies } = await loginAndGetCookies(app.handle, { email, password });
+
+  // With the session cookie the protected route now renders (200).
+  const dash = await testRequest(app.handle, '/features/auth/dashboard', withSessionCookie({}, cookies));
+  assert.equal(dash.status, 200, 'the session cookie unlocks the dashboard');
+  const body = await dash.text();
+  assert.match(body, /Dashboard/, 'the dashboard content rendered');
+  // The greeting interpolates the real user, so the name renders and the literal
+  // template source never leaks (a counterfactual for the escaping bug).
+  assert.match(body, /Harness/, 'the dashboard greets the signed-in user by name');
+  assert.ok(!body.includes('${user'), 'the greeting interpolation is not a literal string');
+});

package/templates/public/favicon.svg

@@ -1,5 +1,12 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" width="32" height="32" role="img" aria-label="WebJs">
-  <rect width="32" height="32" rx="7" fill="#e9edf0"/>
-  <path d="M8 11.5l4.5 4.5L8 20.5" fill="none" stroke="#1e2226" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round"/>
-  <line x1="15.5" y1="21.5" x2="23" y2="21.5" stroke="#1e2226" stroke-width="2.6" stroke-linecap="round"/>
+  <!-- Matches the gallery navbar brand mark (a rounded square with a
+       foreground -> muted-foreground gradient), using the DARK-theme token
+       values (#dee2e6 -> #94989c) so it reads on a dark browser tab bar. -->
+  <defs>
+    <linearGradient id="wj" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#dee2e6"/>
+      <stop offset="1" stop-color="#94989c"/>
+    </linearGradient>
+  </defs>
+  <rect width="32" height="32" rx="10" fill="url(#wj)"/>
 </svg>

package/templates/scripts/clear-api-gallery.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// Clear the api scaffold's backend-features showcase to a clean, buildable base.
+//
+// The api template ships a browsable showcase (JSON/HTTP endpoints under
+// app/api/features/, their modules, an env.ts example, and a starter test) so an
+// agent can learn the backend idioms from real, running code. It is the api
+// counterpart of the UI gallery's `gallery:clear`. Learn from the demos relevant
+// to your task first (the skill at .agents/skills/webjs/ teaches the same
+// patterns and SURVIVES this reset), then run this once to shed the showcase, then
+// grow the api in place.
+//
+// It removes the showcase routes + modules + the env.ts example + the widgets
+// test, and resets the root app/route.ts to list only the kept baseline endpoints
+// (/api/health, /api/users). It KEEPS the agent skill, middleware.ts (CORS), the
+// health + users endpoints, modules/users, the database wiring, and the users
+// example test. It is a one-time reset: if the showcase is already gone (no
+// app/api/features/) it does nothing, so a rerun never clobbers an app you built.
+import { rmSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const root = process.cwd();
+const rm = (p) => { if (existsSync(join(root, p))) { rmSync(join(root, p), { recursive: true, force: true }); return true; } return false; };
+
+// Guard: the showcase is identified by app/api/features/. If it is absent, the
+// showcase was already cleared (or this is not an api scaffold), so exit before
+// any destructive write. This keeps a rerun safe and never clobbers a built app.
+if (!existsSync(join(root, 'app/api/features'))) {
+  console.log('No backend-features showcase found (app/api/features/ is absent); nothing to clear.');
+  process.exit(0);
+}
+
+// 1) The showcase route tree + its module + the env.ts example + the widgets test.
+const showcasePaths = [
+  'app/api/features',
+  'modules/widgets',
+  'env.ts',
+  'test/unit/widgets.test.ts',
+];
+
+let removed = 0;
+for (const p of showcasePaths) if (rm(p)) removed++;
+
+// 2) Reset the root app/route.ts to list only the kept baseline endpoints. The
+// generated index also lists a `features:` block linking the showcase; strip it
+// (and its comment) so the index does not point at routes that no longer exist.
+// The regex preserves everything else (the app name, the health + users links).
+const routePath = join(root, 'app/route.ts');
+if (existsSync(routePath)) {
+  let s = readFileSync(routePath, 'utf8');
+  s = s.replace(/\n[ \t]*\/\/ The backend-features showcase[^\n]*\n[ \t]*features: \{[\s\S]*?\n[ \t]*\},\n/, '\n');
+  writeFileSync(routePath, s);
+}
+
+console.log(`Backend-features showcase cleared (${removed} paths removed). The agent skill, your database wiring, and the health + users endpoints are kept.`);
+console.log('Next: build your api in app/api/ and modules/, keeping server-only code behind .server.ts.');

package/templates/scripts/clear-gallery.mjs

@@ -9,17 +9,38 @@
 // same patterns and SURVIVES this reset, so nothing is lost), then run this
 // once to shed the gallery, then grow the app in place.
 //
-// It removes the gallery routes + modules + demo metadata routes, resets
-// app/page.ts to a minimal home, and drops the demo `todos` table from the
-// schema. It KEEPS the agent skill (.agents/skills/webjs/), the layout, the
-// database wiring, the theme toggle, and (for the saas template) the auth
-// modules. It is a one-time reset: if the gallery is already gone (no
-// app/features/) it does nothing, so a rerun never clobbers an app you built.
-import { rmSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+// It strips the app down to a TRULY BAREBONES blank slate: it removes the
+// gallery routes + modules + demo metadata routes, the gallery's example design
+// system (components/ui/), the example theme-toggle component, the example test
+// suite (test/hello/), and every empty leftover dir, then resets app/page.ts to
+// a minimal home AND app/layout.ts to a blank-slate base (the gallery's navbar,
+// theme toggle, Google Fonts, AND design-token palette dropped: the reset layout
+// carries NO design system, just the OS light/dark system colours, so the agent
+// builds the palette as its own, guided by the skill), and drops the demo `todos`
+// table plus the auth card's `passwordHash` column from the schema. It KEEPS only
+// the buildable base: the agent skill (.agents/skills/webjs/), the reset root
+// layout (the Tailwind wiring + a system-colour base, no tokens), the database
+// wiring, the example `users` table, and `lib/utils/cn.ts` (the `webjs ui add`
+// prerequisite).
+//
+// Why strip so much: the demos, the design system, and the example component /
+// tests are all EXAMPLES to learn FROM, not a base to inherit. Leaving them
+// nudges the implementing agent to lean on the scaffold's choices instead of
+// building the app's own. The DURABLE knowledge is the pattern itself, which
+// lives in the skill (.agents/skills/webjs/, re-read every session): learn it
+// from the gallery here, then after this reset build your own (run
+// `webjs ui add <name>` for UI primitives, cn.ts is kept for it) themed to your
+// app. It is a one-time reset: if the gallery is already gone (no app/features/)
+// it does nothing, so a rerun never clobbers an app you built.
+import { rmSync, rmdirSync, existsSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 
 const root = process.cwd();
 const rm = (p) => { if (existsSync(join(root, p))) { rmSync(join(root, p), { recursive: true, force: true }); return true; } return false; };
+// Remove a directory ONLY if it exists and is empty (used to clean the empty
+// parents a partial gallery removal leaves behind, e.g. app/api after its lone
+// auth handler is gone). Never touches a dir that still holds files.
+const pruneEmpty = (p) => { const abs = join(root, p); if (existsSync(abs) && readdirSync(abs).length === 0) { rmdirSync(abs); return true; } return false; };
 
 // Guard: the gallery is identified by app/features/. If it is absent, the gallery
 // was already cleared (or this is not a gallery scaffold), so exit before any
@@ -30,18 +51,37 @@ if (!existsSync(join(root, 'app/features'))) {
   process.exit(0);
 }
 
-// 1) Gallery route trees + example metadata routes.
+// 1) Gallery route trees + example metadata routes. `app/api/auth` is the auth
+// card's createAuth handler (it lives at the app root, not under app/features/,
+// because createAuth hardcodes /api/auth/*), and `test/auth` is the auth card's
+// request-pipeline test, so both are removed here alongside the card.
 const galleryPaths = [
-  'app/features', 'app/examples', 'app/sitemaps',
+  'app/features', 'app/examples', 'app/sitemaps', 'app/api/auth', 'test/auth',
   'app/icon.ts', 'app/apple-icon.ts', 'app/manifest.ts', 'app/opengraph-image.ts',
   'app/twitter-image.ts', 'app/robots.ts', 'app/sitemap.ts',
   'app/global-error.ts', 'app/global-not-found.ts',
+  // The gallery's EXAMPLE design system. Removed so the reset app is a blank
+  // slate: the agent builds its own components/ui/ (run `webjs ui add`, cn.ts is
+  // kept), learning the pattern from the skill, not inheriting the gallery's.
+  'components/ui',
+  // Example scaffold artifacts (invariant 2): the theme-toggle component and the
+  // example test suite are things to learn from, not the agent's app. Removed
+  // for a true blank slate; the root layout is reset to a minimal base below
+  // (which drops its toggle wiring). The agent writes its own tests + components.
+  'components/theme-toggle.ts', 'test/hello',
+  // The gallery's markup-chunk helpers. Their only users (the feature pages +
+  // the features/examples layouts) are removed above, so drop the example file
+  // too; cn.ts + dom.ts (real infrastructure) stay under lib/utils/.
+  'lib/utils/ui.ts',
 ];
-// 2) The gallery's feature modules (by name, so saas auth modules survive).
+// 2) The gallery's feature modules (by name). `auth` is the auth card's server
+// modules (createAuth config, password hashing, signup action, current-user
+// query), pruned with the rest of the card.
 const galleryModules = [
-  'async-render', 'broadcast', 'caching', 'client-router', 'components',
-  'directives', 'file-storage', 'frames', 'optimistic-ui', 'rate-limit',
-  'route-handler', 'server-actions', 'sessions', 'todo', 'websockets',
+  'async-render', 'auth', 'broadcast', 'caching', 'client-router', 'components',
+  'directives', 'file-storage', 'frames', 'gallery', 'optimistic-ui', 'rate-limit',
+  'route-handler', 'server-actions', 'sessions', 'stream', 'streaming', 'suspense',
+  'todo', 'websockets',
 ].map((m) => `modules/${m}`);
 
 let removed = 0;
@@ -50,26 +90,65 @@ for (const p of [...galleryPaths, ...galleryModules]) if (rm(p)) removed++;
 // 3) Reset app/page.ts to a minimal home (no gallery grid, no dead links).
 writeFileSync(join(root, 'app/page.ts'), MINIMAL_PAGE());
 
-// 4) Drop the demo `todos` table from the schema (keep everything else).
+// 4) Drop the demo `todos` table and the auth card's `passwordHash` column from
+// the schema (keep the example `users` table and everything else), reverting the
+// schema to the minimal base.
 const schemaPath = join(root, 'db/schema.server.ts');
 if (existsSync(schemaPath)) {
   let s = readFileSync(schemaPath, 'utf8');
   s = s.replace(/\n(?:\/\/[^\n]*\n)*export const todos = table\('todos',[\s\S]*?\n\}\);\n/, '\n');
   s = s.replace(/defineRelations\(\{ users, todos \}/, 'defineRelations({ users }');
+  // Strip the auth `passwordHash` column (and its leading comment lines) from the
+  // users table; the rest of the table is the minimal example base.
+  s = s.replace(/\n(?:[ \t]*\/\/[^\n]*\n)*[ \t]*passwordHash: text\(\),\n/, '\n');
   writeFileSync(schemaPath, s);
 }
 
-// 5) Drop generated migrations + the dev database so the next db:generate is
+// 5) Reset the root layout to a blank-slate base. The gallery layout ships a
+// navbar, a theme toggle, Google Fonts, and a full design-token palette; a blank
+// slate should inherit NONE of that, so OVERWRITE it with a minimal layout that
+// carries no design system: the Tailwind stylesheet + OS light/dark system
+// colours (Canvas / CanvasText) + a bare <main>. The agent then builds the
+// palette (CSS tokens + @theme + a light-dark() theme) as its own, guided by
+// .agents/skills/webjs/references/styling.md.
+// GUARD: overwrite only while the layout still carries the gallery's own navbar
+// brand. A hand-customised layout (the brand removed / replaced) is the user's
+// work, so it is KEPT and only the dangling references to the removed
+// theme-toggle file are stripped surgically.
+const layoutPath = join(root, 'app/layout.ts');
+if (existsSync(layoutPath)) {
+  const current = readFileSync(layoutPath, 'utf8');
+  if (current.includes('WebJs Gallery')) {
+    writeFileSync(layoutPath, MINIMAL_LAYOUT());
+  } else {
+    console.log('app/layout.ts looks customised; keeping it (only the theme-toggle wiring is stripped).');
+    writeFileSync(
+      layoutPath,
+      current
+        .replace(/^import '#components\/theme-toggle\.ts';\n/m, '')
+        .replace(/^\s*<theme-toggle><\/theme-toggle>\n?/m, ''),
+    );
+  }
+}
+
+// 6) Drop generated migrations + the dev database so the next db:generate is
 // clean against the reset schema (safe: the scaffold has no real data yet).
 rm('db/migrations');
 for (const f of ['db/dev.db', 'db/dev.db-shm', 'db/dev.db-wal']) rm(f);
 
-console.log(`Gallery cleared (${removed} paths removed). The agent skill and your database wiring are kept.`);
+// 7) Prune the empty leftover dirs a partial removal left behind, so the reset
+// tree is a clean blank slate: app/api (held only the gallery auth handler),
+// test/unit + test/e2e (empty base placeholders), and test/ itself once its
+// example suites are gone. modules/ + components/ are kept as empty build
+// targets (the reset home + `webjs ui add` land there). Order matters: prune the
+// children before test/ so it reads as empty.
+for (const d of ['app/api', 'test/unit', 'test/e2e', 'test']) if (pruneEmpty(d)) removed++;
+
+console.log(`Gallery cleared (${removed} paths removed). The agent skill and your database wiring are kept. Build your own design system: run \`npx webjsdev ui add <name>\` and theme it (see .agents/skills/webjs/references/styling.md).`);
 console.log('Next: regenerate the database (db:generate then db:migrate), then start the dev server and build your app in app/ and modules/.');
 
 function MINIMAL_PAGE() {
   return `import { html } from '@webjsdev/core';
-import '#components/theme-toggle.ts';
 
 export const metadata = {
   title: 'Home',
@@ -77,19 +156,59 @@ export const metadata = {
 
 export default function Home() {
   return html\`
-    <div class="fixed top-4 right-4 z-10"><theme-toggle></theme-toggle></div>
     <div class="max-w-2xl mx-auto px-6 py-24 flex flex-col items-center text-center gap-6">
       <h1 class="text-4xl font-bold tracking-tight m-0">Your app</h1>
-      <p class="text-base text-muted-foreground leading-relaxed m-0">
-        The gallery is cleared. This is <code class="text-[0.9em] text-foreground">app/page.ts</code>. Build your
-        app from here. The guide is <code class="text-[0.9em] text-foreground">.agents/skills/webjs/SKILL.md</code>.
+      <p class="text-base leading-relaxed m-0 opacity-70">
+        The gallery is cleared. This is <code class="text-[0.9em]">app/page.ts</code>. Build your
+        app from here. The guide is <code class="text-[0.9em]">.agents/skills/webjs/SKILL.md</code>.
       </p>
-      <nav class="flex items-center gap-5 text-sm text-muted-foreground">
-        <a href="https://docs.webjs.dev" class="hover:text-foreground transition-colors no-underline">Docs</a>
-        <a href="https://github.com/webjsdev/webjs" class="hover:text-foreground transition-colors no-underline">GitHub</a>
+      <nav class="flex items-center gap-5 text-sm opacity-70">
+        <a href="https://docs.webjs.dev" target="_blank" rel="noopener" class="hover:opacity-100 transition-opacity no-underline">Docs</a>
+        <a href="https://github.com/webjsdev/webjs" target="_blank" rel="noopener" class="hover:opacity-100 transition-opacity no-underline">GitHub</a>
       </nav>
     </div>
   \`;
 }
 `;
 }
+
+function MINIMAL_LAYOUT() {
+  return `import { html } from '@webjsdev/core';
+
+/**
+ * Root layout: the ONLY file that writes the document shell. It links the
+ * Tailwind stylesheet and renders \${children} in a bare container. This is a
+ * BLANK SLATE with no design system: it uses the OS light/dark system colours
+ * (Canvas / CanvasText) so it reads fine immediately, and it is where YOU build
+ * the app's look. The recommended setup, CSS custom-property tokens mapped into
+ * Tailwind via @theme (so bg-background / text-foreground work), a DRY
+ * light-dark() palette, a header/nav, and the ui class helpers, is taught in
+ * .agents/skills/webjs/references/styling.md. Run \`npx webjsdev ui add <name>\`
+ * to pull primitives, then theme them here.
+ */
+
+// Favicon via metadata.icons so the framework emits the <link> into <head> (a
+// hand-written <link> in the template body is ignored by browsers).
+export const metadata = { icons: '/public/favicon.svg' };
+
+export default function RootLayout({ children }: { children: unknown }) {
+  return html\`
+    <meta name="color-scheme" content="light dark">
+    <link rel="stylesheet" href="/public/tailwind.css">
+    <style>
+      html, body { margin: 0; }
+      body {
+        background: Canvas;
+        color: CanvasText;
+        font: 15px/1.6 ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+        -webkit-font-smoothing: antialiased;
+        -moz-osx-font-smoothing: grayscale;
+      }
+    </style>
+    <main class="min-h-dvh max-w-3xl mx-auto px-6 py-10">
+      \${children}
+    </main>
+  \`;
+}
+`;
+}

package/lib/lean-copy.js

@@ -1,43 +0,0 @@
-/**
- * The scaffold's lean-copy of a ui component (#983).
- *
- * `webjs create` copies a few `@webjsdev/ui` registry components into a
- * generated app. To match what `webjs ui add` writes, a Tier-1 helper's worked
- * `@example` is stripped (the example is served on demand by `webjs ui view` /
- * the MCP `ui` tool), while a Tier-2 element file is kept whole. Both scaffold
- * copiers (`create.js` and `saas-template.js`) go through THIS one helper so
- * they cannot drift.
- *
- * The strip primitives live in `@webjsdev/ui/registry/extract`; if that subpath
- * cannot be resolved, this degrades to a no-op (keep the example) so the strip
- * is never a reason `webjs create` fails.
- *
- * @module lean-copy
- */
-
-let _mod = null;
-
-async function loadPrimitives() {
-  if (_mod) return _mod;
-  try {
-    const m = await import('@webjsdev/ui/registry/extract');
-    _mod = { stripExample: m.stripExample, isCustomElementSource: m.isCustomElementSource };
-  } catch {
-    _mod = { stripExample: (s) => s, isCustomElementSource: () => true };
-  }
-  return _mod;
-}
-
-/**
- * Return the component source as `webjs ui add` would write it: a Tier-1 helper
- * has its worked `@example` stripped and a pointer left; a Tier-2 element is
- * returned unchanged.
- *
- * @param {string} source  the component source (imports already rewritten)
- * @param {string} name    the component name (for the pointer)
- * @returns {Promise<string>}
- */
-export async function leanComponentSource(source, name) {
-  const { stripExample, isCustomElementSource } = await loadPrimitives();
-  return isCustomElementSource(source) ? source : stripExample(source, name);
-}