@webjsdev/cli 0.9.1 → 0.10.0

package/README.md

@@ -66,7 +66,7 @@ the CLI gives you `webjs ui` automatically. See
 The scaffold seeds opinionated defaults so AI agents produce consistent code:
 
 - `AGENTS.md` + `CONVENTIONS.md` (the machine-readable contract)
-- `.claude/`, `.cursorrules`, `.windsurfrules`, `.github/copilot-instructions.md`
+- `.claude/`, `.cursorrules`, `.agents/rules/workflow.md` (Antigravity), `.github/copilot-instructions.md`
 - `test/<feature>/` (with optional `browser/` / `e2e/` subfolders per kind) with example tests
 - Tailwind CSS via CLI (no browser runtime at build time)
 - TypeScript, `.editorconfig`, `.gitignore`

package/bin/webjs.js

@@ -8,7 +8,7 @@ const [cmd, ...rest] = process.argv.slice(2);
 
 // Exactly three scaffolds exist. Keep this list as the single source of
 // truth. AI-agent docs in README.md / AGENTS.md / .cursorrules /
-// .windsurfrules / .github/copilot-instructions.md mirror it.
+// .agents/rules/workflow.md / .github/copilot-instructions.md mirror it.
 const TEMPLATES = ['full-stack', 'api', 'saas'];
 
 const USAGE = `webjs commands:
@@ -26,6 +26,11 @@ const USAGE = `webjs commands:
   webjs ui <subcmd>                               AI-first component library CLI
                                                   (init / add / list / view / diff / info)
                                                   Requires @webjsdev/ui installed in the project
+  webjs vendor pin [--download]                   Pin client-side npm packages to .webjs/vendor/importmap.json
+                                                  Default: writes jspm.io URLs (browser fetches from CDN)
+                                                  --download: also downloads bundles for offline production
+  webjs vendor unpin <pkg>                        Remove a specific package from the pin file
+  webjs vendor list                               Show pinned packages with versions and URLs
   webjs help                                      Show this help`;
 
 /** @param {string[]} args */
@@ -266,6 +271,241 @@ Full docs: https://docs.webjs.com`);
       await scaffoldApp(name, process.cwd(), { template, install: !noInstall });
       break;
     }
+    case 'vendor': {
+      const sub = rest[0];
+      const args = rest.slice(1);
+      const appDir = process.cwd();
+      const { pinAll, unpinPackage, listPinned, auditPinned, findOutdated, updatePinned, readPinFile, SUPPORTED_PROVIDERS } = await import('@webjsdev/server');
+
+      // Parse `--from <provider>` once at the top so subcommands share it.
+      // Mirrors importmap-rails's `bin/importmap pin foo --from jsdelivr`.
+      let from = 'jspm';
+      const fromIdx = args.indexOf('--from');
+      if (fromIdx !== -1) {
+        from = args[fromIdx + 1];
+        if (!from || !SUPPORTED_PROVIDERS.has(from)) {
+          console.error(
+            `Unknown --from provider '${from || ''}'. Supported: ${[...SUPPORTED_PROVIDERS].join(', ')}.`,
+          );
+          process.exit(1);
+        }
+        // Strip --from + its argument so downstream flag checks like
+        // `args.includes('--download')` aren't confused.
+        args.splice(fromIdx, 2);
+      }
+
+      if (sub === 'pin') {
+        const download = args.includes('--download');
+        // Same precedence rule as `vendor update`: explicit --from
+        // wins; otherwise pinAll reads the pin file's persisted
+        // provider so a user who pinned via jsdelivr stays on it.
+        // Pass undefined (not the parsed 'jspm' default) when no
+        // --from to engage the pin-file fallback. Peek at the pin
+        // file here to compute the log line before pinAll runs.
+        const explicitFrom = fromIdx !== -1 ? from : undefined;
+        const existing = await readPinFile(appDir);
+        const usedFrom = explicitFrom || existing?.provider || 'jspm';
+        console.log(
+          `Pinning vendor packages from ${appDir}` +
+          (usedFrom !== 'jspm' ? ` via ${usedFrom}` : '') +
+          (download ? ' (downloading bundles)' : '') + '...',
+        );
+        const result = await pinAll(appDir, { download, from: explicitFrom });
+        if (result.noBareImports) {
+          // Scanner found zero bare-specifier imports in client-
+          // reachable source. Without this branch pinAll would write
+          // `{ imports: {} }`, which readPinFile then rejects as empty,
+          // leaving a useless file behind in whatever cwd.
+          console.error(
+            `Pin: no bare-specifier npm imports found in client code under ${appDir}. ` +
+            `Nothing to pin (no pin file written). Add a bare import like ` +
+            `\`import x from 'pkg-name'\` to a page or component, then rerun.`,
+          );
+          process.exit(1);
+        }
+        if (result.failed) {
+          // pinAll refused to write the pin file because every install
+          // failed to resolve via the chosen resolver (jspm.io's
+          // Generator API powers all providers; the failure mode is
+          // typically a brand-new published version not yet on the
+          // CDN, a network outage, or a provider-side 5xx). Surface
+          // the failure with the actual provider in the message so
+          // the user can fix the cause before shipping.
+          const provider = result.provider || 'jspm.io';
+          console.error(
+            `Pin FAILED: every package failed to resolve via ${provider}. No pin file written ` +
+            `(would shadow the live-API fallback with an empty importmap and break the browser).`,
+          );
+          console.error(`Attempted installs:`);
+          for (const i of result.attemptedInstalls) console.error(`  ${i}`);
+          console.error(
+            `Possible causes: the package version is too new for ${provider}'s CDN to have indexed yet; ` +
+            `network outage; ${provider} is down. Try again in a few minutes, or pin an older version.`,
+          );
+          process.exit(1);
+        }
+        const { pins, pruned, downloaded } = result;
+        for (const p of pins) {
+          const sizeStr = p.bytes != null ? ` ${(p.bytes / 1024).toFixed(1)} KB` : '';
+          console.log(`  ${(p.pkg + '@' + p.version).padEnd(40)}${sizeStr}`);
+        }
+        for (const f of pruned) {
+          console.log(`  ${f.padEnd(40)} REMOVED (orphan)`);
+        }
+        const pinMsg = `Pinned ${pins.length} package${pins.length === 1 ? '' : 's'}, wrote .webjs/vendor/importmap.json` +
+          (downloaded ? ` + ${downloaded} bundle${downloaded === 1 ? '' : 's'}` : '') + '.';
+        const pruneMsg = pruned.length ? ` Pruned ${pruned.length} orphan${pruned.length === 1 ? '' : 's'}.` : '';
+        console.log(pinMsg + pruneMsg);
+        break;
+      }
+
+      if (sub === 'unpin') {
+        if (args.length === 0) {
+          console.error('Usage: webjs vendor unpin <pkg>');
+          process.exit(1);
+        }
+        let unpinFailed = false;
+        for (const pkg of args) {
+          const r = await unpinPackage(appDir, pkg);
+          if (!r.removed) {
+            console.error(`  ${pkg.padEnd(40)} not in pin file`);
+            unpinFailed = true;
+            continue;
+          }
+          const extra = r.deletedFile ? ` (also deleted ${r.deletedFile})` : '';
+          console.log(`  ${pkg.padEnd(40)} unpinned${extra}`);
+        }
+        // Exit non-zero if ANY of the requested packages weren't in
+        // the pin file. Scripts wrapping the CLI rely on the exit
+        // code to detect "nothing was removed"; printing the message
+        // alone wasn't enough.
+        if (unpinFailed) process.exit(1);
+        break;
+      }
+
+      if (sub === 'list') {
+        const entries = await listPinned(appDir);
+        if (entries.length === 0) {
+          console.log('No pin file. Run "webjs vendor pin" to create .webjs/vendor/importmap.json.');
+          break;
+        }
+        console.log(`Pinned packages from ${appDir}/.webjs/vendor/importmap.json:`);
+        for (const e of entries) {
+          const sizeStr = e.bytes != null ? ` ${(e.bytes / 1024).toFixed(1)} KB` : '';
+          console.log(`  ${(e.pkg + '@' + e.version).padEnd(40)}${sizeStr}`);
+          console.log(`    ${e.url}`);
+        }
+        console.log(`${entries.length} package${entries.length === 1 ? '' : 's'} pinned.`);
+        break;
+      }
+
+      if (sub === 'audit') {
+        // npm bulk-advisories check against pinned versions. Mirrors
+        // bin/importmap audit. Exits non-zero when any vulnerability
+        // is found so CI can gate on it.
+        const { vulnerable, totalChecked, errored } = await auditPinned(appDir);
+        if (totalChecked === 0) {
+          console.log('No pinned packages to audit. Run "webjs vendor pin" first.');
+          break;
+        }
+        if (errored) {
+          console.error(
+            `Could not reach registry.npmjs.org for security advisories ` +
+            `(network failure, timeout, or 5xx). Retry when connectivity is back.`,
+          );
+          process.exit(1);
+        }
+        if (vulnerable.length === 0) {
+          console.log(`No vulnerable packages found (${totalChecked} checked).`);
+          break;
+        }
+        console.log(`Package                                  Severity   Vulnerable versions       Title`);
+        for (const v of vulnerable) {
+          console.log(
+            `  ${v.name.padEnd(38)} ${v.severity.padEnd(10)} ${v.vulnerableVersions.padEnd(25)} ${v.title}`,
+          );
+        }
+        const bySeverity = vulnerable.reduce((acc, v) => {
+          acc[v.severity] = (acc[v.severity] || 0) + 1;
+          return acc;
+        }, /** @type {Record<string,number>} */ ({}));
+        const summary = Object.entries(bySeverity)
+          .sort((a, b) => b[1] - a[1])
+          .map(([sev, n]) => `${n} ${sev}`).join(', ');
+        console.error(
+          `  ${vulnerable.length} vulnerabilit${vulnerable.length === 1 ? 'y' : 'ies'} found: ${summary}`,
+        );
+        process.exit(1);
+      }
+
+      if (sub === 'outdated') {
+        // npm registry latest-version check against pinned versions.
+        // Mirrors bin/importmap outdated. Exits non-zero when any
+        // package is outdated so CI / Renovate-style automation can
+        // detect it.
+        const outdated = await findOutdated(appDir);
+        if (outdated.length === 0) {
+          console.log('No outdated packages found.');
+          break;
+        }
+        console.log(`Package                                  Current               Latest`);
+        for (const o of outdated) {
+          console.log(`  ${o.pkg.padEnd(38)} ${o.current.padEnd(21)} ${o.latest}`);
+        }
+        console.error(
+          `  ${outdated.length} outdated package${outdated.length === 1 ? '' : 's'} found.`,
+        );
+        process.exit(1);
+      }
+
+      if (sub === 'update') {
+        // Re-pin outdated packages to latest. Mirrors bin/importmap
+        // update. Does NOT modify package.json or node_modules; the
+        // user should run `npm install <pkg>@<latest>` afterward to
+        // keep the local install in sync.
+        //
+        // Provider precedence: explicit --from CLI flag wins. Without
+        // it, updatePinned reads the pin file's persisted provider so
+        // a user who pinned via jsdelivr stays on jsdelivr after
+        // update. Pass `undefined` (not the parsed `from = 'jspm'`
+        // default) when no --from was given so updatePinned's
+        // pin-file fallback engages.
+        const explicitFrom = fromIdx !== -1 ? from : undefined;
+        const existing = await readPinFile(appDir);
+        const usedFrom = explicitFrom || existing?.provider || 'jspm';
+        console.log(`Updating outdated vendor pins in ${appDir}${usedFrom !== 'jspm' ? ` via ${usedFrom}` : ''}...`);
+        const result = await updatePinned(appDir, { from: explicitFrom });
+        if (result.noOutdated) {
+          console.log('No outdated packages found.');
+          break;
+        }
+        if (result.updated.length === 0) {
+          console.error('No packages were updated (jspm.io may have failed to resolve any of the new versions).');
+          process.exit(1);
+        }
+        for (const u of result.updated) {
+          console.log(`  ${u.pkg.padEnd(38)} ${u.from} → ${u.to}`);
+        }
+        console.log(
+          `Updated ${result.updated.length} package${result.updated.length === 1 ? '' : 's'}. ` +
+          `Run \`npm install ${result.updated.map(u => `${u.pkg}@${u.to}`).join(' ')}\` to ` +
+          `sync your node_modules.`,
+        );
+        break;
+      }
+
+      console.error(`Unknown vendor subcommand: ${sub || '(none)'}\n` +
+        `Usage:\n` +
+        `  webjs vendor pin [--from PROVIDER] [--download]   Pin packages to .webjs/vendor/importmap.json\n` +
+        `  webjs vendor unpin <pkg>                          Remove a package from the pin file\n` +
+        `  webjs vendor list                                 Show pinned packages with versions and URLs\n` +
+        `  webjs vendor audit                                Run a security audit against pinned versions\n` +
+        `  webjs vendor outdated                             Check pinned packages for newer versions\n` +
+        `  webjs vendor update [--from PROVIDER]             Re-pin outdated packages to latest\n` +
+        `\n` +
+        `  --from PROVIDER     CDN to resolve through. One of: ${[...SUPPORTED_PROVIDERS].join(', ')}. Default: jspm.`);
+      process.exit(1);
+    }
     case 'help':
     case undefined:
       console.log(USAGE);

package/lib/create.js

@@ -381,9 +381,14 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     '.cursor/hooks/nudge-uncommitted.sh',
     // OpenCode plugins (loaded as TS by Bun at runtime)
     '.opencode/plugins/nudge-uncommitted.ts',
+    // Antigravity workspace rules (Google's documented convention is
+    // `.agents/rules/*.md`, lowercase, per the Codelab
+    // "Build Autonomous Developer Pipelines using agents.md and skills.md
+    // in Antigravity"). Replaced the legacy `.windsurfrules` ship when
+    // Windsurf was acquired by Google.
+    '.agents/rules/workflow.md',
     // Cross-agent config files
     '.cursorrules',
-    '.windsurfrules',
     '.github/copilot-instructions.md',
     '.github/pull_request_template.md',
     '.editorconfig',
@@ -606,7 +611,7 @@ export type ActionResult<T> =
       .replace(/`/g, '\\`')
       .replace(/\$\{/g, '\\${');
 
-  await writeFile(join(appDir, 'app', 'layout.ts'), `import { html } from '@webjsdev/core';
+  await writeFile(join(appDir, 'app', 'layout.ts'), `import { html, cspNonce } from '@webjsdev/core';
 import '@webjsdev/core/client-router';
 import '../components/theme-toggle.ts';
 // Webjs UI components are tiered:
@@ -638,8 +643,13 @@ const navLink = (href: string, label: string) => html\`
 \`;
 
 export default function RootLayout({ children }: { children: unknown }) {
+  // Read the in-flight request's CSP nonce so the theme-detection
+  // inline script below passes strict CSP (script-src 'nonce-...').
+  // Returns '' when no CSP nonce is set, in which case the attribute
+  // is empty and the browser ignores it.
+  const nonce = cspNonce();
   return html\`
-    <script>
+    <script nonce="\${nonce}">
       (function(){
         try {
           var mq = window.matchMedia('(prefers-color-scheme: light)');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "type": "module",
   "description": "webjs CLI - dev, start, create, db",
   "bin": {
@@ -13,7 +13,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@webjsdev/server": "^0.7.2",
+    "@webjsdev/server": "^0.8.0",
     "@webjsdev/ui": "^0.3.1"
   },
   "publishConfig": {

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

@@ -0,0 +1,149 @@
+# Antigravity Workspace Rules: webjs app
+
+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**.
+
+## Persistence + scaffold rules (non-negotiable)
+
+- **Use Prisma + SQLite for data, never JSON files.** It is already wired up
+  (`prisma/schema.prisma`, `lib/prisma.server.ts`, `npm run db:migrate`). For
+  ANY data the app stores (todos, posts, messages, products, comments), define
+  a Prisma model. NEVER create `data/*.json`, `db.json`, or any JSON file as a
+  fake database. NEVER use module-scope arrays / Maps as a substitute. NEVER
+  use localStorage for app data. `webjs check`'s `no-json-data-files` rule
+  will fail the build if you do.
+- **The scaffold is reference, not the final product.** Replace `app/page.ts`,
+  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.
+- **Only three templates exist:** `webjs create <name>` (default full-stack),
+  `--template api`, `--template saas`. The CLI rejects any other `--template`
+  value. Pick:
+  - Any product UI (todo, blog, dashboard, marketplace, social) goes through
+    the default template.
+  - HTTP/JSON API only, no UI, uses `--template api`.
+  - Auth / login / signup / SaaS uses `--template saas`.
+
+## Before starting ANY work
+
+FIRST, before writing any code:
+1. Check `git branch --show-current`.
+   - If on main/master: create a feature branch before editing.
+   - If on a feature branch: verify it matches the current task.
+2. Sync: `git fetch origin && git rebase origin/main` if behind.
+
+## Autonomous mode (sandbox / no-prompt)
+
+If running without interactive approval, auto-decide:
+- On main? Auto-create feature/<task-slug> branch.
+- Parent behind? Auto-rebase. Merge? Auto-merge + delete feature branches.
+- Auto-generate commit messages. Fix failing tests and violations.
+Quality bar stays the same, no blocking on questions.
+
+## Mandatory workflow (never skip)
+
+Every code change must include:
+1. Server tests in `test/<feature>/*.test.ts` (node:test).
+2. Browser tests in `test/<feature>/browser/*.test.js` (WTR + Playwright, real Chromium).
+3. Documentation updates. Walk every surface in the **Definition of done**
+   section of CONVENTIONS.md (AGENTS.md, CONVENTIONS.md, README.md, docs/,
+   website/, scaffold scripts) and either update it or write
+   "N/A because <reason>" in the PR body. Docs land on the same PR as the
+   code, never as a follow-up.
+4. Convention check: `webjs check` must pass.
+5. Pre-merge self-review loop. Before saying the PR is ready for merge, run
+   fresh-context review rounds until one round finds zero issues. Antigravity
+   primitive: open a new Cascade thread or a fresh side-panel session for
+   each round so the reviewer has no prior context on the implementation
+   decisions. Minimum two rounds; rotate focus each round. Skip the loop
+   only for one-line trivial changes; skipping on a change that touches
+   logic, public surface, build, security, or multiple files is the exact
+   failure mode the loop exists to prevent. The full rule, prompt template,
+   and reporting contract live in the **Pre-merge self-review loop** section
+   of CONVENTIONS.md.
+
+The user should never have to ask for tests, documentation, or the
+self-review loop.
+
+## Git rules
+
+- COMMIT AND PUSH PER LOGICAL UNIT, NOT AT THE END. One feature, one fix, one
+  rename, one doc rewrite per commit. Always `git push` after committing.
+  The user should never have to ask for a commit.
+- HARD LIMIT: if you have 5+ unstaged files spanning different concerns,
+  commit before continuing. The Claude Code hook at
+  `.claude/hooks/nudge-uncommitted.sh` fires at threshold 4. Antigravity
+  users should self-enforce the same rule. Batching multiple logical units
+  into one commit is the failure mode this rule exists to prevent.
+- Meaningful commit messages: what changed and why.
+- NEVER add Co-Authored-By or AI attribution trailers to commits.
+- NEVER use em-dashes (U+2014), a hyphen-as-pause (` - `), or a
+  semicolon-as-pause (` ; `) in commit messages or anywhere else. Rewrite the
+  sentence so no pause-punctuation crutch is needed. Use a period, comma,
+  colon, parentheses, or a restructured phrasing. Plain hyphens stay fine in
+  compound words, CLI flags, filenames, and ranges. Semicolons stay fine
+  inside code.
+- Work on feature branches, never push directly to main.
+- Create pull requests for review.
+- NEVER merge any branch without explicit user permission. Always ask:
+  "Ready to merge <branch> into <target>? Delete or keep <branch> after?"
+  Wait for approval AND the delete/keep preference. Applies to ALL merges.
+- Run `webjs test` before every commit.
+
+## Framework rules
+
+- No build step: ES modules served directly.
+- **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 render into light DOM by default (so Tailwind / global CSS
+  apply directly). Opt in to shadow DOM per component with
+  `static shadow = true` when you need scoped styles (via
+  `static styles = css\`...\``) or third-party-embed isolation. `<slot>`
+  projection works identically in both modes (named slots, fallback content,
+  `assignedNodes` / `slotchange`, first-wins resolution).
+- 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`).
+- 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.
+- Directives are deliberately minimal: only `unsafeHTML`, `live`, and `repeat`
+  ship. Use plain template-literal expressions
+  (`class=${active ? 'btn active' : 'btn'}`, `style=${'color:' + color}`,
+  `${cond ? a : b}`) and lifecycle hooks (`this.query('#el')` in
+  `firstUpdated`) instead of Lit's `classMap` / `styleMap` / `ref` / `when` /
+  `choose` / `guard`.
+- Use Context for cross-component data, Task for async data in components.
+- **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), 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.
+- **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.
+- Full API reference in AGENTS.md.

package/templates/.cursorrules

@@ -1,6 +1,6 @@
-# Cursor Rules - webjs app
+# Cursor Rules: webjs app
 
-You are working on a webjs app - an AI-first, no-build, web-components-first
+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**.
@@ -36,7 +36,7 @@ FIRST, before writing any code:
    - If upstream has new commits: `git rebase origin/main` before starting.
    - Resolve any conflicts before proceeding with the task.
 
-## Autonomous mode (sandbox / no-prompt mode)
+## Autonomous mode (sandbox / no-prompt)
 
 If running without interactive approval, auto-decide:
 - On main? Auto-create feature/<task-slug> branch
@@ -44,29 +44,44 @@ If running without interactive approval, auto-decide:
 - Merge? Auto-merge in autonomous mode, delete feature branches after
 - Commit message? Auto-generate (meaningful, no AI attribution)
 - Tests failing? Fix them. Convention violations? Fix them.
-Quality bar stays the same - just no blocking on questions.
+Quality bar stays the same, no blocking on questions.
 
 ## Mandatory workflow (never skip)
 
-1. TESTS: Server tests in test/<feature>/ (node:test), browser tests in
-   test/<feature>/browser/ (WTR + Playwright, real Chromium). Run `webjs test`
-   after every change. Never deliver code without passing tests.
+Every code change must include:
+1. Server tests in `test/<feature>/*.test.ts` (node:test).
+2. Browser tests in `test/<feature>/browser/*.test.js` (WTR + Playwright, real Chromium).
+3. Documentation updates. Walk every surface in the **Definition of done**
+   section of CONVENTIONS.md (AGENTS.md, CONVENTIONS.md, README.md, docs/,
+   website/, scaffold scripts) and either update it or write
+   "N/A because <reason>" in the PR body. Docs land on the same PR as the
+   code, never as a follow-up.
+4. Convention check: `webjs check` must pass.
+5. Pre-merge self-review loop. Before saying the PR is ready for merge, run
+   fresh-context review rounds until one round finds zero issues. Cursor
+   primitive: open a NEW composer tab and prompt the review there so the
+   reviewer has no prior context on your decisions. Minimum two rounds;
+   rotate focus each round. Skip the loop only for one-line trivial
+   changes; skipping on a change that touches logic, public surface, build,
+   security, or multiple files is the exact failure mode the loop exists
+   to prevent. The full rule, prompt template, and reporting contract live
+   in the **Pre-merge self-review loop** section of CONVENTIONS.md.
 
-2. DOCS: Update AGENTS.md for API changes. Update docs/ and website/ if
-   they exist. The user should never have to ask for tests or docs.
-
-3. CONVENTIONS: Run `webjs check` and fix violations before committing.
+The user should never have to ask for tests, documentation, or the
+self-review loop.
 
 ## Git rules
 
 - COMMIT AND PUSH PER LOGICAL UNIT, NOT AT THE END. One feature, one fix,
   one rename, one doc rewrite per commit. Always `git push` after
-  committing. This is automatic.
+  committing. The user should never have to ask for a commit.
 - HARD LIMIT: if you have 5+ unstaged files spanning different concerns,
-  commit before continuing. The Claude Code hook at
-  `.claude/hooks/nudge-uncommitted.sh` fires at threshold 4. Cursor users
-  should self-enforce the same rule. Batching multiple logical units into
-  one commit is the failure mode this rule exists to prevent.
+  commit before continuing. Cursor 1.7+ has its own
+  `.cursor/hooks/nudge-uncommitted.sh` (afterFileEdit) firing at threshold
+  4; the same enforcement runs for Claude users via
+  `.claude/hooks/nudge-uncommitted.sh`. On older Cursor versions without
+  the hook, self-enforce the same rule. Batching multiple logical units
+  into one commit is the failure mode this rule exists to prevent.
 - Write meaningful commit messages: what changed and why, not "update files"
 - NEVER add "Co-Authored-By", "Generated by", "AI-assisted" or similar
   attribution trailers to commits
@@ -77,23 +92,22 @@ Quality bar stays the same - just no blocking on questions.
   Plain hyphens stay fine in compound words, CLI flags, filenames,
   and ranges. Semicolons stay fine inside code
 - Work on feature branches, not main
-- NEVER push directly to main - create a pull request
+- NEVER push directly to main. Create a pull request instead.
 - NEVER merge any branch without explicit user permission. Always ask:
   "Ready to merge <branch> into <target>? Delete or keep <branch> after?"
   Wait for approval AND the delete/keep preference before proceeding.
   This applies to ALL merges, not just merges into main.
 - Run tests before every commit
-- Keep commits small and focused
 
 ## Framework rules
 
 - 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 falls back to esbuild + inline sourcemap for those files (~3x wire bytes per request).
+- **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
 - 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.
-- Directives are deliberately minimal: only `unsafeHTML`, `live`, and `repeat` ship. Lit's `classMap` / `styleMap` / `ref` / `when` / `choose` / `guard` are NOT exported - 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()`, not `connectedCallback` - the server doesn't call lifecycle hooks). Initial data for components comes from the page function (server-side fetch + pass as attribute/property), NOT from `fetch` calls in `connectedCallback`. For write-paths, prefer `<form action=...>` + server action over `fetch` + click handler - the framework upgrades plain forms to partial-swap submissions automatically.
-- **Client navigation is auto-magic.** Real `<a href>` and `<form action>` get partial-swap behavior with no opt-in. Layouts persist across navigation - put shared chrome (sidenav, header) in `layout.ts`, 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.
+- Directives are deliberately minimal: only `unsafeHTML`, `live`, and `repeat` ship. Lit's `classMap` / `styleMap` / `ref` / `when` / `choose` / `guard` are NOT exported. 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), 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.
+- **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.
 - See AGENTS.md for the complete directive decision guide

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

@@ -33,53 +33,80 @@ FIRST, before writing any code:
    - If on a feature branch: verify it matches the task at hand.
 2. Sync: `git fetch origin && git rebase origin/main` if behind.
 
-## Autonomous mode
+## Autonomous mode (sandbox / no-prompt)
 
 If running without interactive approval (sandbox, auto-approve, etc.):
 - On main? Auto-create feature/<task-slug> branch
 - Parent behind? Auto-rebase. Merge? Auto-merge + delete feature branches.
 - Auto-generate meaningful commit messages. Fix tests and violations.
 
-## Mandatory workflow
+Quality bar stays the same, no blocking on questions.
+
+## Mandatory workflow (never skip)
 
 Every code change must include:
-1. Commit and push PER LOGICAL UNIT, not at the end. One feature, one fix,
-   one rename, one doc rewrite per commit. Always `git push` after
-   committing. Don't accumulate changes. If you have 5+ unstaged files
-   spanning different concerns, commit before continuing. The Claude Code
-   hook at `.claude/hooks/nudge-uncommitted.sh` enforces threshold 4 for
-   Claude users; Copilot users should self-enforce the same rule. Automatic.
-2. Server tests in test/<feature>/*.test.ts (node:test for actions, queries, utilities)
-3. Browser tests in test/<feature>/browser/*.test.js (WTR + Playwright, real Chromium)
-4. Documentation updates (AGENTS.md for API, docs/ for user guides)
-5. Convention validation: `webjs check` must pass
+1. Server tests in `test/<feature>/*.test.ts` (node:test).
+2. Browser tests in `test/<feature>/browser/*.test.js` (WTR + Playwright, real Chromium).
+3. Documentation updates. Walk every surface in the **Definition of done**
+   section of CONVENTIONS.md (AGENTS.md, CONVENTIONS.md, README.md, docs/,
+   website/, scaffold scripts) and either update or write
+   "N/A because <reason>" in the PR body. Docs land on the same PR as the
+   code, never as a follow-up.
+4. Convention check: `webjs check` must pass.
+5. Pre-merge self-review loop. Before saying the PR is ready for merge,
+   run fresh-context review rounds until one round finds zero issues.
+   Copilot primitive: open a NEW chat session (reset the side panel) for
+   each round so the reviewer has no prior context on the implementation
+   decisions. Minimum two rounds; rotate focus each round. Skip the loop
+   only for one-line trivial changes; skipping on a change that touches
+   logic, public surface, build, security, or multiple files is the exact
+   failure mode the loop exists to prevent. The full rule, prompt
+   template, and reporting contract live in the **Pre-merge self-review
+   loop** section of CONVENTIONS.md.
+
+The user should never have to ask for tests, documentation, or the
+self-review loop. The commit-per-logical-unit rule lives under "Git rules"
+below, not here, since it governs how work is grouped rather than what
+each change must include.
 
 ## Git rules
 
-- Commit after each logical unit of work
+- COMMIT AND PUSH PER LOGICAL UNIT, NOT AT THE END. One feature, one fix,
+  one rename, one doc rewrite per commit. Always `git push` after
+  committing. The user should never have to ask for a commit.
+- HARD LIMIT: if you have 5+ unstaged files spanning different concerns,
+  commit before continuing. The Claude Code hook at
+  `.claude/hooks/nudge-uncommitted.sh` enforces threshold 4 for Claude
+  users. Copilot has no equivalent hook surface today; self-enforce the
+  same rule. Batching multiple logical units into one commit is the
+  failure mode this rule exists to prevent.
 - Meaningful commit messages: what changed and why
 - NEVER add Co-Authored-By or AI attribution trailers to commits
+- NEVER use em-dashes (U+2014), a hyphen-as-pause (` - `), or a
+  semicolon-as-pause (` ; `) in commit messages or anywhere else.
+  Rewrite the sentence so no pause-punctuation crutch is needed. Use a
+  period, comma, colon, parentheses, or a restructured phrasing. Plain
+  hyphens stay fine in compound words, CLI flags, filenames, and ranges.
+  Semicolons stay fine inside code.
 - Work on feature branches, create PRs, never push directly to main
 - NEVER merge any branch without explicit user permission. Always ask:
   "Ready to merge <branch> into <target>? Delete or keep <branch> after?"
   Wait for approval AND the delete/keep preference. Applies to ALL merges.
 - Run `webjs test` before every commit
 
-## Code patterns
+## Framework rules
 
-- **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 falls back to esbuild + inline sourcemap for those files (~3x wire bytes per request).
-- Tagged template: html`<div>${value}</div>` with css`...` for styles
+- No build step: source files are served as ES modules. Don't introduce
+  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\`...\``).
 - 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
-- Directives: webjs ships only `unsafeHTML`, `live`, and `repeat`. Lit's `classMap` / `styleMap` / `ref` / `when` / `choose` / `guard` are NOT exported - use plain template-literal expressions and lifecycle hooks instead.
+- 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.
+- Directives: webjs ships only `unsafeHTML`, `live`, and `repeat`. Lit's `classMap` / `styleMap` / `ref` / `when` / `choose` / `guard` are NOT exported. Use plain template-literal expressions and lifecycle hooks instead.
 - Context: import { createContext, ContextProvider, ContextConsumer } from '@webjsdev/core/context'
 - Task: import { Task, TaskStatus } from '@webjsdev/core/task'
-- Routing: file-based under app/ (page.ts, layout.ts, route.ts, middleware.ts)
-
-## What NOT to do
-
-- Don't introduce build tools or bundlers in the critical path
-- 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.
-- Don't use inline style="..." on components (use static styles = css`...`)
+- Routing: file-based under app/ (page.ts, layout.ts, route.ts, middleware.ts).
 - Component state lives in signals from @webjsdev/core. Module-scope signals share state across components; instance signals (created in the constructor) carry component-local state. Reactive properties (static properties + declare) are for HTML attributes and .prop=${...} hydration.
-- Don't skip tests or documentation updates
+- Don't skip tests or documentation updates.

package/templates/.github/pull_request_template.md

@@ -8,7 +8,31 @@
 - [ ] E2E tests added/updated for user-facing changes (`webjs test --e2e` passes)
 - [ ] `webjs check` passes (no convention violations)
 
-## Documentation
+## Definition of done
 
-- [ ] AGENTS.md updated (if API surface changed)
-- [ ] Docs updated (if docs/ exists and feature is documented)
+Documentation MUST land on the same PR as the code change. Drift is how
+a codebase rots. Walk every markdown file in the project (`git ls-files
+'*.md'`) and ask whether this PR changed behaviour, surface, or
+invariants it describes. For each row below, write `Updated <path>` or
+`N/A because <reason>`. Reviewers should reject the PR if this section
+is left as the template default. See the **Definition of done** section
+in [`CONVENTIONS.md`](../CONVENTIONS.md) for the full guidance.
+
+- [ ] **Tests.** Unit coverage for logic. Real-browser coverage for
+      user-facing behaviour.
+- [ ] **Every markdown file in the project** that describes the
+      changed surface. Common cases (non-exhaustive): `AGENTS.md` (root
+      + nested), `CONVENTIONS.md`, `README.md` (root + nested),
+      `CHANGELOG.md`, `docs/**/*.md`, `agent-docs/**/*.md`,
+      `.github/*.md`. The rule is generative: if a markdown file in
+      this project mentions a thing this PR changed, it gets touched
+      on this PR.
+- [ ] **`website/`** (if the project has one). Marketing copy on the
+      landing or pricing page when the change touches a claim made
+      there.
+- [ ] **Scaffold scripts / codegen** (if the project has any). Updated
+      when the change affects what new instances generate.
+- [ ] **Pre-merge self-review loop.** Ran N rounds; last round clean.
+      Skip only for one-line trivial changes. See the **Pre-merge
+      self-review loop** section in [`CONVENTIONS.md`](../CONVENTIONS.md)
+      for the prompt template and reporting contract.

package/templates/.hooks/pre-commit

@@ -22,7 +22,7 @@ if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
 fi
 
 # webjs test + webjs check on every commit. Tool-agnostic enforcement:
-# fires regardless of which agent (Claude, Cursor, Windsurf, Copilot,
+# fires regardless of which agent (Claude, Cursor, Antigravity, Copilot,
 # human) is making the commit. Skipped if the CLI is not yet installed
 # (fresh clone before npm install).
 if command -v webjs >/dev/null 2>&1 || [ -x "node_modules/.bin/webjs" ]; then

package/templates/AGENTS.md

@@ -301,6 +301,20 @@ In Docker / Railway, prefer `npm start` (or `node node_modules/.bin/npm
 start`) as the CMD over `node ... webjs.js start ...`. The npm form
 fires `prestart`; the direct binary form skips it.
 
+**Health and readiness probes.** Every webjs server answers two endpoints:
+`/__webjs/health` (liveness, 200 once the process is listening) and
+`/__webjs/ready` (readiness, 503 until the instance is fully warm, then 200).
+Fully warm means the deterministic analysis AND the first vendor attempt have
+both completed, so the importmap and its build id are settled. Point your
+platform's readiness check at `/__webjs/ready` so it holds traffic off a
+not-yet-warmed instance instead of routing the first user request into the cold
+analysis or the brief window where the importmap is still resolving. On
+Railway, set `"healthcheckPath": "/__webjs/ready"` under `deploy` in
+`railway.json`. For dependency-aware
+readiness (gate on a live DB ping), add an optional `readiness.{js,ts}` at the
+app root that default-exports an async check; `/__webjs/ready` runs it once warm
+and reports 503 if it returns `false` or throws.
+
 Scripts:
 
 - `npm run db:migrate`: `prisma migrate dev` (dev-time schema changes + migration + generate)
@@ -320,6 +334,87 @@ const users = await prisma.user.findMany();
 To switch to Postgres or MySQL: change `provider` in `prisma/schema.prisma`
 and the `DATABASE_URL` in `.env`.
 
+## NPM packages (vendor pipeline)
+
+Adding a third-party npm package follows the same `npm install` flow
+as any Node project, with one webjs-specific concern: how the BROWSER
+fetches that package.
+
+```sh
+npm install dayjs                 # standard npm install
+```
+
+Now write `import dayjs from 'dayjs'` in any component or page. The
+import works in dev immediately. webjs's scanner discovers bare
+imports on the first request (memoized for the process) and asks
+`api.jspm.io` to resolve them to CDN URLs (jspm.io serves pre-bundled
+ESM for every npm package). The browser fetches the bundle directly
+from `https://ga.jspm.io`.
+
+**For production deploys**, run `webjs vendor pin` once and commit
+the result:
+
+```sh
+webjs vendor pin                  # writes .webjs/vendor/importmap.json
+git add .webjs/vendor/
+git commit -m "vendor dayjs"
+```
+
+The pin file holds the resolved jspm.io URLs. Server reads it from
+disk on the first request (memoized); no `api.jspm.io` call needed in
+production. Deterministic across deploys.
+
+**For offline-capable / strict-CSP production**, use `--download`:
+
+```sh
+webjs vendor pin --download       # also vendors bundle bytes locally
+git add .webjs/vendor/
+git commit -m "vendor + download dayjs"
+```
+
+Bundle files land in `.webjs/vendor/<pkg>@<version>.js`. importmap
+points at local `/__webjs/vendor/` paths. Browser fetches from your
+own origin. Suitable for `script-src 'self'` CSP, air-gapped deploys,
+or compliance environments. See [docs.webjs.com Deployment → CSP](https://docs.webjs.com/docs/deployment#csp).
+
+**Other CLI commands:**
+
+```sh
+webjs vendor list                 # show pinned packages with versions
+webjs vendor unpin <pkg>          # remove one entry from pin file
+webjs vendor audit                # npm security advisories against pinned versions
+webjs vendor outdated             # list pinned packages with newer versions on npm
+webjs vendor update               # re-pin every outdated package to its latest
+
+# Switch CDN at pin time (default: jspm.io). Resolver options:
+# jspm, jsdelivr, unpkg, skypack. Useful for jspm.io incident response.
+webjs vendor pin --from jsdelivr
+webjs vendor update --from jsdelivr
+```
+
+Same posture as Rails 7 + importmap-rails: explicit pin command,
+committed manifest, optional `--download` for full offline capability,
+and a `--from` knob to swap the resolver CDN if jspm.io has an
+incident.
+
+**Don't auto-run `webjs vendor pin` in `predev` / `prestart`.** Auto-pin
+would silently churn the committed importmap.json as jspm.io resolves
+URLs or transitive deps drift. Pin is a deliberate developer action,
+like `npm install` itself.
+
+**Do NOT modify the `.webjs/` lines in `.gitignore` / `.dockerignore`.**
+The scaffolded pattern is three lines (`.webjs/*` + `!.webjs/vendor/`
++ `!.webjs/vendor/**`) and is structurally load-bearing. Collapsing it
+to a single `.webjs/` excludes the parent directory; once the parent
+is excluded, git cannot re-include `.webjs/vendor/` via a child
+negation (gitignore semantics: parent exclusion blocks child
+negations). The breakage is invisible: `webjs vendor pin` runs, writes
+files, and git silently ignores them. Production then has no
+importmap.json and the server falls back to calling api.jspm.io on
+every cold start. The `gitignore-vendor-not-ignored` lint rule
+(`webjs check`) verifies the pattern with `git check-ignore` and will
+fail CI if it regresses.
+
 ## Imports
 
 ```ts
@@ -770,9 +865,9 @@ composition, so a nested shell ends up dropped by the HTML parser.
    ```
 
    If you turn `erasableSyntaxOnly` off and use non-erasable syntax,
-   the dev server falls back to esbuild and emits inline sourcemaps
-   for those specific files: roughly 3x wire bytes per request, and
-   stack-trace positions are no longer byte-exact. The
+   the dev server fails at strip time and returns a 500 naming the
+   file and pointing at the `no-non-erasable-typescript` lint rule.
+   webjs is buildless end-to-end and has no bundler fallback. The
    `erasable-typescript-only` convention check warns when the flag
    is missing or set to false.
 9. **No em-dashes (U+2014) anywhere, and no hyphen or semicolon used
@@ -802,14 +897,25 @@ composition, so a nested shell ends up dropped by the HTML parser.
    | Gemini CLI | `.gemini/hooks/nudge-uncommitted.sh` (`AfterTool`) | `.gemini/settings.json` |
    | Cursor 1.7+ | `.cursor/hooks/nudge-uncommitted.sh` (`afterFileEdit`) | `.cursor/hooks.json` |
    | OpenCode | `.opencode/plugins/nudge-uncommitted.ts` (`tool.execute.after`) | `.opencode/plugins/` |
-   | Windsurf | text rule only (post-write hooks cannot inject context) | `.windsurfrules` |
+   | Antigravity (Google) | text rule only (post-write hooks not yet exposed) | `.agents/rules/workflow.md` |
    | GitHub Copilot | text rule only (no hooks API) | `.github/copilot-instructions.md` |
-   | Google Antigravity | text rule only (no hooks API) | `AGENTS.md` |
 
    Tool-agnostic fallback: `.hooks/pre-commit` runs `webjs test` + `webjs check`
    on every commit, regardless of which agent (or human) made it. No AI
    attribution trailers in commit messages.
-4. When unsure how a framework feature works, `grep` or `cat` the
+4. Run the **pre-merge self-review loop** before signaling the PR is
+   ready. After committing the work, trigger a fresh-context review
+   pass (a new chat / composer tab / subagent / Cascade thread
+   depending on your tool) and iterate fix-then-review rounds until
+   one round finds zero issues. Minimum two rounds; rotate focus each
+   round so the reviewer does not rediscover the same surface twice.
+   Skip the loop only for one-line trivial changes; skipping on a
+   change that touches logic, public surface, build, security, or
+   multiple files is the exact failure mode the loop exists to
+   prevent. The full rule, prompt template, and reporting contract
+   live in the **Pre-merge self-review loop** section of
+   `CONVENTIONS.md`.
+5. When unsure how a framework feature works, `grep` or `cat` the
    relevant `node_modules/@webjsdev/*/src/` file before asking the user.
 
 Project-specific conventions and overrides live in

package/templates/CONVENTIONS.md

@@ -95,16 +95,135 @@ even if the user doesn't explicitly ask.**
    Run `webjs test` after every change. Never mark work as done with
    failing tests.
 
-3. **Documentation updates.** When adding or modifying features:
-   - Update `AGENTS.md` if the change affects the framework API surface.
-   - Update `CONVENTIONS.md` only if the change introduces a new convention.
-   - If a `docs/` directory exists, add or update the relevant doc page.
-   - If a `website/` directory exists, update the landing page for
-     user-facing features.
-
-3. **Convention check.** Run `webjs check` after changes and fix
+3. **Documentation updates.** See the **Definition of done** section
+   below for the per-surface checklist. The short version: docs land on
+   the same PR as the code, never as a follow-up. Drift is how a
+   codebase rots; the user should never have to ask "did you update the
+   docs?"
+
+4. **Convention check.** Run `webjs check` after changes and fix
    any violations before reporting the task as done.
 
+### Definition of done (MUST be addressed BEFORE opening the PR)
+
+This is the per-PR contract. Before running `gh pr create`, walk through
+every surface below and either update it OR write `N/A because <reason>`
+in the PR body so the omission is visible. The
+[`.github/pull_request_template.md`](./.github/pull_request_template.md)
+checklist mirrors this list.
+
+**Surfaces to consider on EVERY PR:**
+
+1. **Tests.** Unit coverage for new logic. Real-browser coverage for
+   user-facing behaviour. `webjs test` must pass; `webjs test --browser`
+   for any DOM-touching change. See the "Testing" section below for the
+   per-change matrix.
+2. **Every markdown file in the project.** Walk the whole tree, not a
+   closed list. Run `git ls-files '*.md'` (or `git ls-files '*.md'
+   '*.mdx'` if the project ships MDX) and for each path ask: does this
+   file describe behaviour, surface, or invariants that this PR changed?
+   If yes, update it on this PR. Common surfaces (non-exhaustive):
+   - `AGENTS.md` (root and every nested one) for API surface, invariants,
+     file-routing rules, project-wide agent workflow.
+   - `CONVENTIONS.md` (this file) for architectural conventions. Do NOT
+     enumerate lint rules in prose; those live in `package.json` under
+     `"webjs": { "conventions": { … } }`.
+   - `README.md` (root and any nested ones) for install / use / public
+     surface descriptions.
+   - `CHANGELOG.md` for any user-visible change, including the SHA / PR
+     reference. Keep it in chronological order; don't backdate.
+   - `docs/` (if the project has one). Every user-visible change. Add a
+     new page if the surface is new and there's no obvious home.
+   - Any `*.md` under `agent-docs/`, `docs-internal/`, `decisions/`, or
+     similar reference trees.
+   - `.github/*.md` (issue templates, PR templates, contributing) when
+     a workflow rule shifts.
+3. **`website/`** (if the project has one). Marketing copy on the
+   landing page or pricing page when the change touches a claim made
+   there.
+4. **Scaffold or codegen scripts** (if the project has any). Update
+   when the change affects what new instances generate.
+5. **PR body.** Summary, test plan checklist, and a per-row answer to
+   the Definition-of-done checklist (`Updated <path>` or `N/A because
+   <reason>`).
+
+**How to use the checklist.** For each surface above, explicitly answer
+one of:
+
+- **Updated**, with the file path in the commit and PR body.
+- **N/A because**, with a one-sentence reason.
+
+The "every markdown file" rule is generative, not enumerative. New
+markdown files appear over a project's lifetime, and this checklist
+must not silently exclude them. The git query above is the source of
+truth; the named files are just common cases.
+
+If you find yourself writing `N/A` for every surface except tests, that
+is a smell. Most user-visible code changes touch at least one markdown
+file and either `AGENTS.md` or `CONVENTIONS.md`.
+
+**Worked examples:**
+
+- Add a new server action `modules/posts/actions/create-post.server.ts`.
+  Updated: test (`test/posts/posts.test.ts`), `AGENTS.md` (action listed
+  in the module map if the project keeps one), `CHANGELOG.md` (one-line
+  entry), `docs/` (the page listing shipped actions if one exists). N/A
+  on website / scaffold scripts.
+- Rename a directory convention (e.g. `modules/` to `features/`).
+  Updated: existing tests still pass after renames, every markdown file
+  that mentions the old name (run `git grep -l 'modules/' '*.md'`),
+  scaffold scripts, `CHANGELOG.md`. N/A on website unless the layout
+  appears in a landing-page screenshot.
+- Fix a bug in `rateLimit()` that doesn't change the surface. Updated:
+  test (regression), `CHANGELOG.md` (one-line entry under fixes). N/A
+  on every other markdown file because the public contract did not
+  change.
+
+### Pre-merge self-review loop (MUST run before signaling the PR is ready)
+
+Saying "ready for merge" before a self-review loop converges is a recurring source of low-quality PRs. The pattern to avoid: agent claims ready-for-merge, user requests a code review, agent finds issues, fixes them, claims ready-for-merge again, repeat 4-5 cycles before a review comes back clean. The cure is to run that loop internally before the first "ready" signal, so the user only hears "ready to merge" after the loop has converged on a clean round.
+
+**How the loop works:**
+
+1. After committing the work and (if remote pushes are in use) pushing the branch, do NOT report "ready for merge" yet. Trigger a **fresh-context review pass**: an AI review with NO prior knowledge of the decisions you made during the implementation. Each AI tool exposes its own primitive for this:
+
+   - **Cursor**: open a new composer tab.
+   - **Claude Code**: spawn a `general-purpose` subagent via the Agent tool.
+   - **GitHub Copilot**: open a new chat (reset the side panel).
+   - **Antigravity** (Google, formerly Windsurf): open a new Cascade thread or a fresh side-panel session.
+   - **Aider**: invoke a separately-started `aider` session (do NOT use `/ask` inside the same session; `/ask` only flips the mode for the next message and still sees the existing context).
+   - **Gemini CLI**: invoke a separately-started `gemini` session.
+   - **OpenCode**: open a new agent session (the `tool.execute.after` hook is a different surface and not a fresh-context primitive).
+
+   The shared property is that the reviewer does not see your decision log. That independence is what makes the review catch blind spots. If your tool does not expose a true fresh-context primitive, the canonical fallback is a separately-invoked CLI process; what matters is the reviewer starts with an empty context, not the specific UI affordance.
+
+2. Prompt the review for problems only. A working prompt template:
+
+   > Review the changes on this branch against the project's `AGENTS.md` and `CONVENTIONS.md`. Look for bugs, regressions, security issues, missed edge cases, broken invariants, doc drift, test gaps, and style violations. Read every file the diff touches in its current state, not just the diff hunks. Specifically check: \<focus rotates per round\>. Report findings as a numbered list with file:line references. Problems only, no suggestions. If you find nothing genuinely wrong, reply exactly `CLEAN` on its own line and stop.
+
+3. For each finding the review reports, either:
+
+   - Fix it on the branch (commit + push), OR
+   - Reject it explicitly with a one-sentence reason. False positives are real, but rejection has to be defensible (e.g. "the reviewer flagged X as a security issue but X runs server-side only and never reaches user input"). Hand-waving doesn't count.
+
+4. If the round found any findings, run another round. The new round picks a slightly different focus: if round 1 was broad, round 2 zooms in on the file you most edited; if round 2 zoomed in, round 3 zooms out to cross-file consistency. Rotate focus to avoid the reviewer rediscovering the same surface twice.
+
+5. If the round reports `CLEAN`, the loop is done.
+
+The minimum is TWO rounds. A clean first round is rare and usually means the review was too shallow; if round 1 is clean, run a second one with a sharper focus before believing the result.
+
+**When to skip the loop:**
+
+Skip only for changes that touch a single line of trivially-correct content (a doc typo, a renamed local variable, a one-token config bump). Anything that touches logic, public surface, build, security, or multiple files goes through the loop without exception. A bias toward running the loop is correct; a bias toward skipping it is the exact failure mode this rule exists to prevent.
+
+**Reporting after the loop:**
+
+When the user is notified the PR is ready, the message should carry:
+
+> Ready for merge. Self-review loop ran \<K\> rounds; last round clean. Issues found and fixed during the loop: \<one-line list, or "none" if rounds 2+ kept finding nothing\>.
+
+If you cannot honestly say "last round clean", you cannot say "ready for merge". If a finding was rejected as a false positive, mention it so the user can second-guess the rejection.
+
 ### Autonomous mode (sandbox / bypass permissions)
 
 When running without interactive approval, agents must NOT ask questions.
@@ -653,7 +772,15 @@ Use `rateLimit()` as per-segment middleware to protect routes:
 ```ts
 // app/api/auth/middleware.ts: protect auth endpoints
 import { rateLimit } from '@webjsdev/server';
+
+// Direct deploy (default). Keys on the socket-stamped IP, ignoring
+// forwarded-IP headers.
 export default rateLimit({ window: '10s', max: 5 });
+
+// Behind a reverse proxy or CDN (Cloudflare, Railway, Fly, Vercel,
+// nginx, Caddy). Set trustProxy to honour X-Forwarded-For. The proxy
+// MUST strip inbound X-Forwarded-For before adding its own.
+export default rateLimit({ window: '10s', max: 5, trustProxy: true });
 ```
 
 Place `middleware.ts` at any route level. It applies to that subtree only.
@@ -681,9 +808,11 @@ SSR content is visible immediately. Only the JS download is deferred.
 ## expose(): REST endpoints from server actions
 
 <!-- OVERRIDE -->
-Tag a server action to also be reachable over HTTP:
+Tag a server action to also be reachable over HTTP. The file MUST be a `.server.{js,ts}` file: `expose()` is server-only and the bare `@webjsdev/core` specifier resolves to the browser entry which excludes it, so importing from a client-bound file silently reads `undefined`.
 
 ```ts
+// modules/posts/actions/create-post.server.ts
+'use server';
 import { expose } from '@webjsdev/core';
 export const createPost = expose('POST /api/posts', async ({ title, body }) => {
   return prisma.post.create({ data: { title, body } });
@@ -823,7 +952,7 @@ export async function createPost(input: {
     constructor(x: number) { this.x = x; }
   }
   ```
-  If you turn `erasableSyntaxOnly` off and use non-erasable syntax, the dev server falls back to esbuild and ships inline sourcemaps for those files (~3x wire bytes per request and stack traces lose strict accuracy). The `erasable-typescript-only` convention check warns when the flag is off.
+  If you turn `erasableSyntaxOnly` off and use non-erasable syntax, 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. The `erasable-typescript-only` convention check warns when the flag is off.
 - No semicolons (or with semicolons, pick one and stay consistent)
 - `const` by default, `let` when needed, never `var`
 - Prefer `async/await` over `.then()` chains
@@ -837,7 +966,7 @@ export async function createPost(input: {
 <!-- OVERRIDE -->
 
 This project enforces a git workflow via agent-specific config files
-(`.claude/settings.json`, `.cursorrules`, `.windsurfrules`,
+(`.claude/settings.json`, `.cursorrules`, `.agents/rules/workflow.md`,
 `.github/copilot-instructions.md`). These rules apply to ALL AI agents:
 
 **Commit rules:**
@@ -862,7 +991,7 @@ This project enforces a git workflow via agent-specific config files
   Delete or keep `<branch>` after?" Wait for approval AND the preference.
 - **Claude Code hook** (`.claude/hooks/guard-main-merge.sh`) enforces
   merge/push-to-main approval programmatically for Claude agents.
-  Other agents enforce this via `.cursorrules`, `.windsurfrules`,
+  Other agents enforce this via `.cursorrules`, `.agents/rules/workflow.md`,
   `.github/copilot-instructions.md`.
 
 **Pre-commit checks:**

package/templates/test/hello/hello.test.ts

@@ -6,7 +6,8 @@
  */
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { html, renderToString } from '@webjsdev/core';
+import { html } from '@webjsdev/core';
+import { renderToString } from '@webjsdev/core/server';
 
 test('html template renders correctly', async () => {
   const result = await renderToString(html`<p>Hello, ${'world'}!</p>`);

package/templates/.windsurfrules

@@ -1,91 +0,0 @@
-# Windsurf Rules - webjs app
-
-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**.
-
-## Persistence + scaffold rules (non-negotiable)
-
-- **Use Prisma + SQLite for data, never JSON files.** It's already wired up
-  (`prisma/schema.prisma`, `lib/prisma.server.ts`, `npm run db:migrate`). For ANY
-  data the app stores (todos, posts, messages, products, comments…),
-  define a Prisma model. NEVER create `data/*.json`, `db.json`, or any
-  JSON file as a fake database. NEVER use module-scope arrays / Maps as
-  a substitute. NEVER use localStorage for app data. `webjs check`'s
-  `no-json-data-files` rule will fail the build if you do.
-- **The scaffold is reference, not the final product.** Replace
-  `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.
-- **Only three templates exist:** `webjs create <name>` (default
-  full-stack), `--template api`, `--template saas`. The CLI rejects any
-  other `--template` value. Pick:
-  - Any product UI (todo, blog, dashboard, marketplace, social…) → default
-  - HTTP/JSON API only, no UI → `--template api`
-  - Auth / login / signup / SaaS → `--template saas`
-
-## Before starting ANY work
-
-FIRST, before writing any code:
-1. Check `git branch --show-current`.
-   - If on main/master: create a feature branch before editing.
-   - If on a feature branch: verify it matches the current task.
-2. Sync: `git fetch origin && git rebase origin/main` if behind.
-
-## Autonomous mode (sandbox / no-prompt)
-
-If running without interactive approval, auto-decide:
-- On main? Auto-create feature/<task-slug> branch
-- Parent behind? Auto-rebase. Merge? Auto-merge + delete feature branches.
-- Auto-generate commit messages. Fix failing tests and violations.
-Quality bar stays the same - no blocking on questions.
-
-## Mandatory workflow (never skip)
-
-Every code change must include:
-1. Server tests in test/<feature>/*.test.ts (node:test)
-2. Browser tests in test/<feature>/browser/*.test.js (WTR + Playwright, real Chromium)
-3. Documentation updates (AGENTS.md, docs/, website/ if they exist)
-4. Convention check: `webjs check` must pass
-
-The user should never have to ask for tests or documentation.
-
-## Git rules
-
-- COMMIT AND PUSH PER LOGICAL UNIT, NOT AT THE END. One feature, one fix,
-  one rename, one doc rewrite per commit. Always `git push` after
-  committing. This is automatic.
-- HARD LIMIT: if you have 5+ unstaged files spanning different concerns,
-  commit before continuing. The Claude Code hook at
-  `.claude/hooks/nudge-uncommitted.sh` fires at threshold 4. Windsurf
-  users should self-enforce the same rule. Batching multiple logical units
-  into one commit is the failure mode this rule exists to prevent.
-- Meaningful commit messages: what changed and why
-- NEVER add Co-Authored-By or AI attribution trailers to commits
-- NEVER use em-dashes (U+2014), a hyphen-as-pause (` - `), or a
-  semicolon-as-pause (` ; `) in commit messages or anywhere else.
-  Rewrite the sentence so no pause-punctuation crutch is needed.
-  Use a period, comma, colon, parentheses, or a restructured phrasing.
-  Plain hyphens stay fine in compound words, CLI flags, filenames,
-  and ranges. Semicolons stay fine inside code
-- Work on feature branches, never push directly to main
-- Create pull requests for review
-- NEVER merge any branch without explicit user permission. Always ask:
-  "Ready to merge <branch> into <target>? Delete or keep <branch> after?"
-  Wait for approval AND the delete/keep preference. Applies to ALL merges.
-- Run `webjs test` before every commit
-
-## Framework specifics
-
-- No build step: ES modules served directly
-- **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 falls back to esbuild + inline sourcemap for those files (~3x wire bytes per request).
-- Web components render into light DOM by default (so Tailwind / global CSS apply directly). Opt in to shadow DOM per component with `static shadow = true` when you need scoped styles (via `static styles = css\`...\``) or third-party-embed isolation. `<slot>` projection works identically in both modes (named slots, fallback content, `assignedNodes` / `slotchange`, first-wins resolution).
-- 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)
-- 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.
-- Directives are deliberately minimal: only `unsafeHTML`, `live`, and `repeat` ship. Use plain template-literal expressions (`class=${active ? 'btn active' : 'btn'}`, `style=${'color:' + color}`, `${cond ? a : b}`) and lifecycle hooks (`this.query('#el')` in `firstUpdated`) instead of Lit's `classMap` / `styleMap` / `ref` / `when` / `choose` / `guard`.
-- Use Context for cross-component data, Task for async data in components
-- **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()`, not `connectedCallback` - the server doesn't call lifecycle hooks). Initial data for components comes from the page function (server-side fetch + pass as attribute/property), NOT from `fetch` calls in `connectedCallback`. For write-paths, prefer `<form action=...>` + server action over `fetch` + click handler - the framework upgrades plain forms to partial-swap submissions automatically.
-- **Client navigation is auto-magic.** Real `<a href>` and `<form action>` get partial-swap behavior with no opt-in. Layouts persist across navigation - put shared chrome (sidenav, header) in `layout.ts`, 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.
-- Full API reference in AGENTS.md