@webjsdev/cli 0.10.8 → 0.10.9

package/bin/webjs.js

@@ -41,7 +41,8 @@ const USAGE = `webjs commands:
   webjs dev   [--port 8080]                       Start dev server with live reload
   webjs start [--port 8080]                       Start production server (serves source directly, no build step)
   webjs test  [--server|--browser]                 Run server + browser tests
-  webjs check                                     Run correctness checks on the app
+  webjs check [--json]                            Run correctness checks on the app (--json emits structured violations)
+  webjs mcp                                       Start the read-only MCP server (routes / actions / components / check)
   webjs doctor                                    Verify project health (Node, tsconfig, env, vendor pins, @webjsdev versions, git hook)
   webjs types                                     Generate .webjs/routes.d.ts (typed Route union + per-route params)
   webjs typecheck [tsc args...]                   Type-check the app with the project's tsc --noEmit (non-zero on errors)
@@ -266,6 +267,18 @@ async function main() {
 
       const violations = await checkConventions(process.cwd());
 
+      // --json emits the raw structured violations + a summary count as JSON,
+      // so an agent running `webjs check` in a loop consumes structured data
+      // instead of regex-scraping stdout. The shared projector keeps this byte-
+      // identical to the MCP `check` tool. The non-zero exit on violations is
+      // preserved (an agent gates on the exit code AND parses the report).
+      if (rest.includes('--json')) {
+        const { projectCheck } = await import('../lib/check-json.js');
+        console.log(JSON.stringify(projectCheck(violations)));
+        if (violations.length > 0) process.exit(1);
+        break;
+      }
+
       if (violations.length === 0) {
         console.log('webjs check: all checks pass ✓');
       } else {
@@ -631,6 +644,29 @@ Full docs: https://docs.webjs.com`);
         `  --from PROVIDER     CDN to resolve through. One of: ${[...SUPPORTED_PROVIDERS].join(', ')}. Default: jspm.`);
       process.exit(1);
     }
+    case 'mcp': {
+      // Read-only MCP server (#262) over stdio. STDOUT is the JSON-RPC channel,
+      // so nothing here may write to stdout: the data functions are read-only
+      // and `runMcpServer` routes all diagnostics to stderr. The CLI version is
+      // advertised in the initialize handshake's serverInfo.
+      const { readFileSync } = await import('node:fs');
+      let version = '0.0.0';
+      try {
+        const pkg = JSON.parse(
+          readFileSync(join(__dirname, '..', 'package.json'), 'utf8'),
+        );
+        version = pkg.version || version;
+      } catch {}
+      const { runMcpServer } = await import('../lib/mcp.js');
+      await runMcpServer({
+        stdin: process.stdin,
+        stdout: process.stdout,
+        stderr: process.stderr,
+        cwd: process.cwd(),
+        version,
+      });
+      break;
+    }
     case 'help':
     case undefined:
       console.log(USAGE);

package/lib/check-json.js

@@ -0,0 +1,47 @@
+/**
+ * Shared JSON projector for `webjs check` violations (#262).
+ *
+ * `webjs check --json` and the `webjs mcp` server's `check` tool BOTH return
+ * the identical shape, so the projection lives here once. The input is the raw
+ * `Violation[]` from `checkConventions(appDir)` (each `{ rule, file, message,
+ * fix }`); the output adds a `summary` count plus a per-rule breakdown so an
+ * agent consuming the structured output never has to regex-scrape stdout.
+ *
+ * Pure and side-effect-free: it neither reads files nor prints. The caller owns
+ * running `checkConventions` and (for the CLI) the non-zero exit when there are
+ * violations.
+ *
+ * @module check-json
+ */
+
+/**
+ * @typedef {{ rule: string, file: string, message: string, fix: string }} Violation
+ */
+
+/**
+ * @typedef {{
+ *   violations: Violation[],
+ *   summary: { count: number, byRule: Record<string, number> },
+ * }} CheckReport
+ */
+
+/**
+ * Project a raw `Violation[]` into the structured `{ violations, summary }`
+ * report shared by `check --json` and the MCP `check` tool. `violations` is
+ * passed through verbatim (the `{ rule, file, message, fix }` shape), and
+ * `summary.byRule` tallies how many violations each rule produced.
+ *
+ * @param {Violation[]} violations
+ * @returns {CheckReport}
+ */
+export function projectCheck(violations) {
+  /** @type {Record<string, number>} */
+  const byRule = {};
+  for (const v of violations) {
+    byRule[v.rule] = (byRule[v.rule] || 0) + 1;
+  }
+  return {
+    violations,
+    summary: { count: violations.length, byRule },
+  };
+}

package/lib/mcp.js

@@ -0,0 +1,408 @@
+/**
+ * `webjs mcp`: a minimal, READ-ONLY Model Context Protocol server (#262).
+ *
+ * Exposes the live introspection surface an AI agent needs while editing a
+ * webjs app (the route table, registered server actions with their RPC
+ * endpoints, registered custom-element tags, and the structured `webjs check`
+ * violations) over MCP's stdio transport. Every tool REUSES an existing
+ * `@webjsdev/server` data function and MUTATES NOTHING. The prior art is
+ * Next.js's `next-devtools-mcp` (get_routes / get_server_action_by_id /
+ * get_errors); this is deliberately tiny.
+ *
+ * Transport: MCP stdio is newline-delimited JSON-RPC 2.0. One JSON object per
+ * line arrives on stdin; exactly one JSON response line per request is written
+ * to stdout. STDOUT IS THE PROTOCOL CHANNEL, so this module writes ONLY
+ * JSON-RPC frames there and routes every diagnostic to stderr. A malformed
+ * input line is answered with a JSON-RPC parse error and never crashes the
+ * loop. Hand-rolled with zero new dependency (webjs is buildless +
+ * minimal-deps).
+ *
+ * @module mcp
+ */
+
+import { createInterface } from 'node:readline';
+import { relative } from 'node:path';
+
+const PROTOCOL_VERSION = '2024-11-05';
+
+/**
+ * The four read-only tools. Each takes an optional `{ appDir }` (default the
+ * server's cwd) and projects an EXISTING `@webjsdev/server` function's output
+ * into an agent-friendly shape. Descriptions are crisp so a model picks the
+ * right tool without reading source.
+ */
+const TOOL_DEFS = [
+  {
+    name: 'list_routes',
+    description:
+      'List the app route table: SSR pages (path, file, dynamic flag, param names) and route.{js,ts} API handlers (path, file, HTTP methods). Read-only.',
+  },
+  {
+    name: 'list_actions',
+    description:
+      'List registered server actions (the .server.{js,ts} files with "use server"): file, exported function name, and the /__webjs/action/<hash>/<fn> RPC endpoint. Read-only.',
+  },
+  {
+    name: 'list_components',
+    description:
+      'List registered custom-element tags: tag name, defining file, and class name. Read-only.',
+  },
+  {
+    name: 'check',
+    description:
+      'Run webjs check (correctness rules) and return the structured violations { rule, file, message, fix } plus a summary count and per-rule breakdown. Read-only.',
+  },
+];
+
+/** The shared input schema: every tool takes an optional appDir override. */
+const TOOL_INPUT_SCHEMA = {
+  type: 'object',
+  properties: {
+    appDir: {
+      type: 'string',
+      description: 'App directory to introspect. Defaults to the server cwd.',
+    },
+  },
+  required: [],
+};
+
+/**
+ * Lexically extract the names exported from a module source. Recognises the
+ * common forms a server-action / route file uses without LOADING the module
+ * (loading would run its top-level side effects: Prisma init, DB connects).
+ *
+ *   export async function foo() {}   export function foo() {}
+ *   export const foo = ...           export let/var foo = ...
+ *   export default ...               (recorded as 'default')
+ *   export { a, b as c }             (the EXPORTED name, so `c`)
+ *
+ * @param {string} src
+ * @returns {string[]} unique export names, in source order
+ */
+export function extractExportNames(src) {
+  /** @type {string[]} */
+  const names = [];
+  const add = (n) => { if (n && !names.includes(n)) names.push(n); };
+
+  // export [async] function NAME / export const|let|var NAME / export class NAME
+  const declRe =
+    /\bexport\s+(?:async\s+)?(?:function\*?|const|let|var|class)\s+([A-Za-z_$][\w$]*)/g;
+  let m;
+  while ((m = declRe.exec(src)) !== null) add(m[1]);
+
+  // export default ...
+  if (/\bexport\s+default\b/.test(src)) add('default');
+
+  // export { a, b as c, default as d }
+  const namedRe = /\bexport\s*\{([^}]*)\}/g;
+  while ((m = namedRe.exec(src)) !== null) {
+    for (const part of m[1].split(',')) {
+      const seg = part.trim();
+      if (!seg) continue;
+      // `local as exported` -> the exported name is what callers import.
+      const asMatch = /\bas\s+([A-Za-z_$][\w$]*)\s*$/.exec(seg);
+      if (asMatch) add(asMatch[1]);
+      else {
+        const idMatch = /^([A-Za-z_$][\w$]*)$/.exec(seg);
+        if (idMatch) add(idMatch[1]);
+      }
+    }
+  }
+  return names;
+}
+
+/**
+ * Lexically extract the HTTP method exports of a route.{js,ts} file. The webjs
+ * API router (`api.js`) dispatches the five standard verbs, plus `WS` for a
+ * WebSocket upgrade. We report exactly those that are exported, NOT `HEAD` /
+ * `OPTIONS` (the router does not dispatch a named handler for them, so listing
+ * them would imply a route the framework ignores). Read-only: no module load.
+ *
+ * @param {string} src
+ * @returns {string[]}
+ */
+export function extractRouteMethods(src) {
+  const METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'WS'];
+  const exported = new Set(extractExportNames(src));
+  return METHODS.filter((m) => exported.has(m));
+}
+
+/**
+ * The literal URL path for a page/api directory: `blog/[slug]` -> `/blog/[slug]`,
+ * the root `.` -> `/`. Route groups `(group)` and `_private` segments drop, the
+ * same normalization `buildRouteTable` uses for matching.
+ *
+ * @param {string} routeDir  POSIX-style, `.` for the app root.
+ * @returns {string}
+ */
+function routePathFromDir(routeDir) {
+  if (!routeDir || routeDir === '.') return '/';
+  const segs = routeDir
+    .split('/')
+    .filter((s) => !(s.startsWith('(') && s.endsWith(')')) && !s.startsWith('_'));
+  return segs.length ? '/' + segs.join('/') : '/';
+}
+
+/**
+ * The tool runners. Each is async, takes `(appDir)`, and returns a plain
+ * JSON-serialisable projection of an existing server data function. All are
+ * read-only.
+ *
+ * @param {{ buildRouteTable: Function, buildActionIndex: Function, hashFile: Function, scanComponents: Function, checkConventions: Function, projectCheck: Function, readFile: Function }} deps
+ */
+export function makeToolRunners(deps) {
+  const {
+    buildRouteTable,
+    buildActionIndex,
+    hashFile,
+    scanComponents,
+    checkConventions,
+    projectCheck,
+    readFile,
+  } = deps;
+
+  return {
+    async list_routes(appDir) {
+      const table = await buildRouteTable(appDir);
+      const pages = await Promise.all(
+        table.pages.map(async (r) => {
+          /** @type {{ path: string, file: string, dynamic?: boolean, params?: string[] }} */
+          const out = {
+            path: routePathFromDir(r.routeDir),
+            file: relative(appDir, r.file),
+          };
+          if (r.paramNames && r.paramNames.length) {
+            out.dynamic = true;
+            out.params = r.paramNames;
+          }
+          return out;
+        }),
+      );
+      const apis = await Promise.all(
+        table.apis.map(async (r) => {
+          let methods = [];
+          try {
+            methods = extractRouteMethods(await readFile(r.file, 'utf8'));
+          } catch {}
+          return {
+            path: routePathFromDir(r.routeDir),
+            file: relative(appDir, r.file),
+            methods,
+          };
+        }),
+      );
+      return { pages, apis };
+    },
+
+    async list_actions(appDir) {
+      // `skipExposeLoad` builds the file -> hash maps WITHOUT importing any
+      // `expose()` module, so this stays truly read-only (no Prisma/DB init, and
+      // no stray stdout from a loaded module corrupting the JSON-RPC channel).
+      // The RPC hash is over the file path only, so no module load is needed.
+      const idx = await buildActionIndex(appDir, false, { skipExposeLoad: true });
+      /** @type {Array<{ file: string, fn: string, endpoint: string }>} */
+      const actions = [];
+      for (const [file, hash] of idx.fileToHash) {
+        let names = [];
+        try {
+          names = extractExportNames(await readFile(file, 'utf8'));
+        } catch {}
+        for (const fn of names) {
+          actions.push({
+            file: relative(appDir, file),
+            fn,
+            endpoint: `/__webjs/action/${hash}/${fn}`,
+          });
+        }
+      }
+      // Stable order for deterministic output.
+      actions.sort((a, b) =>
+        a.file === b.file ? a.fn.localeCompare(b.fn) : a.file.localeCompare(b.file),
+      );
+      return actions;
+    },
+
+    async list_components(appDir) {
+      const comps = await scanComponents(appDir);
+      return comps
+        .map((c) => ({
+          tag: c.tag,
+          file: relative(appDir, c.file),
+          className: c.className,
+        }))
+        .sort((a, b) => a.tag.localeCompare(b.tag));
+    },
+
+    async check(appDir) {
+      const violations = await checkConventions(appDir);
+      return projectCheck(violations);
+    },
+  };
+}
+
+/**
+ * A JSON-RPC 2.0 result frame.
+ * @param {string|number|null} id
+ * @param {any} result
+ */
+function rpcResult(id, result) {
+  return { jsonrpc: '2.0', id, result };
+}
+
+/**
+ * A JSON-RPC 2.0 error frame.
+ * @param {string|number|null} id
+ * @param {number} code
+ * @param {string} message
+ */
+function rpcError(id, code, message) {
+  return { jsonrpc: '2.0', id, error: { code, message } };
+}
+
+/**
+ * Run the read-only webjs MCP server over the given streams. Reads
+ * newline-delimited JSON-RPC from `stdin`, writes one response line per request
+ * to `stdout`, and logs diagnostics to `stderr` ONLY (stdout is the protocol
+ * channel). Resolves when stdin ends (clean shutdown).
+ *
+ * Injectable streams + `cwd` keep it testable in-process with PassThrough
+ * streams; the bin passes the real `process.std*` + `process.cwd()`.
+ *
+ * @param {{
+ *   stdin: NodeJS.ReadableStream,
+ *   stdout: NodeJS.WritableStream,
+ *   stderr: NodeJS.WritableStream,
+ *   cwd: string,
+ *   version?: string,
+ *   deps?: object,
+ * }} opts
+ * @returns {Promise<void>}
+ */
+export async function runMcpServer(opts) {
+  const { stdin, stdout, stderr, cwd } = opts;
+  const version = opts.version || '0.0.0';
+
+  // Resolve the data functions from @webjsdev/server (reading them is
+  // read-only). Injectable for tests so they need not boot the real server.
+  let deps = opts.deps;
+  if (!deps) {
+    const server = await import('@webjsdev/server');
+    const check = await import('@webjsdev/server/check');
+    const { readFile } = await import('node:fs/promises');
+    const { projectCheck } = await import('./check-json.js');
+    deps = {
+      buildRouteTable: server.buildRouteTable,
+      buildActionIndex: server.buildActionIndex,
+      hashFile: server.hashFile,
+      scanComponents: server.scanComponents,
+      checkConventions: check.checkConventions,
+      projectCheck,
+      readFile,
+    };
+  }
+  const runners = makeToolRunners(deps);
+
+  /** Write one JSON-RPC frame as a single line to stdout. */
+  const send = (frame) => {
+    stdout.write(JSON.stringify(frame) + '\n');
+  };
+  /** Diagnostics go to stderr only, never stdout. */
+  const logErr = (msg) => {
+    try { stderr.write(`[webjs mcp] ${msg}\n`); } catch {}
+  };
+
+  /**
+   * Dispatch one parsed JSON-RPC message. Returns a frame to send, or null
+   * for a notification (no `id`) which gets no response.
+   */
+  const dispatch = async (msg) => {
+    const id = msg && Object.prototype.hasOwnProperty.call(msg, 'id') ? msg.id : null;
+    const isNotification = id === null || id === undefined;
+    const method = msg && msg.method;
+
+    if (method === 'initialize') {
+      return rpcResult(id, {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: { tools: {} },
+        serverInfo: { name: 'webjs', version },
+      });
+    }
+
+    // `notifications/initialized` (and any other notification) gets no reply.
+    if (isNotification) return null;
+
+    if (method === 'tools/list') {
+      return rpcResult(id, {
+        tools: TOOL_DEFS.map((t) => ({
+          name: t.name,
+          description: t.description,
+          inputSchema: TOOL_INPUT_SCHEMA,
+        })),
+      });
+    }
+
+    if (method === 'tools/call') {
+      const params = (msg && msg.params) || {};
+      const name = params.name;
+      const args = params.arguments || {};
+      const runner = runners[name];
+      if (!runner) {
+        return rpcError(id, -32602, `Unknown tool: ${String(name)}`);
+      }
+      const appDir = typeof args.appDir === 'string' && args.appDir ? args.appDir : cwd;
+      try {
+        const result = await runner(appDir);
+        return rpcResult(id, {
+          content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        });
+      } catch (e) {
+        // A tool failure is an MCP tool-result error (isError), not a transport
+        // error, so the agent sees the message in the content channel.
+        logErr(`tool ${name} failed: ${e && e.message ? e.message : e}`);
+        return rpcResult(id, {
+          isError: true,
+          content: [
+            { type: 'text', text: `Error running ${name}: ${e && e.message ? e.message : String(e)}` },
+          ],
+        });
+      }
+    }
+
+    return rpcError(id, -32601, `Method not found: ${String(method)}`);
+  };
+
+  const rl = createInterface({ input: stdin, crlfDelay: Infinity });
+
+  await new Promise((resolveRun) => {
+    // Serialise line handling so responses preserve request order even though
+    // dispatch is async.
+    let chain = Promise.resolve();
+    rl.on('line', (line) => {
+      const trimmed = line.trim();
+      if (!trimmed) return;
+      chain = chain.then(async () => {
+        let msg;
+        try {
+          msg = JSON.parse(trimmed);
+        } catch {
+          // Malformed line: a JSON-RPC parse error, never a crash.
+          send(rpcError(null, -32700, 'Parse error'));
+          return;
+        }
+        try {
+          const frame = await dispatch(msg);
+          if (frame) send(frame);
+        } catch (e) {
+          logErr(`dispatch error: ${e && e.message ? e.message : e}`);
+          const id =
+            msg && Object.prototype.hasOwnProperty.call(msg, 'id') ? msg.id : null;
+          send(rpcError(id, -32603, 'Internal error'));
+        }
+      });
+    });
+    rl.on('close', () => {
+      // Drain the in-flight chain, then resolve (clean shutdown on stdin end).
+      chain.then(() => resolveRun()).catch(() => resolveRun());
+    });
+  });
+}

package/package.json

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

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

@@ -114,6 +114,20 @@ self-review loop.
   `static styles = css\`...\``) or third-party-embed isolation. `<slot>`
   projection works identically in both modes (named slots, fallback content,
   `assignedNodes` / `slotchange`, first-wins resolution).
+- **Tailwind-first styling.** Tailwind utilities are the strong default for
+  pages AND light-DOM components: 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 legitimately use
+  `static styles = css\`...\`` for scoped CSS.
 - Custom-element tag names are passed to `.register('tag-name')`. They are NOT
   a static field on the class.
 - One function per server action file (`*.server.ts`).

package/templates/.claude.json

@@ -4,6 +4,11 @@
       "type": "stdio",
       "command": "npx",
       "args": ["@playwright/mcp@latest"]
+    },
+    "webjs": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@webjsdev/cli", "mcp"]
     }
   }
 }

package/templates/.cursorrules

@@ -103,7 +103,8 @@ self-review loop.
 
 - No build step: source files are served as ES modules
 - **Erasable TypeScript only.** Node 24+ strips types via `module.stripTypeScriptTypes` (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.
-- Web components with shadow DOM: use `static styles = css` not inline 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 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)
 - Components must call customElements.define('tag', Class)
 - Server-only code (@prisma/client, 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 (lib/prisma.server.ts) 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.

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

@@ -100,7 +100,7 @@ each change must include.
   build tools or bundlers in the critical path.
 - **Erasable TypeScript only.** Node 24+ strips types via `module.stripTypeScriptTypes` (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.
-  Don't use inline `style="..."` on components (use `static styles = css\`...\``).
+- **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.
 - Components: extend WebComponent, declare `static properties` (and `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.
 - Server actions: *.server.ts files with one exported async function each.
 - Server-only code (@prisma/client, 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. lib/ holds both server-only infra (lib/prisma.server.ts) and browser-safe utilities (lib/utils/cn.ts with cn); apply the same rule per file.

package/templates/AGENTS.md

@@ -618,7 +618,7 @@ Practical consequences for agents writing webjs code.
 | Top-level `import` of a browser-only library | SSR crash | Dynamic `import()` inside `connectedCallback` |
 | Class-field initializer for a reactive property (`student: Student = {...}`) | Silently breaks reactivity (overwrites the framework accessor) | `declare student: Student` plus constructor default |
 | `@property()` decorator | Banned by invariant 10 (erasable TS) | `static properties = { ... }` plus `declare` |
-| `static styles = css` block without `static shadow = true` | Styles leak globally; the framework warns at runtime | Add `static shadow = true`, or use Tailwind utilities |
+| Scoped `static styles = css` or an inline `<style>` with semantic class names (`.hero`, `.card`) in a light-DOM component | Scoped block does nothing without `static shadow = true`; inline `<style>` class names leak globally | Tailwind utilities (the light-DOM default); or `static shadow = true` for genuinely scoped CSS |
 | `willUpdate` computing SSR-visible derived state | Works (runs at SSR), but overriding it opts the component out of elision | Fine for interactive components; for display-only, derive inline in `render()` |
 | `this.hasAttribute` / `getAttribute` in `render()` | Works (server attribute shim backs the attribute methods at SSR) | Read attributes directly, or via a `static properties` + `declare` reactive prop |
 | `ContextProvider` for server-known data | Default value during SSR, content shift on hydration | Pass via props from the page function |
@@ -627,6 +627,30 @@ The full annotated catalog with code examples lives in the framework
 repo at
 [`agent-docs/lit-muscle-memory-gotchas.md`](https://github.com/webjsdev/webjs/blob/main/agent-docs/lit-muscle-memory-gotchas.md).
 
+### Styling: Tailwind-first (the most common lit reflex to unlearn)
+
+**Tailwind utilities are the strong default for pages AND light-DOM
+components (the default DOM mode).** Use them for layout, spacing, color
+(via the `@theme` tokens), typography, borders, radius, shadows, and
+interaction states (hover/focus/active/disabled, dark mode). Light DOM
+does not scope styles, so utilities apply directly.
+
+The lit habit is to scope CSS in a shadow root (`static styles =
+css\`\``) or write an inline `<style>` with semantic class names
+(`.hero`, `.card`). In a light-DOM webjs component the scoped block does
+nothing without `static shadow = true`, and the inline class names leak
+globally. Prefer Tailwind. When a utility bundle repeats, extract it into
+a `lib/utils/ui.ts` helper returning an `` html`...` `` fragment, not a
+CSS class.
+
+Reserve raw CSS for what utilities cannot express: design-token `:root` /
+`@theme` definitions, `@property` + `@keyframes` animations,
+`::-webkit-scrollbar`, `prefers-reduced-motion` blocks, and complex
+`color-mix()` / gradient effects. When custom CSS is unavoidable in a
+light-DOM component, prefix every class selector with the component tag
+(invariant below). Shadow-DOM components (`static shadow = true`)
+legitimately use `static styles = css\`\`` for scoped CSS.
+
 ## Server action pattern
 
 ```ts

package/templates/CONVENTIONS.md

@@ -687,7 +687,7 @@ Both hydrate without flash on the client.
 
 ---
 
-## Styling: Tailwind + JS helpers
+## Styling: Tailwind-first + JS helpers
 
 <!-- OVERRIDE -->
 
@@ -697,6 +697,31 @@ fluid type scale value, and motion duration is declared once in `@theme`
 and available everywhere via utility classes (`text-fg`, `bg-bg-elev`,
 `font-serif`, `duration-fast`, `text-display`).
 
+**Tailwind-first is the strong default for pages AND light-DOM
+components (the default DOM mode).** Use utilities for layout, spacing,
+color (via the `@theme` tokens), typography, borders, radius, shadows,
+and interaction states (hover/focus/active/disabled, dark mode). Light
+DOM does not scope styles, so utilities apply directly.
+
+**The lit muscle-memory trap.** If you have written lit, the habit is to
+scope CSS in a shadow root (`static styles = css\`\``) or write an inline
+`<style>` with semantic class names (`.hero`, `.feature`, `.card`) for
+every component. In a webjs light-DOM component the scoped block does
+nothing without `static shadow = true`, and the inline class names leak
+into the global namespace. Prefer Tailwind utilities. When the same
+bundle repeats, extract a `lib/utils/ui.ts` helper (below), not a CSS
+class.
+
+**Custom-CSS allowlist (the only things raw CSS is for).** Reserve raw
+CSS for what utilities cannot express: design-token `:root` / `@theme`
+definitions, `@property` animated custom properties with `@keyframes`,
+`::-webkit-scrollbar` / `scrollbar-color`, `prefers-reduced-motion`
+blocks, and complex `color-mix()` or gradient effects. When custom CSS is
+unavoidable in a light-DOM component, the class-prefix rule (see the
+Components section above) still applies. Shadow-DOM components
+(`static shadow = true`) legitimately author `static styles = css\`\``;
+that is the right home for scoped CSS.
+
 **Dedup repeated Tailwind class bundles with JS helpers, not `@apply`.**
 When the same string of classes appears in 2+ places, extract it into a
 small function in `lib/utils/ui.ts`: