@webjsdev/cli 0.10.29 → 0.10.31

package/lib/saas-template.js

@@ -106,7 +106,7 @@ export async function writeSaasFiles(appDir, opts = {}) {
   // add passwordHash (the column auth needs). Drizzle, dialect-agnostic.
   await writeFile(join(appDir, 'db', 'schema.server.ts'), [
     "import { defineRelations } from 'drizzle-orm';",
-    "import { table, pk, text, createdAt } from './columns.server.ts';",
+    "import { table, pk, uuidPk, text, bool, createdAt } from './columns.server.ts';",
     "",
     "export const users = table('users', {",
     "  id: pk(),",
@@ -116,7 +116,16 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "  createdAt: createdAt(),",
     "});",
     "",
-    "export const relations = defineRelations({ users }, () => ({}));",
+    "// Backs the example-gallery /examples/todo route (modules/todo). Delete it",
+    "// with the gallery when you prune the examples you do not use.",
+    "export const todos = table('todos', {",
+    "  id: uuidPk(),",
+    "  title: text().notNull(),",
+    "  completed: bool().notNull().default(false),",
+    "  createdAt: createdAt(),",
+    "});",
+    "",
+    "export const relations = defineRelations({ users, todos }, () => ({}));",
     "",
     "export type User = typeof users.$inferSelect;",
     "",
@@ -132,12 +141,19 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "import { db } from '#db/connection.server.ts';",
     "import { users } from '#db/schema.server.ts';",
     "import { hash } from '#lib/password.server.ts';",
-    "",
+    "import { signIn } from '#lib/auth.server.ts';",
+    "",
+    "// Creates the account, then signs the new user in and lands on the",
+    "// dashboard. signIn returns a 302 Response carrying the session cookie; the",
+    "// signup page action returns that Response as-is (a page action may return a",
+    "// Response). signIn lives in the server-only auth module, imported here",
+    "// server-to-server, so it never reaches the browser (the signup page only",
+    "// imports this action's RPC stub).",
     "export async function signup(input: { name: string; email: string; password: string }) {",
     "  const exists = await db.query.users.findFirst({ where: { email: input.email }, columns: { id: true } });",
     "  if (exists) return { success: false as const, error: 'Email already registered', status: 409 };",
-    "  const [user] = await db.insert(users).values({ name: input.name, email: input.email, passwordHash: await hash(input.password) }).returning();",
-    "  return { success: true as const, data: { id: user.id, name: user.name, email: user.email } };",
+    "  await db.insert(users).values({ name: input.name, email: input.email, passwordHash: await hash(input.password) });",
+    "  return signIn('credentials', { email: input.email, password: input.password }, { redirectTo: '/dashboard' });",
     "}",
     "",
   ].join('\n'));
@@ -252,10 +268,11 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "      headers: { 'content-type': 'application/x-www-form-urlencoded' },",
     "      body: new URLSearchParams({ name: 'Harness', email, password }).toString(),",
     "    });",
-    "    // Success is a 303 PRG to /login; a 422 means validation failed (still a",
-    "    // real response, just not the happy path). Either way the action ran.",
-    "    assert.ok([303, 422].includes(signupRes.status), 'signup action ran');",
-    "    if (signupRes.status !== 303) canSignup = false;",
+    "    // Success auto-logs-in and 302s to /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'), '/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;",
@@ -270,6 +287,10 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "  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');",
     "});",
     "",
   ].join('\n');
@@ -308,6 +329,8 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "        </div>",
     "        <div class=${cardContentClass()}>",
     "          <form method=\"POST\" action=\"/api/auth/signin/credentials\" class=\"flex flex-col gap-4\">",
+    "            <!-- createAuth reads redirectTo from the posted form and 302s there after a successful signin. -->",
+    "            <input type=\"hidden\" name=\"redirectTo\" value=\"/dashboard\">",
     "            <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>",
@@ -357,9 +380,10 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "  if (password.length < 8) fieldErrors.password = 'At least 8 characters';",
     "  if (Object.keys(fieldErrors).length) return { success: false, fieldErrors, values, status: 422 };",
     "  const result = await signup({ name, email, password });",
-    "  if (!result.success) return { success: false, fieldErrors: { email: result.error }, values, status: result.status };",
-    "  // Account created. Redirect to login via PRG so a reload will not resubmit.",
-    "  return { success: true, redirect: '/login' };",
+    "  // On success signup returns signIn's 302 Response (auto-login -> /dashboard);",
+    "  // a page action may return a Response, so pass it straight through.",
+    "  if (result instanceof Response) return result;",
+    "  return { success: false, fieldErrors: { email: result.error }, values, status: result.status };",
     "}",
     "",
     "export default function SignupPage({ actionData }: { actionData?: { fieldErrors?: Record<string, string>; values?: Record<string, string> } }) {",
@@ -436,7 +460,7 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "    </div>",
     "    <div class=${cardClass()}>",
     "      <div class=${cardHeaderClass()}>",
-    "        <h3 class=${cardTitleClass()}>Welcome, ${`\\$\\{user?.name || user?.email\\}`}!</h3>",
+    "        <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()}>",
@@ -468,9 +492,9 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "      <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>",
+    "          <dd>${user?.email}</dd>",
     "          <dt class=\"text-muted-foreground\">Name</dt>",
-    "          <dd>${`\\$\\{user?.name || 'Not set'\\}`}</dd>",
+    "          <dd>${user?.name || 'Not set'}</dd>",
     "        </dl>",
     "      </div>",
     "    </div>",

package/package.json

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

package/templates/.agents/rules/workflow.md

@@ -3,7 +3,7 @@
 You are working on a webjs app, an AI-first, no-build, web-components-first
 framework. Read AGENTS.md for the full API reference and CONVENTIONS.md for
 project-specific conventions before writing any code. When AGENTS.md does not
-cover what you need, the full hosted docs are at **https://docs.webjs.com**.
+cover what you need, the full hosted docs are at **https://docs.webjs.dev**.
 
 ## Persistence + scaffold rules (non-negotiable)
 
@@ -19,6 +19,39 @@ cover what you need, the full hosted docs are at **https://docs.webjs.com**.
   the example `User` model, the example users module, etc. with the app the
   user actually asked for. Do not ship "Hello from <app-name>" as the
   deliverable.
+- **Study the gallery first, prune it second.** The full-stack and saas scaffolds
+  ship single-feature demos under `app/features/` plus one whole example app under
+  `app/examples/` (logic in `modules/`). It is your PRIMARY webjs reference: read
+  every demo end to end (code AND comments) to learn the idioms BEFORE you write
+  or delete anything. Only after internalising the patterns should you prune,
+  keeping and adapting what you need and deleting the rest (the
+  `app/features/<name>` or `app/examples/<name>` route AND its `modules/<name>`;
+  for the todo app, also the `todos` table). Never delete blindly up front. Each
+  route page has a `webjs-scaffold-placeholder` marker so `webjs check` fails
+  until you resolve it. Delete now-empty directories after pruning. The `api`
+  template ships a BACKEND-features showcase instead (endpoints under
+  `app/api/features/`: the `route()` adapter + validation, rate limiting,
+  streaming, file storage, WebSockets + broadcast, plus `env.ts` validation),
+  listed in the root `app/route.ts` index; prune it the same way.
+- **Prune what the app does not use.** Keep the infrastructure the app USES
+  and delete the rest (files AND folders). No persistence means delete `db/`,
+  `drizzle.config.ts`, and the `db:*` scripts. No UI kit used means delete
+  `components/ui/`, `components.json`, and `lib/utils/cn.ts`. No PWA means
+  delete `public/sw.js` and `offline.html`. Always KEEP the durable knowledge
+  (`AGENTS.md`, `CONVENTIONS.md`, the rule files, the MCP), never prune it, so
+  removing example code never removes your context. Prune AFTER using the
+  features and examples as reference, never blindly up front. A no-op for the `api` template
+  (no UI kit, no PWA files).
+- **`app/` is routing-only.** Only routing files live in `app/` (page, layout,
+  route, middleware, metadata routes). CSS, helpers, and constants do NOT:
+  `globals.css` is at `styles/`, browser-safe helpers at `lib/utils/`, feature
+  logic in `modules/`.
+- **Use a unique design (UI apps).** When the app has a UI, give it a design of
+  your own (palette, layout, typography, chrome) that fits what the user asked
+  for. Do NOT mimic the scaffold's example look (its warm colors, the 760px
+  reading column, the example header/nav). The `api` template has no UI, so this
+  does not apply there. Keep the design tokens and theme setup in
+  `app/layout.ts`, those are infrastructure, and restyle on top of them.
 - **Only three templates exist:** `webjs create <name>` (default full-stack),
   `--template api`, `--template saas`. The CLI rejects any other `--template`
   value. Pick:
@@ -135,17 +168,46 @@ self-review loop.
   gradients); when unavoidable in a light-DOM component, prefix every class
   selector with the component tag. Shadow-DOM components legitimately use
   `static styles = css\`...\`` for scoped CSS.
+- **One theme, canonical tokens.** The app has a SINGLE theme, defined once in
+  `app/layout.ts` using the standard `@webjsdev/ui` (shadcn-compatible)
+  semantic tokens set to the brand palette. Use the canonical utility names
+  everywhere, in the page chrome AND inside components: `bg-background`,
+  `text-foreground`, `bg-card`, `bg-muted`, `text-muted-foreground`,
+  `bg-primary`, `text-primary-foreground`, `bg-accent`, `text-accent-foreground`,
+  `border-border`, `ring-ring`. These are exactly the tokens a component copied
+  in by `webjs ui add <name>` reads, so a scaffolded page and a later-added ui
+  component share one theme with no wiring. NEVER invent a parallel token
+  vocabulary (`--fg`, `--bg`, `text-fg`, `bg-elev`, a separate `--brand`): it
+  collides with the ui tokens (the accent once flipped to neutral on navigation
+  for exactly this reason) and diverges from the shadcn conventions the kit and
+  AI agents expect. Reach for opacity modifiers (`bg-primary/10`,
+  `hover:bg-primary/90`) before adding a token; add one the canonical way (a
+  `--x` var plus a `--color-x: var(--x)` line in `@theme inline`).
 - Custom-element tag names are passed to `.register('tag-name')`. They are NOT
   a static field on the class.
 - **Never extend raw HTMLElement directly for app components.** Always subclass `WebComponent` (or the factory form `WebComponent({...})`) to hook into SSR, lifecycle, elision, and the reactive property system. Extend raw HTMLElement only for rare native-API edge cases (like form-associated `ElementInternals` or customized built-in elements), and add a `webjs-allow-htmlelement: <reason>` comment to acknowledge the exception.
 - One function per server action file (`*.server.ts`).
+- **`.server.ts` vs `'use server'`, the decision.** Will the client call it?
+  Add `'use server'` and the file becomes an RPC action (browser import
+  rewritten to a typed stub). Is it server-only infra instead (a DB driver,
+  secrets, `node:*`)? Use NO directive, and NEVER import it into a
+  page/layout/component. Reach it from a `'use server'` action, `route.ts`, or
+  `middleware.ts`. A `.server.ts` WITHOUT the directive is a server-only utility
+  whose browser import throws at module load.
+- **Label every interactive control.** Give each control an accessible name, and
+  make clickable text a `<label for="control-id">` (or the control itself) so a
+  text click activates the control on BOTH the JS path and the no-JS
+  form-submit path. Use `aria-label` and `aria-pressed` on icon-only controls.
+  `assertNoA11yViolations(el)` in a browser test catches missing labels.
 - Server-only code (a DB driver like `pg`, `node:*`, anything that needs Node APIs)
   goes only in `.server.{js,ts}` files, `route.ts` handlers, or
   `middleware.ts`. Never in pages, layouts, or components. Wrap the access in
   a `.server.{js,ts}` file; the framework rewrites that import into an RPC
   stub for the browser. `lib/` holds both server-only infra
   (the DB in `db/*.server.ts`) and browser-safe utilities (`lib/utils/cn.ts` with
-  `cn`); follow the same rule per file.
+  `cn`); follow the same rule per file. A TYPE-ONLY `import type { Todo } from
+  '#db/schema.server.ts'` is the exception, fine in a page or component because
+  the stripper erases it before it reaches the browser.
 - Keep pages and layouts as pure carriers so their modules stay out of the
   network tab. A page/layout never hydrates; the framework drops its module
   from the browser as long as its only browser job is registering the
@@ -180,6 +242,12 @@ self-review loop.
   paint), NOT from `fetch` calls in `connectedCallback`. For write-paths, prefer `<form action=...>` plus
   server action over `fetch` plus click handler. The framework upgrades plain
   forms to partial-swap submissions automatically.
+- **Default to optimistic UI for feasible mutations.** Use `optimistic()` from
+  `@webjsdev/core` for create/toggle/like/reorder so the UI updates instantly
+  and rolls back on failure (no hand-written try-catch or temp-id bookkeeping).
+  Do NOT use it where it hurts: unpredictable or server-computed results,
+  side-effectful or OAuth/payment mutations, and destructive irreversible
+  actions (confirm-first instead).
 - **Client navigation is auto-magic.** Real `<a href>` and `<form action>`
   get partial-swap behavior with no opt-in. Because layouts persist across
   navigation, put shared chrome (sidenav, header) in `layout.ts` and

package/templates/.claude/hooks/check-server-imports.mjs

@@ -0,0 +1,86 @@
+// Node walker for check-server-imports.sh (#804). Reads the PreToolUse JSON
+// payload (arg or stdin), extracts the file being edited and its proposed
+// content, and warns when a browser-facing app module adds an import of a
+// server-only `.server.*` utility (no `'use server'`). WARN by default; a
+// clean edit prints nothing and exits 0.
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, resolve, join } from 'node:path';
+
+function readPayload() {
+  const arg = process.argv[2];
+  if (arg && arg.trim().startsWith('{')) return arg;
+  try { return readFileSync(0, 'utf8'); } catch { return ''; }
+}
+
+let data;
+try { data = JSON.parse(readPayload() || '{}'); } catch { process.exit(0); }
+const input = data.tool_input || {};
+const filePath = input.file_path || input.filePath || '';
+if (!filePath) process.exit(0);
+
+// Only browser-facing app modules matter. A `.server.*` file (the boundary) or a
+// route.ts / middleware.ts (never shipped) is allowed to import server code.
+const rel = filePath.replace(/\\/g, '/');
+const isAppModule = /\/(app|components|modules|lib)\/.*\.(ts|js|mts|mjs)$/.test('/' + rel) || /(^|\/)(app|components|modules|lib)\//.test(rel);
+if (!isAppModule) process.exit(0);
+if (/\.server\.(ts|js|mts|mjs)$/.test(rel)) process.exit(0);
+if (/(^|\/)(route|middleware)\.(ts|js|mts|mjs)$/.test(rel)) process.exit(0);
+
+// Proposed content: Write has `content`; Edit has `new_string`; else read disk.
+let content = input.content ?? input.new_string ?? '';
+if (!content && existsSync(filePath)) { try { content = readFileSync(filePath, 'utf8'); } catch { /* ignore */ } }
+if (!content) process.exit(0);
+
+// Find the app root (walks up for a package.json with a `#*` imports map or a db/ dir).
+function findAppRoot(start) {
+  let dir = dirname(resolve(start));
+  for (let i = 0; i < 8; i++) {
+    if (existsSync(join(dir, 'package.json')) && (existsSync(join(dir, 'app')) || existsSync(join(dir, 'db')))) return dir;
+    const up = dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return dirname(resolve(start));
+}
+const appRoot = findAppRoot(filePath);
+
+// Collect import specifiers, skipping `import type` (erased by the stripper).
+const specs = [];
+const re = /(?:^|\n)\s*import\s+(type\s+)?[^;'"]*?from\s*['"]([^'"]+)['"]/g;
+let m;
+while ((m = re.exec(content))) { if (!m[1]) specs.push(m[2]); }
+
+function resolveSpec(spec) {
+  if (spec.startsWith('#')) return join(appRoot, spec.slice(1).replace(/^\//, ''));
+  if (spec.startsWith('.')) return resolve(dirname(filePath), spec);
+  return null; // bare npm specifier
+}
+
+const offenders = [];
+for (const spec of specs) {
+  if (!/\.server\.(ts|js|mts|mjs)$/.test(spec)) continue;
+  const abs = resolveSpec(spec);
+  if (!abs || !existsSync(abs)) continue;
+  let src = '';
+  try { src = readFileSync(abs, 'utf8'); } catch { continue; }
+  const head = src.split('\n').slice(0, 5).join('\n');
+  const hasUseServer = /^\s*(['"])use server\1\s*;?\s*$/m.test(head);
+  if (!hasUseServer) offenders.push(spec);
+}
+
+if (offenders.length === 0) process.exit(0);
+
+const msg =
+  `A browser-facing module (${rel}) imports a server-only utility: ${offenders.join(', ')}. ` +
+  `A .server.{ts,js} file with NO 'use server' directive throws at load in the browser, ` +
+  `so this would crash the page (webjs check flags it as no-server-import-in-browser-module). ` +
+  `Fix: add 'use server' to make it an RPC action, or reach it from a 'use server' action / route.ts / ` +
+  `middleware.ts, or share only a type via 'import type'. See agent-docs/types-and-mutations.md.`;
+
+if (process.env.WEBJS_SERVER_IMPORT_GATE === 'block') {
+  process.stderr.write(`BLOCKED: ${msg}\n`);
+  process.exit(2);
+}
+// WARN: surface as additionalContext, allow the edit.
+process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: msg } }) + '\n');
+process.exit(0);

package/templates/.claude/hooks/check-server-imports.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+#
+# PreToolUse hook (scaffolded by `webjs create`): WARN, at write time, when an
+# Edit/Write to a browser-facing app module (a page / layout / component under
+# app/ or components/ or modules/, NOT a `.server.*` file) adds an import of a
+# server-only `.server.{ts,js}` utility (a `.server.*` file with NO `'use server'`
+# directive). In the browser that import resolves to a throw-at-load stub, so the
+# module crashes the moment it loads. This is the #804 first-pass iteration loop:
+# `webjs check`'s `no-server-import-in-browser-module` catches it AFTER the file
+# lands; this hook surfaces it BEFORE, so the agent never writes the wrong shape.
+#
+# WARN, not block (the convention-vs-check principle in this app's AGENTS.md):
+# `webjs check` is the authoritative gate, and a pre-edit static peek cannot see
+# the full elision verdict, so a hard block could false-positive on a display-only
+# page the framework would elide. So this emits a loud reminder and allows the
+# edit. Set WEBJS_SERVER_IMPORT_GATE=block to hard-block instead; set
+# WEBJS_NO_SERVER_IMPORT_GATE=1 to skip.
+#
+# A `'use server'` action import is fine (it becomes a working RPC stub), and a
+# `import type { ... } from './x.server.ts'` is fine (the stripper erases it), so
+# both are ignored.
+
+[ "$WEBJS_NO_SERVER_IMPORT_GATE" = "1" ] && exit 0
+
+payload="$(cat)"
+node "$(dirname "$0")/check-server-imports.mjs" "$payload"

package/templates/.claude/settings.json

@@ -10,6 +10,15 @@
           }
         ]
       },
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/check-server-imports.sh"
+          }
+        ]
+      },
       {
         "matcher": "Write|Edit|MultiEdit|NotebookEdit|Bash",
         "hooks": [

package/templates/.cursorrules

@@ -3,7 +3,7 @@
 You are working on a webjs app, an AI-first, no-build, web-components-first
 framework. Read AGENTS.md for the full API reference and CONVENTIONS.md for
 project-specific conventions before writing any code. When AGENTS.md doesn't
-cover what you need, the full hosted docs are at **https://docs.webjs.com**.
+cover what you need, the full hosted docs are at **https://docs.webjs.dev**.
 
 ## Persistence + scaffold rules (non-negotiable)
 
@@ -18,6 +18,41 @@ cover what you need, the full hosted docs are at **https://docs.webjs.com**.
   `app/page.ts`, the example `User` model, the example users module, etc.
   with the app the user actually asked for. Don't ship "Hello from
   <app-name>" as the deliverable.
+- **Study the gallery first, prune it second.** The full-stack and saas scaffolds ship
+  single-feature demos under `app/features/` plus one whole example app under
+  `app/examples/` (logic in `modules/`). It is your PRIMARY webjs reference:
+  read every demo end to end (code AND comments) to learn the idioms BEFORE you
+  write or delete anything. Only after internalising the patterns should you
+  prune, keeping and adapting what you need and deleting the rest (the
+  `app/features/<name>` or `app/examples/<name>` route AND its `modules/<name>`;
+  for the todo app, also the `todos` table). Never delete blindly up front. Each
+  route page has a `webjs-scaffold-placeholder` marker so `webjs check` fails
+  until you resolve it. Delete now-empty directories after pruning. The `api`
+  template ships a BACKEND-features showcase instead (endpoints under
+  `app/api/features/`: the `route()` adapter + validation, rate limiting,
+  streaming, file storage, WebSockets + broadcast, plus `env.ts` validation),
+  listed in the root `app/route.ts` index; prune it the same way.
+- **Prune what the app does not use.** Keep the infrastructure the app
+  USES and delete the rest (files AND folders). No persistence means
+  delete `db/`, `drizzle.config.ts`, and the `db:*` scripts. No UI kit
+  used means delete `components/ui/`, `components.json`, and
+  `lib/utils/cn.ts`. No PWA means delete `public/sw.js` and
+  `offline.html`. Always KEEP the durable knowledge (`AGENTS.md`,
+  `CONVENTIONS.md`, the rule files, the MCP), never prune it, so removing
+  example code never removes your context. Prune AFTER using the features
+  and examples as reference, never blindly up front. A no-op for the `api` template
+  (no UI kit, no PWA files).
+- **`app/` is routing-only.** Only routing files live in `app/` (page,
+  layout, route, middleware, metadata routes). CSS, helpers, and constants
+  do NOT: `globals.css` is at `styles/`, browser-safe helpers at
+  `lib/utils/`, feature logic in `modules/`.
+- **Use a unique design (UI apps).** When the app has a UI, give it a
+  design of your own (palette, layout, typography, chrome) that fits what
+  the user asked for. Do NOT mimic the scaffold's example look (its warm
+  colors, the 760px reading column, the example header/nav). The `api`
+  template has no UI, so this does not apply there. Keep the design tokens
+  and theme setup in `app/layout.ts`, those are infrastructure, and
+  restyle on top of them.
 - **Only three templates exist:** `webjs create <name>` (default
   full-stack), `--template api`, `--template saas`. The CLI rejects any
   other `--template` value. Pick:
@@ -110,13 +145,17 @@ self-review loop.
 - No build step: source files are served as ES modules
 - **Erasable TypeScript only.** The runtime strips types via `module.stripTypeScriptTypes` (Node's built-in, or `amaro` on Bun) (whitespace replacement, byte-exact position preservation, no sourcemap). The scaffold's tsconfig.json sets `erasableSyntaxOnly: true`, so the TS compiler rejects `enum`, `namespace` with values, constructor parameter properties, legacy decorators with `emitDecoratorMetadata`, and `import = require`. Use erasable equivalents: `const X = { ... } as const` plus a derived union type instead of `enum`; explicit fields plus constructor body assignments instead of parameter properties. If `erasableSyntaxOnly` is disabled and non-erasable syntax is used, the dev server fails at strip time and returns a 500 pointing at the `no-non-erasable-typescript` lint rule. webjs is buildless end-to-end and has no bundler fallback.
 - **Tailwind-first styling.** Tailwind utilities are the strong default for pages AND light-DOM components (the default DOM mode): layout, spacing, color (via `@theme` tokens), typography, borders, radius, shadows, interaction states. Light DOM does not scope, so utilities apply directly. The lit reflex to scope CSS (`static styles = css`) or write an inline `<style>` with semantic class names (`.hero`, `.card`) in a light-DOM component is wrong: the scoped block needs `static shadow = true`, and inline class names leak globally. When a utility bundle repeats, extract a `lib/utils/ui.ts` helper returning an `html` fragment, not a CSS class. Reserve raw CSS for the allowlist (design tokens / `@theme`, `@property` + `@keyframes`, `::-webkit-scrollbar`, `prefers-reduced-motion`, complex `color-mix()` / gradients); when unavoidable in a light-DOM component, prefix every class selector with the component tag.
+- **One theme, canonical tokens.** The app has a SINGLE theme, defined once in `app/layout.ts` using the standard `@webjsdev/ui` (shadcn-compatible) semantic tokens set to the brand palette. Use the canonical utility names everywhere, in the page chrome AND inside components: `bg-background`, `text-foreground`, `bg-card`, `bg-muted`, `text-muted-foreground`, `bg-primary`, `text-primary-foreground`, `bg-accent`, `text-accent-foreground`, `border-border`, `ring-ring`. These are exactly the tokens a component copied in by `webjs ui add <name>` reads, so a scaffolded page and a later-added ui component share one theme with no wiring. NEVER invent a parallel token vocabulary (`--fg`, `--bg`, `text-fg`, `bg-elev`, a separate `--brand`): it collides with the ui tokens (the accent once flipped to neutral on navigation for exactly this reason) and diverges from the shadcn conventions the kit and AI agents expect. Reach for opacity modifiers (`bg-primary/10`, `hover:bg-primary/90`) before adding a token; add one the canonical way (a `--x` var plus a `--color-x: var(--x)` line in `@theme inline`).
 - Shadow-DOM components opt in with `static shadow = true` and use `static styles = css` for scoped CSS, not inline styles. That is the right home for scoped CSS.
 - One function per server action file (*.server.ts)
+- **`.server.ts` vs `'use server'`, the decision.** Will the client call it? Add `'use server'` and the file becomes an RPC action (browser import rewritten to a typed stub). Is it server-only infra instead (a DB driver, secrets, node:*)? Use NO directive, and NEVER import it into a page/layout/component. Reach it from a `'use server'` action, `route.ts`, or `middleware.ts`. A `.server.ts` WITHOUT the directive is a server-only utility whose browser import throws at module load.
+- **Label every interactive control.** Give each control an accessible name, and make clickable text a `<label for="control-id">` (or the control itself) so a text click activates the control on BOTH the JS path and the no-JS form-submit path. Use `aria-label` and `aria-pressed` on icon-only controls. `assertNoA11yViolations(el)` in a browser test catches missing labels.
 - Components must call customElements.define('tag', Class)
 - **Never extend raw HTMLElement directly for app components.** Always subclass `WebComponent` (or the factory form `WebComponent({...})`) to hook into SSR, lifecycle, elision, and the reactive property system. Extend raw HTMLElement only for rare native-API edge cases (like form-associated `ElementInternals` or customized built-in elements), and add a `webjs-allow-htmlelement: <reason>` comment to acknowledge the exception.
-- Server-only code (the DB driver `pg`, node:*, anything that needs Node APIs) goes only in .server.{js,ts} files, route.ts handlers, or middleware.ts. Never in pages, layouts, or components. Wrap the access in a .server.{js,ts} file; the framework rewrites that import into an RPC stub for the browser. The DB lives in db/*.server.ts (db/connection.server.ts); lib/ holds other server-only infra and browser-safe utilities (lib/utils/cn.ts with cn); follow the same rule per file: if a lib/ file needs Node APIs, only import it from server-only files.
+- Server-only code (the DB driver `pg`, node:*, anything that needs Node APIs) goes only in .server.{js,ts} files, route.ts handlers, or middleware.ts. Never in pages, layouts, or components. Wrap the access in a .server.{js,ts} file; the framework rewrites that import into an RPC stub for the browser. The DB lives in db/*.server.ts (db/connection.server.ts); lib/ holds other server-only infra and browser-safe utilities (lib/utils/cn.ts with cn); follow the same rule per file: if a lib/ file needs Node APIs, only import it from server-only files. A TYPE-ONLY `import type { Todo } from '#db/schema.server.ts'` is the exception, fine in a page or component because the stripper erases it before it reaches the browser.
 - Directives: webjs exports the lit directives with no clean native equivalent (`repeat`, `unsafeHTML`, `live`, `keyed`, `guard`, `cache`, `until`, `ref` / `createRef`, `templateContent`, `asyncAppend` / `asyncReplace`, `watch`). Lit's `classMap` / `styleMap` / `ifDefined` / `when` / `choose` are NOT exported. For those, use plain template-literal expressions (`class=${cond ? 'a' : 'b'}`, `${cond ? a : b}`) and lifecycle hooks (`this.query('#el')` in `firstUpdated`) instead.
 - **Progressive enhancement is the default.** Pages AND every web component are SSR'd to real HTML. Write components so the first paint is the right content. Read SSR-meaningful defaults in `constructor()`. `connectedCallback` is never called on the server, so anything there only runs after hydration. Initial data for components comes from the page function (server-side fetch plus pass as attribute/property) OR from an `async render()` in the component itself (`const u = await getUser(this.uid)`, which SSR awaits so the data is in the first paint), NOT from `fetch` calls in `connectedCallback`. Prefer the co-located `async render()` over prop-drilling; `renderFallback()` is the optional re-fetch loading state (never first paint), and a `Task` is for genuinely client-only data. For write-paths, prefer `<form action=...>` plus server action over `fetch` plus click handler. The framework upgrades plain forms to partial-swap submissions automatically.
+- **Default to optimistic UI for feasible mutations.** Use `optimistic()` from `@webjsdev/core` for create/toggle/like/reorder so the UI updates instantly and rolls back on failure (no hand-written try-catch or temp-id bookkeeping). Do NOT use it where it hurts: unpredictable or server-computed results, side-effectful or OAuth/payment mutations, and destructive irreversible actions (confirm-first instead).
 - **Client navigation is auto-magic.** Real `<a href>` and `<form action>` get partial-swap behavior with no opt-in. Because layouts persist across navigation, put shared chrome (sidenav, header) in `layout.ts` and page-specific content in `page.ts`. For validation errors, return 4xx HTML from a `route.ts` POST handler; the router renders it in place preserving the user's input. For non-layout swap regions, wrap in `<webjs-frame id="...">`. See "Client navigation patterns" in AGENTS.md.
 - **Keep pages and layouts as pure carriers** so their modules stay out of the network tab. A page/layout never hydrates; the framework drops its module from the browser as long as its only browser job is registering the components it imports. It starts shipping its own module (invisible in tests, an elision verdict) the moment its closure does any OTHER client work. Don't give a page/layout module-scope client work (a top-level call, a window/document/customElements access, a bare side-effect import, or a @webjsdev/core/client-router import: routing is automatic) or import a client-global-touching non-component util into it. Put client behaviour in a component, server-only code in .server.{js,ts}. Self-check: page.ts/layout.ts should not appear in the browser's network tab.
 - See AGENTS.md for the complete directive decision guide

package/templates/.github/copilot-instructions.md

@@ -3,7 +3,7 @@
 You are working on a webjs app, an AI-first, no-build, web-components-first
 framework. Read AGENTS.md for the full API reference and CONVENTIONS.md for
 project-specific conventions. When AGENTS.md doesn't cover what you need,
-the full hosted docs are at **https://docs.webjs.com**.
+the full hosted docs are at **https://docs.webjs.dev**.
 
 ## Persistence + scaffold rules (non-negotiable)
 
@@ -18,6 +18,41 @@ the full hosted docs are at **https://docs.webjs.com**.
   `app/page.ts`, the example `User` model, the example users module, etc.
   with the app the user actually asked for. Don't ship "Hello from
   <app-name>" as the deliverable.
+- **Study the gallery first, prune it second.** The full-stack and saas scaffolds ship
+  single-feature demos under `app/features/` plus one whole example app under
+  `app/examples/` (logic in `modules/`). It is your PRIMARY webjs reference:
+  read every demo end to end (code AND comments) to learn the idioms BEFORE you
+  write or delete anything. Only after internalising the patterns should you
+  prune, keeping and adapting what you need and deleting the rest (the
+  `app/features/<name>` or `app/examples/<name>` route AND its `modules/<name>`;
+  for the todo app, also the `todos` table). Never delete blindly up front. Each
+  route page has a `webjs-scaffold-placeholder` marker so `webjs check` fails
+  until you resolve it. Delete now-empty directories after pruning. The `api`
+  template ships a BACKEND-features showcase instead (endpoints under
+  `app/api/features/`: the `route()` adapter + validation, rate limiting,
+  streaming, file storage, WebSockets + broadcast, plus `env.ts` validation),
+  listed in the root `app/route.ts` index; prune it the same way.
+- **Prune what the app does not use.** Keep the infrastructure the app
+  USES and delete the rest (files AND folders). No persistence means
+  delete `db/`, `drizzle.config.ts`, and the `db:*` scripts. No UI kit
+  used means delete `components/ui/`, `components.json`, and
+  `lib/utils/cn.ts`. No PWA means delete `public/sw.js` and
+  `offline.html`. Always KEEP the durable knowledge (`AGENTS.md`,
+  `CONVENTIONS.md`, the rule files, the MCP), never prune it, so removing
+  example code never removes your context. Prune AFTER using the features
+  and examples as reference, never blindly up front. A no-op for the `api` template
+  (no UI kit, no PWA files).
+- **`app/` is routing-only.** Only routing files live in `app/` (page,
+  layout, route, middleware, metadata routes). CSS, helpers, and constants
+  do NOT: `globals.css` is at `styles/`, browser-safe helpers at
+  `lib/utils/`, feature logic in `modules/`.
+- **Use a unique design (UI apps).** When the app has a UI, give it a
+  design of your own (palette, layout, typography, chrome) that fits what
+  the user asked for. Do NOT mimic the scaffold's example look (its warm
+  colors, the 760px reading column, the example header/nav). The `api`
+  template has no UI, so this does not apply there. Keep the design tokens
+  and theme setup in `app/layout.ts`, those are infrastructure, and
+  restyle on top of them.
 - **Only three templates exist:** `webjs create <name>` (default
   full-stack), `--template api`, `--template saas`. The CLI rejects any
   other `--template` value. Pick:
@@ -107,10 +142,14 @@ each change must include.
 - **Erasable TypeScript only.** The runtime strips types via `module.stripTypeScriptTypes` (Node's built-in, or `amaro` on Bun) (whitespace replacement, byte-exact position preservation, no sourcemap). The scaffold's tsconfig.json sets `erasableSyntaxOnly: true`, so the TS compiler rejects `enum`, `namespace` with values, constructor parameter properties, legacy decorators with `emitDecoratorMetadata`, and `import = require`. Use erasable equivalents: `const X = { ... } as const` plus a derived union type instead of `enum`; explicit fields plus constructor body assignments instead of parameter properties. If `erasableSyntaxOnly` is disabled and non-erasable syntax is used, the dev server fails at strip time and returns a 500 pointing at the `no-non-erasable-typescript` lint rule. webjs is buildless end-to-end and has no bundler fallback.
 - Tagged template: html`<div>${value}</div>` with css`...` for styles.
 - **Tailwind-first styling.** Tailwind utilities are the strong default for pages AND light-DOM components (the default DOM mode): layout, spacing, color (via `@theme` tokens), typography, borders, radius, shadows, interaction states. Light DOM does not scope, so utilities apply directly. The lit reflex to scope CSS (`static styles = css\`...\``) or write an inline `<style>` with semantic class names (`.hero`, `.card`) in a light-DOM component is wrong: the scoped block needs `static shadow = true`, and inline class names leak globally. When a utility bundle repeats, extract a `lib/utils/ui.ts` helper returning an `html` fragment, not a CSS class. Reserve raw CSS for the allowlist (design tokens / `@theme`, `@property` + `@keyframes`, `::-webkit-scrollbar`, `prefers-reduced-motion`, complex `color-mix()` / gradients); when unavoidable in a light-DOM component, prefix every class selector with the component tag. Shadow-DOM components (`static shadow = true`) legitimately author `static styles = css\`...\`` for scoped CSS; don't use inline `style="..."` there.
+- **One theme, canonical tokens.** The app has a SINGLE theme, defined once in `app/layout.ts` using the standard `@webjsdev/ui` (shadcn-compatible) semantic tokens set to the brand palette. Use the canonical utility names everywhere, in the page chrome AND inside components: `bg-background`, `text-foreground`, `bg-card`, `bg-muted`, `text-muted-foreground`, `bg-primary`, `text-primary-foreground`, `bg-accent`, `text-accent-foreground`, `border-border`, `ring-ring`. These are exactly the tokens a component copied in by `webjs ui add <name>` reads, so a scaffolded page and a later-added ui component share one theme with no wiring. NEVER invent a parallel token vocabulary (`--fg`, `--bg`, `text-fg`, `bg-elev`, a separate `--brand`): it collides with the ui tokens (the accent once flipped to neutral on navigation for exactly this reason) and diverges from the shadcn conventions the kit and AI agents expect. Reach for opacity modifiers (`bg-primary/10`, `hover:bg-primary/90`) before adding a token; add one the canonical way (a `--x` var plus a `--color-x: var(--x)` line in `@theme inline`).
 - Components: extend the `WebComponent({ ... })` factory to declare reactive properties (e.g. `extends WebComponent({ count: Number })`; per-prop options via `prop(Number, { reflect: true })`), add `static styles` for shadow-DOM components, call `Class.register('tag-name')` at the bottom of the file. The tag name is the argument to `.register()`, not a static field. A hand-written `static properties` throws at construction (`no-static-properties`); set defaults in the constructor, never a class-field initializer (`reactive-props-no-class-field`). Declare an array-typed prop with the `Array` constructor, not `Object` (`items: prop<Tag[]>(Array)`), flagged by `array-prop-uses-array-type`. **Never extend raw HTMLElement directly for app components.** Always subclass `WebComponent` (or the factory form `WebComponent({...})`) to hook into SSR, lifecycle, elision, and the reactive property system. Extend raw HTMLElement only for rare native-API edge cases (like form-associated `ElementInternals` or customized built-in elements), and add a `webjs-allow-htmlelement: <reason>` comment to acknowledge the exception.
 - Async data in a component: prefer an `async render()` (`const u = await getUser(this.uid)`), which SSR awaits so the data is in the first paint, over prop-drilling from the page or fetching in `connectedCallback`. `renderFallback()` is the optional re-fetch loading state (never first paint); error isolation is automatic (`renderError()` customizes it); a `Task` is for genuinely client-only data.
+- **Default to optimistic UI for feasible mutations.** Use `optimistic()` from `@webjsdev/core` for create/toggle/like/reorder so the UI updates instantly and rolls back on failure (no hand-written try-catch or temp-id bookkeeping). Do NOT use it where it hurts: unpredictable or server-computed results, side-effectful or OAuth/payment mutations, and destructive irreversible actions (confirm-first instead).
 - Server actions: *.server.ts files with one exported async function each.
-- Server-only code (a DB driver like pg, node:*, anything needing Node APIs) goes only in .server.{js,ts} files, route.ts handlers, or middleware.ts. Never in pages, layouts, or components. Wrap in a .server.{js,ts} file; the framework rewrites that import to an RPC stub for the browser. The DB lives in db/*.server.ts; lib/ holds other server-only infra and browser-safe utilities (lib/utils/cn.ts with cn); apply the same rule per file.
+- **`.server.ts` vs `'use server'`, the decision.** Will the client call it? Add `'use server'` and the file becomes an RPC action (browser import rewritten to a typed stub). Is it server-only infra instead (a DB driver, secrets, node:*)? Use NO directive, and NEVER import it into a page/layout/component. Reach it from a `'use server'` action, route.ts, or middleware.ts. A `.server.ts` WITHOUT the directive is a server-only utility whose browser import throws at module load.
+- **Label every interactive control.** Give each control an accessible name, and make clickable text a `<label for="control-id">` (or the control itself) so a text click activates the control on BOTH the JS path and the no-JS form-submit path. Use `aria-label` and `aria-pressed` on icon-only controls. `assertNoA11yViolations(el)` in a browser test catches missing labels.
+- Server-only code (a DB driver like pg, node:*, anything needing Node APIs) goes only in .server.{js,ts} files, route.ts handlers, or middleware.ts. Never in pages, layouts, or components. Wrap in a .server.{js,ts} file; the framework rewrites that import to an RPC stub for the browser. The DB lives in db/*.server.ts; lib/ holds other server-only infra and browser-safe utilities (lib/utils/cn.ts with cn); apply the same rule per file. A TYPE-ONLY `import type { Todo } from '#db/schema.server.ts'` is the exception, fine in a page or component because the stripper erases it before it reaches the browser.
 - Directives: webjs exports the lit directives with no clean native equivalent (`repeat`, `unsafeHTML`, `live`, `keyed`, `guard`, `cache`, `until`, `ref` / `createRef`, `templateContent`, `asyncAppend` / `asyncReplace`, `watch`). Lit's `classMap` / `styleMap` / `ifDefined` / `when` / `choose` are NOT exported; use plain template-literal expressions instead.
 - Context: import { createContext, ContextProvider, ContextConsumer } from '@webjsdev/core/context'
 - Task: import { Task, TaskStatus } from '@webjsdev/core/task'