@webjsdev/cli 0.10.53 → 0.10.54

package/README.md

@@ -68,8 +68,8 @@ 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`, `.agents/rules/workflow.md` (Antigravity), `.github/copilot-instructions.md`
+- `AGENTS.md` + `CONVENTIONS.md` + `.agents/skills/webjs/` (single cross-agent source of truth)
+- `.agents/rules/workflow.md` & `.claude/` protective hooks
 - `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

@@ -9,6 +9,7 @@ import { checkNodeInline, nodeInlineMessage } from '../lib/node-preflight.js';
 import { loadAppEnv, resolvePort } from '../lib/port.js';
 import { planDevSupervisor } from '../lib/dev-supervisor.js';
 import { checkAppName, appNameErrorMessage } from '../lib/app-name.js';
+import { findCheckTarget, notAnAppMessage, notAnAppJson } from '../lib/check-target.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const [cmd, ...rest] = process.argv.slice(2);
@@ -722,6 +723,22 @@ async function main() {
         break;
       }
 
+      // #1301: `webjs check` is an APP-level tool. At a workspace root it
+      // walks every package's tests and every app at once and reports
+      // cross-app collisions that no single runtime ever sees (67 false
+      // findings at this repo's root). Refuse instead, naming the member
+      // apps to run it in. Exit 1: an agent gates on the exit status, and
+      // 0 would read as "clean", the exact false signal this fixes.
+      const target = await findCheckTarget(process.cwd());
+      if (!target.isApp) {
+        if (rest.includes('--json')) {
+          console.log(JSON.stringify(notAnAppJson(process.cwd(), target.workspaceApps)));
+        } else {
+          console.error(notAnAppMessage(process.cwd(), target.workspaceApps));
+        }
+        process.exit(1);
+      }
+
       const violations = await checkConventions(process.cwd());
 
       // --json emits the raw structured violations + a summary count as JSON,

package/lib/check-target.js

@@ -0,0 +1,145 @@
+/**
+ * `webjs check` invocation-target guard (#1301).
+ *
+ * `webjs check` is an APP-level tool: every rule assumes one application,
+ * meaning one module graph, one custom-element registry, one runtime. Run at a
+ * workspace root it walks whatever JS/TS happens to live under that path (two
+ * apps, every package's test suite, editor fixtures, the scaffold templates)
+ * and reports collisions no single runtime ever sees. At this repo's root that
+ * was 67 findings, all false.
+ *
+ * The predicate is the presence of an `app/` directory, nothing else. That is
+ * the same test `check.js` already applies per-rule, `app/` cannot be renamed
+ * (AGENTS.md "App layout"), and BOTH scaffold templates create it. Next.js
+ * refuses on the identical predicate in
+ * `packages/next/src/lib/find-pages-dir.ts`. A `workspaces` key is NOT part of
+ * the predicate (a directory with no `app/` is not an app either way); it only
+ * enriches the MESSAGE with the member apps to run instead.
+ *
+ * PURE apart from directory reads: it never prints and never exits. The bin
+ * owns rendering and the exit code.
+ *
+ * @module check-target
+ */
+
+import { statSync } from 'node:fs';
+import { readFile, glob } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * @typedef {{ isApp: boolean, workspaceApps: string[] }} CheckTarget
+ */
+
+/**
+ * Whether `dir` holds an `app/` DIRECTORY. A plain file named `app` is not one,
+ * and `existsSync` alone would call it one, so the type is checked. A broken
+ * symlink or an unreadable parent throws out of `statSync` rather than
+ * returning false, so it is caught: an unreadable path is not an app either.
+ *
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function hasAppDir(dir) {
+  try {
+    return statSync(join(dir, 'app')).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Classify `cwd` as a checkable app or not, and (when it declares npm
+ * workspaces) list the member directories that ARE apps, sorted, as
+ * cwd-relative POSIX paths.
+ *
+ * @param {string} cwd
+ * @returns {Promise<CheckTarget>}
+ */
+export async function findCheckTarget(cwd) {
+  if (hasAppDir(cwd)) return { isApp: true, workspaceApps: [] };
+  return { isApp: false, workspaceApps: await workspaceApps(cwd) };
+}
+
+/**
+ * Expand `package.json` `workspaces` (the array form and yarn's
+ * `{ packages: [...] }` form) and keep the members that have an `app/`
+ * directory. Any read / parse failure yields an empty list: the message
+ * degrades to the generic form and the refusal still stands.
+ *
+ * @param {string} cwd
+ * @returns {Promise<string[]>}
+ */
+async function workspaceApps(cwd) {
+  let patterns;
+  try {
+    const pkg = JSON.parse(await readFile(join(cwd, 'package.json'), 'utf8'));
+    const ws = pkg.workspaces;
+    patterns = Array.isArray(ws) ? ws : Array.isArray(ws?.packages) ? ws.packages : null;
+  } catch {
+    return [];
+  }
+  if (!patterns) return [];
+  /** @type {Set<string>} */
+  const apps = new Set();
+  for (const pattern of patterns) {
+    if (typeof pattern !== 'string') continue;
+    try {
+      for await (const match of glob(pattern, { cwd })) {
+        // `glob` yields whatever matched, files included, so the app test is
+        // what filters a stray same-named file out too.
+        if (hasAppDir(join(cwd, match))) apps.add(match.split('\\').join('/'));
+      }
+    } catch {
+      // A malformed pattern drops out of the listing, never out of the refusal.
+    }
+  }
+  return [...apps].sort();
+}
+
+/**
+ * The human refusal, for stderr.
+ *
+ * @param {string} cwd
+ * @param {string[]} apps
+ * @returns {string}
+ */
+export function notAnAppMessage(cwd, apps) {
+  const lines = [
+    'webjs check: this directory is not a WebJs app, so nothing was checked.',
+    '',
+    `  ${cwd}`,
+    '',
+    'There is no `app/` directory here. Every check assumes ONE application',
+    '(one module graph, one custom-element registry, one runtime), so running',
+    'them over a workspace root reports collisions no single runtime ever sees.',
+    '',
+  ];
+  if (apps.length) {
+    lines.push('This is a workspace root. Run the check inside each app:', '');
+    for (const app of apps) lines.push(`  ( cd ${app} && npx webjs check )`);
+  } else {
+    lines.push('Change into your app directory (the one holding `app/`) and re-run.');
+  }
+  lines.push('', '`webjs check --rules` lists the rules and works from anywhere.');
+  return lines.join('\n');
+}
+
+/**
+ * The `--json` refusal. It carries NO `violations` key on purpose: a consumer
+ * that ignores the exit code and reads `report.violations.length` must throw
+ * rather than be told the workspace is clean.
+ *
+ * @param {string} cwd
+ * @param {string[]} apps
+ * @returns {{ error: { code: string, message: string, cwd: string, apps: string[] } }}
+ */
+export function notAnAppJson(cwd, apps) {
+  return {
+    error: {
+      code: 'NOT_AN_APP',
+      message: 'No `app/` directory here, so webjs check has no application to check.',
+      cwd,
+      apps,
+    },
+  };
+}

package/lib/create.js

@@ -12,13 +12,14 @@
  */
 
 import { mkdir, writeFile, readFile, cp } from 'node:fs/promises';
-import { join, resolve, dirname } from 'node:path';
+import { join, resolve, dirname, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { spawnSync } from 'node:child_process';
 import { bunifyProse, bunifyDockerfile, bunifyCompose, bunifyCi } from './runtime-rewrite.js';
 import { assertValidAppName, toDatabaseName } from './app-name.js';
+import { isGalleryAppShellFile } from './gallery-shell-files.js';
 
 /**
  * Detect which package manager invoked us. Reads `npm_config_user_agent`,
@@ -116,13 +117,20 @@ const UI_REGISTRY_ROOT = resolveUiRegistryRoot();
  * Ships verbatim (no `{{APP_NAME}}` substitution): the examples are self-
  * contained and reference only `@webjsdev/*`, drizzle, `#db/*`, and each other.
  * The scaffold's own `app/page.ts` / `app/layout.ts` are written AFTER this and
- * the gallery ships neither, so there is no clobber. `cp` merges into existing
- * `app/` and `modules/` dirs rather than replacing them.
+ * are filtered out of the copy here (see GALLERY_APP_SHELL_FILES), so there is
+ * no clobber. `cp` merges into existing `app/` and `modules/` dirs rather than
+ * replacing them.
+ *
+ * The source is the canonical repo-root `gallery/` app in monorepo dev, and the
+ * `templates/gallery/` copy `prepack` bundles into the tarball when installed
+ * from npm. Both are filtered identically, so the two modes emit the same app.
  *
  * @param {string} appDir
  */
 async function copyGallery(appDir) {
-  const galleryDir = join(TEMPLATES, 'gallery');
+  const bundledGallery = join(TEMPLATES, 'gallery');
+  const repoRootGallery = resolve(__dirname, '..', '..', '..', 'gallery');
+  const galleryDir = existsSync(bundledGallery) ? bundledGallery : repoRootGallery;
   // `test` carries the auth card's real request-pipeline test (test/auth); it
   // ships with the gallery and is pruned by gallery:clear alongside the card.
   // `components` carries the gallery's EXAMPLE design system (components/ui/ class
@@ -135,7 +143,15 @@ async function copyGallery(appDir) {
   // the ui bootstrap's cn.ts/dom.ts (written earlier); gallery:clear removes just
   // ui.ts. cp is recursive-merge, so the pre-written lib/utils/ files are kept.
   for (const sub of ['app', 'modules', 'test', 'components', 'lib']) {
-    await cp(join(galleryDir, sub), join(appDir, sub), { recursive: true });
+    const srcSub = join(galleryDir, sub);
+    if (!existsSync(srcSub)) continue;
+    await cp(srcSub, join(appDir, sub), {
+      recursive: true,
+      // Skip the gallery's own app shell (root layout, home page, theme toggle,
+      // cn.ts). Those exist because gallery/ is a live app; the scaffold writes
+      // its own, with the app's displayName and the ui-registry cn.ts.
+      filter: (src) => !isGalleryAppShellFile(relative(galleryDir, src)),
+    });
   }
 }
 
@@ -568,26 +584,12 @@ export async function scaffoldApp(name, cwd, opts = {}) {
   // --- Templates (AGENTS.md, CONVENTIONS.md, CLAUDE.md, test files, Claude hooks) ---
 
   const templateFiles = [
-    // Single cross-agent source: a thin AGENTS.md points at the skill; the
+    // Single cross-agent source: AGENTS.md points at .agents/skills/webjs/; the
     // .agents/rules workflow rules and the Claude enforcement hooks back it up.
     'AGENTS.md',
     'CONVENTIONS.md',
     '.agents/rules/workflow.md',
-    // Per-agent files. Content is single-source (AGENTS.md + the skill); these
-    // are thin bridges plus each tool's own config and commit-nudge hook. Claude
-    // Code (CLAUDE.md @-imports AGENTS.md), Gemini CLI (GEMINI.md), Copilot in VS
-    // Code (copilot-instructions.md). Cursor / opencode / Antigravity read
-    // AGENTS.md natively; Cursor also gets a .cursorrules bridge, and each of
-    // Cursor / Gemini / opencode ships a "commit often" nudge hook.
     'CLAUDE.md',
-    'GEMINI.md',
-    '.github/copilot-instructions.md',
-    '.cursorrules',
-    '.cursor/hooks.json',
-    '.cursor/hooks/nudge-uncommitted.sh',
-    '.gemini/settings.json',
-    '.gemini/hooks/nudge-uncommitted.sh',
-    '.opencode/plugins/nudge-uncommitted.ts',
     // Claude Code config + the protective enforcement hooks (no design ceremony).
     '.claude.json',
     '.claude/settings.json',
@@ -629,7 +631,7 @@ export async function scaffoldApp(name, cwd, opts = {}) {
   // rewrites; the three infra files get their file-specific transform. On Node,
   // every file is copied byte-identical (the map is empty).
   const PROSE_REWRITE = new Set([
-    'AGENTS.md', 'CLAUDE.md', 'CONVENTIONS.md', '.cursorrules',
+    'AGENTS.md', 'CLAUDE.md', 'CONVENTIONS.md',
     '.agents/rules/workflow.md',
     'test/hello/browser/hello.test.js', 'test/hello/e2e/hello.test.ts',
   ]);
@@ -1376,13 +1378,16 @@ import { cardClass } from '#components/ui/card.ts';
 import { badgeClass } from '#components/ui/badge.ts';
 // The demo index is defined once in modules/gallery/nav.ts (the same source the
 // left sidebar reads), so the home cards and the sidebar can never drift.
-import { FEATURES, EXAMPLES } from '#modules/gallery/nav.ts';
+import { featureList, EXAMPLES } from '#modules/gallery/nav.ts';
 
 export const metadata = {
   title: '${displayName}',
 };
 
 export default function Home() {
+  // Flattened HERE rather than at module scope. A top-level call is a module
+  // side effect, which would ship this page to the browser for nothing.
+  const FEATURES = featureList();
   return html\`
     <div class="py-8 flex flex-col items-center gap-16">
       <!-- Hero -->

package/lib/doctor.js

@@ -1396,11 +1396,19 @@ function unmarkedStylesheetHref(tag, basePath = '') {
  * Ported rather than imported because that helper is not on `@webjsdev/server`'s
  * public surface, and because doctor must stay usable when the framework does
  * not resolve from the app dir at all (the #954 fresh-worktree case this same
- * command exists to diagnose). `test/cli/doctor.test.mjs` pins the forms.
+ * command exists to diagnose). The port is intentional and stays. What makes it
+ * safe is that the drift is tested rather than trusted.
+ *
+ * `test/cli/base-path-parity.test.mjs` feeds one input table through BOTH this
+ * function and the server's `readBasePath`, asserting they agree with each other
+ * and with the expected value. Change either side without the other and it reds.
+ * So edit this body only alongside `packages/server/src/base-path.js`, and run
+ * that test. (`test/cli/doctor.test.mjs` covers the check that consumes this,
+ * not the normalization forms themselves.)
  * @param {string} appDir
  * @returns {Promise<string>}
  */
-async function readAppBasePath(appDir) {
+export async function readAppBasePath(appDir) {
   let raw;
   try {
     const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));

package/lib/gallery-shell-files.js

@@ -0,0 +1,36 @@
+/**
+ * The files the canonical `gallery/` app owns only because it is a RUNNABLE
+ * WebJs app, and which the scaffold (`webjs create`) generates itself.
+ *
+ * `gallery/` is both the single source of the scaffold's feature gallery AND a
+ * live app deployed on its own, so it needs a root layout, a home page, a theme
+ * toggle, and the `cn()` helper. The scaffold writes all four itself, with
+ * things the gallery's copies cannot carry: the app's `displayName`, the
+ * `cspNonce()` wiring, `LayoutProps` typing, the `metadata.icons` favicon, and
+ * a `cn.ts` read verbatim from the `@webjsdev/ui` registry so `webjs ui add`
+ * stays in lockstep with the kit.
+ *
+ * So they are the ONE part of `gallery/` that is not scaffold payload. They are
+ * dropped from the published bundle (`scripts/sync-scaffold-gallery.mjs`) and
+ * skipped by `copyGallery()` so monorepo-dev and installed-npm scaffolding emit
+ * byte-identical apps. Paths are POSIX-relative to the gallery root.
+ *
+ * @type {readonly string[]}
+ */
+export const GALLERY_APP_SHELL_FILES = Object.freeze([
+  'app/layout.ts',
+  'app/page.ts',
+  'components/theme-toggle.ts',
+  'lib/utils/cn.ts',
+]);
+
+/**
+ * True when `relPath` (POSIX-relative to the gallery root) is a gallery-only
+ * app-shell file rather than scaffold payload.
+ *
+ * @param {string} relPath
+ * @returns {boolean}
+ */
+export function isGalleryAppShellFile(relPath) {
+  return GALLERY_APP_SHELL_FILES.includes(relPath.split('\\').join('/'));
+}

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.53",
+  "version": "0.10.54",
   "type": "module",
   "description": "The CLI for WebJs, a full-stack JavaScript framework built on web components with server-side rendering and no build step. Runs the dev and production servers, scaffolds apps, validates conventions, and drives the database. Node 24+ or Bun.",
   "bin": {
     "webjs": "bin/webjs.js"
   },
   "scripts": {
-    "prepack": "node ../../scripts/sync-scaffold-skill.mjs",
-    "postpack": "node ../../scripts/sync-scaffold-skill.mjs --clean"
+    "prepack": "node ../../scripts/sync-scaffold-skill.mjs && node ../../scripts/sync-scaffold-gallery.mjs",
+    "postpack": "node ../../scripts/sync-scaffold-skill.mjs --clean && node ../../scripts/sync-scaffold-gallery.mjs --clean"
   },
   "files": [
     "bin",

package/templates/.agents/skills/webjs/SKILL.md

@@ -238,7 +238,9 @@ Success is a 303 (PRG); failure re-renders the page at 422 with the result on `a
 - Writing a bare `<form method="post">` and expecting a page `action` export to catch it. There is no such export; bind the action with `action=${fn}` or the submission is a 405.
 - Putting a submitter's `formaction=${fn}` on anything that is not a submit control, or on a button carrying its own `name` / `value`. The identity IS the button's name/value pair, so both halves are spoken for.
 - Writing `formmethod="get"` or `formenctype="text/plain"` on a button that BINDS an action. Neither can carry that action's body, so the pair contradicts itself and throws. On a button that binds nothing it is a legal native override and is honoured.
-- Binding an action whose file declares `export const method = 'GET'`. That is a 405 at runtime and a `webjs check` error.
+- Binding an action whose file declares `export const method = 'GET'`. Form-bound actions strictly require POST (default). Binding a GET action to a form is a 405 at runtime and a `webjs check` error (`form-action-not-a-get-action`).
+- Leaving read-only RPC server query actions as default `POST`. Always export `export const method = 'GET'` for RPC data queries so arguments ride URL params, ETags/304 caching work, and CSRF is safely bypassed.
+- Writing `method="get"` on a bound `<form action=${fn}>`. WebJs supplies `method="post"` and `formenctype` automatically, and a bound form declaring `method="get"` is REFUSED at render (a thrown error, not a warning), because a GET sends no body for the action to read.
 - Throwing `redirect()` / `notFound()` inside a `route.ts` handler (uncaught 500). Return a `Response` there.
 - A placeholder first paint that fetches in `connectedCallback`. SSR does not call `connectedCallback`; put first-paint data in the constructor (server-known inputs) or use `async render()`.
 - A browser global (`window`, `document`, `localStorage`) in the constructor or `render()`. It throws at SSR; do browser-only work in `connectedCallback`.

package/templates/.agents/skills/webjs/references/built-ins.md

@@ -145,7 +145,7 @@ setFileStore(diskStore({ dir: '/var/data/uploads', baseUrl: '/files' }));
 
 ## The `"webjs"` config block (package.json)
 
-All keys are optional, and a malformed entry in a key the SERVER reads is dropped at boot with a warning, never crashing the pipeline. The one exception is `doctor.gate`, which is read by the `webjs doctor` CLI rather than the server and rejects a bad entry outright (see the doctor severity gate below): a gate whose typo was quietly ignored would leave CI un-gated while looking gated, which is the one thing that mechanism cannot afford.
+All keys are optional, and a malformed entry in a key the SERVER reads is dropped at boot rather than crashing the pipeline, some readers warning as they drop it. `headers` and `redirects` warn on every drop. Both warn for the key itself when it is present but not an array, and for each rule or entry inside it; `headers` has a third level and warns per header directive too. An absent key is the default and says nothing. An UNKNOWN top-level key no longer passes in silence either (#1300): the block is validated against the published JSON Schema once per boot, in dev and in prod alike, and one aggregated warning names what was ignored. So a `"redirect"` typed for `"redirects"` now says so in the server output instead of silently leaving the feature at its default. It never fails the boot. Know its exact reach, since what it passes over looks like what it catches. It reports any unknown TOP-LEVEL key, whatever it is called, and it checks the VALUE of 9 of the 17 known keys, being the one `enum` and the `boolean` / `integer` leaves. It does not descend into a nested object, so a misspelling inside `dev` or `start` is not reported, and it does not type-check the other 8 (`headers`, `redirects`, `basePath`, `allowedOrigins`, `csp`, `dev`, `start`, `doctor`), whose schemas are the free-form ones a blunt check would start refusing working configs over. Whether anything else notices a value this check passes over is up to that value's own reader, and it varies by reader. `doctor.gate` varies furthest, since the boot check never descends into any key and the `webjs doctor` CLI, not the server, is what reads this one, rejecting a bad entry outright (see the doctor severity gate below): a gate whose typo was quietly ignored would leave CI un-gated while looking gated, which is the one thing that mechanism cannot afford.
 
 ### Security headers
 

package/templates/.agents/skills/webjs/references/components.md

@@ -135,17 +135,21 @@ The bare form is shorthand: `count: Number` means `prop(Number)`. Use `prop()` t
 |---|---|---|
 | `type` | `String` | Constructor feeding the default attribute converter |
 | `reflect` | `false` | Property changes write back to the HTML attribute (a value with no attribute representation removes it instead, see below) |
-| `state` | `false` | Internal-only. No attribute, not observed |
+| `state` | `false` | Internal-only. No attribute, not observed, and never read from one at SSR either |
 | `attribute` | derived from name | The HTML attribute name the property rides |
 | `default` | none | Declarative initial value (a function runs per instance for a fresh object / array) |
 | `hasChanged` | strict `!==` | Custom change detection |
-| `converter` | type-based | Custom attribute-to-property serialization |
+| `converter` | type-based | Custom attribute-to-property serialization. `fromAttribute` runs on BOTH readers (the client upgrade and SSR), ahead of type coercion |
 
 For an array-typed prop pass `Array`, not `Object` (`array-prop-uses-array-type` flags the `Object` form). For anything the built-in converters cannot parse (Date, Map, Set) supply a `converter`.
 
+**A `converter.fromAttribute` runs SERVER-SIDE too.** Both attribute readers go through one shared implementation, so the converter fires during SSR as well as on the client upgrade, and it wins over the declared `type` on both. So keep it free of browser globals (`document`, `window`, `navigator`), since SSR has no DOM and touching one throws where the same code worked in the browser. A converter that THROWS is not caught by either reader, because an author who writes one owns the conversion: at SSR the throw lands in per-component error isolation (an error box in dev, an empty element at a 200 in production, with the cause in the server log) while sibling components still render, and on the client it escapes `attributeChangedCallback` during upgrade. Both readers hand the converter DECODED attribute text, so a converter that parses its input (`JSON.parse` for a Map or a Set, `new Date(...)`) sees the same string on both sides even when the attribute carries `"` or `&`.
+
 **A `reflect: true` property holding a FUNCTION drops its attribute instead of writing one, and so does one holding an array that carries a function, unless the prop is `Object` or `Array` typed.** A function has no HTML attribute representation, and the serializations it would otherwise get are both useless and dangerous. `String(fn)` is the function's SOURCE, so a reflected `'use server'` action would ship its whole body, closure secrets included, to every visitor, and `JSON.stringify(fn)` is `undefined`, which lands in the attribute as the literal four-character string. So the reflection path treats a function like `null`, removes the attribute, and warns naming the property, the tag, and the attribute. This holds on both sides, since SSR and the client-side setter run the same path, and it holds for every property name (the leak was never specific to one called `action`). Two exceptions. A property with a custom `converter.toAttribute` runs that converter first and is left alone, because an author who writes one has taken responsibility for serializing whatever they are handed. And an `Object` or `Array` typed property CARRYING a function keeps its data, because `JSON.stringify` drops the function to `null` and omits the key, so `[1, 2, fn]` reflects as `[1,2,null]` with no source and nothing else lost. If you need a function on a component, use a plain property or a signal and do not mark it `reflect`.
 
-**An `Object` or `Array` typed reflected property whose value `JSON.stringify` cannot serialize AT ALL drops its attribute the same way, and warns.** Three shapes do this: a cycle (an object or array that reaches itself, which arrives from a parent/child graph, a linked node, a memo table, or anything a library hands back with a back-reference), a `BigInt` anywhere inside the value, and an author `toJSON()` that throws. The line to keep straight is that a value which serializes WITH A GAP in it keeps its data (the carried-function case above), while one that does not serialize at all has no string to put in the attribute and so has no attribute representation, exactly like a function. The property itself is untouched and still holds the value; only the attribute goes. Before this guard the throw escaped reflection entirely, which meant a client upgrade threw before the component's first render, and an SSR render was swallowed by per-component error isolation, which shows an error box in dev and renders the component EMPTY on a page that still returned 200 in production. To reflect something about a graph-shaped value, reflect a derived scalar (an id, a count) and keep the graph on a non-reflected property. On the read side an attribute that is PRESENT but not parseable JSON reads back as `null` rather than as the raw string, on both the SSR and the client reader. An ABSENT attribute is a different case: neither reader sees it, so the property keeps its constructor value.
+**An `Object` or `Array` typed reflected property whose value `JSON.stringify` cannot serialize AT ALL drops its attribute the same way, and warns.** Three shapes do this: a cycle (an object or array that reaches itself, which arrives from a parent/child graph, a linked node, a memo table, or anything a library hands back with a back-reference), a `BigInt` anywhere inside the value, and an author `toJSON()` that throws. The line to keep straight is that a value which serializes WITH A GAP in it keeps its data (the carried-function case above), while one that does not serialize at all has no string to put in the attribute and so has no attribute representation, exactly like a function. The property itself is untouched and still holds the value; only the attribute goes. Before this guard the throw escaped reflection entirely, which meant a client upgrade threw before the component's first render, and an SSR render was swallowed by per-component error isolation, which shows an error box in dev and renders the component EMPTY on a page that still returned 200 in production. To reflect something about a graph-shaped value, reflect a derived scalar (an id, a count) and keep the graph on a non-reflected property. On the read side an attribute that is PRESENT but not parseable JSON reads back as `null` rather than as the raw string, on both the SSR and the client reader. An ABSENT attribute is a different case: neither reader sees it, so the property keeps its constructor value. The two readers also see the same attribute SET, not merely the same fallback: a `state: true` prop, a camelCase attribute name, and an attribute matching no declared property are all ignored by both, and both are handed a value whose HTML character references are already decoded.
+
+**Writing attributes in markup.** Names are case-insensitive and the browser lowercases them while parsing, so write kebab-case (`user-name`); a camelCase attribute (`userName="…"`) reaches no property on either side. A prop that renames its attribute answers to the new name ONLY, so `open: prop(Boolean, { attribute: 'is-open' })` is written `<my-el is-open>` and `<my-el open>` reaches nothing. Character references are decoded before the value is coerced, so `cfg="&#123;&quot;a&quot;:1&#125;"` parses as the object it spells and `label="Tom &amp; Jerry"` is `Tom & Jerry`; the legacy semicolon-less forms decode exactly where a browser decodes them (`&nbsp` at the end of a value is a non-breaking space, `&nbspx` and `&nbsp=x` stay literal), and writing the semicolon avoids the question. A `state: true` prop takes an SSR value only through a `.prop=${value}` binding from the parent template, never from an attribute.
 
 **Never use a class-field declaration OR initializer** (`count = 0`, `student: Student = {...}`, `todos!: Todo[]`). Under `useDefineForClassFields` even a type-only `todos!: Todo[]` compiles to define an own property after `super()`, which clobbers the prototype's reactive accessor and silently breaks reactivity. Only declare props in the factory and read/write them off `this`. The `reactive-props-no-class-field` rule catches this.
 

package/templates/.agents/skills/webjs/references/data-and-actions.md

@@ -146,15 +146,41 @@ Everything the action declares applies here too, or an action would be protected
 - `invalidates` is evicted when the action actually RAN (a middleware short-circuit does not evict), and the evicted tags are reported on the response so the browser's tag coordinator bypasses a stale cached GET. One reach limit: `fetch` follows the success `303` transparently, so JS cannot read a redirect's headers; the tags are on the wire and the `422` re-render carries them, and the redirect's own render is server-side and seeds fresh data.
 - `invalidates` and `tags` receive the SAME first argument the action does, so on a form boundary they receive the `FormData`. `invalidates: (input) => ['post:' + input.id]` returns `post:undefined` for a submission and evicts nothing. Either read the field (`(fd) => ['post:' + fd.get('id')]`), declare a `validate` that transforms the `FormData` into the typed input first (the transform result is what the config functions then see), or use an argument-independent tag.
 - `method = 'GET'` cannot be bound to a form: a GET action rides its args in the url and is CSRF-exempt, so it cannot answer a form POST. That is a `405` at runtime and the `form-action-not-a-get-action` error in `webjs check`.
+- A form whose buttons run DIFFERENT actions binds each on its submitter, `<button formaction=${publishDraft}>`. **The submitter is self-sufficient** (#1307): the renderer gives it `formmethod="post"` and `formenctype` ON THE BUTTON, alongside the identity riding the button's own `name`/`value` pair, and a submitter's `formmethod` overrides the form's `method` per HTML. So a per-button action works inside a bound form, an unbound form, a `method="get"` form, or a form with no method at all, and the enclosing form does not need binding for the button's sake. Bind the form when the FORM itself should run an action on a plain submit. In dev the client logs one `console.error` at submit time for a submission holding an identity it cannot deliver, and in production both server-visible fingerprints reach `onError` with a code (`WEBJS_FORM_SUBMITTED_AS_GET` for an identity in the query string, `WEBJS_FORM_ACTION_MISSING` for a body carrying no identity). See `muscle-memory-gotchas.md` for the shape.
 
 The response drives the page: a success is a `303` PRG (to `result.redirect` when it is a same-site local path, else the page's own url), a failure re-renders the SAME page with `status` (default `422`) and the result on `actionData`, a submission carrying no identity is a `405`, and one whose hash no longer resolves is a `422` with a resubmit message (a form held open across a deploy). The submission is Origin-verified like an RPC call, so no token field is needed.
 
 A streamed return (#489) is refused from a form-bound action: the RPC stub decodes frames, but a submission is answered with a redirect or a page, and with JS off there is no consumer at all. Stream from a programmatic call instead.
 
-## HTTP-verb config exports
+## HTTP-verb config exports & decision guide
 
 A `'use server'` action is a POST by default. Reserved sibling exports, read statically (the same way a page reads `export const revalidate`), change its HTTP semantics WITHOUT changing the call site (you still write `await getUser(7)`).
 
+### HTTP Verbs Decision Guide
+
+| Action Kind | Target Verb | Example Declaration | HTTP Semantics & Features |
+|---|---|---|---|
+| **Form-Bound Action** (`<form action=${fn}>`) | **POST** (default) | *(no export or `export const method = 'POST'`) | Standard HTML form submission. Enforces `POST` + `multipart/form-data` or `urlencoded`. **Never export `method = 'GET'`** (triggers 405 refusal & `webjs check` violation). |
+| **RPC Read Action (Query)** | **GET** | `export const method = 'GET'` | Read-only RPC calls (`await getTodos()`). Args ride URL query params (with POST fallback over 4KB). CSRF-exempt, supports ETags, 304 revalidation, and `export const cache`. |
+| **RPC Write Action (Mutation)** | **POST** / **PUT** / **PATCH** / **DELETE** | Default or `export const method = 'DELETE'` | Data-modifying RPC calls (`await deleteUser(4)`). Carries CSRF protection, serialized payload body, and evicts cached query tags via `export const invalidates`. |
+
+### Choosing the right HTTP verb
+
+1. **Form-Bound Actions (`<form action=${fn}>` / `<button formaction=${fn}>`):**
+   - **MUST be POST.** Leave unannotated (default) or export `export const method = 'POST'`.
+   - **NEVER export `export const method = 'GET'` for form actions.** The HTML renderer automatically emits `method="post"` and `formenctype` for form actions. Binding a `method = 'GET'` action to a form returns a `405 Method Not Allowed` at runtime and triggers a `webjs check` error (`form-action-not-a-get-action`).
+   - **NEVER add `method="get"` to a bound `<form action=${fn}>`.** WebJs manages form submission semantics automatically, and a bound form declaring `method="get"` is REFUSED at render (a thrown error, not a warning), because a GET sends no body for the action to read.
+
+2. **Programmatic / RPC Read Actions (Queries):**
+   - **ALWAYS export `export const method = 'GET'` for read-only queries.**
+   - When an action only fetches data (`await getUser(id)`), exporting `method = 'GET'` instructs the client RPC stub to issue an HTTP GET request with arguments encoded in query parameters.
+   - Enables browser/CDN caching, weak ETags (returning 304 Not Modified on cache hit), and HTTP `Cache-Control` header generation when paired with `export const cache = ...`.
+
+3. **Programmatic / RPC Write Actions (Mutations):**
+   - **Use POST, PUT, PATCH, or DELETE for writes.**
+   - Use default `POST` or explicitly export `PUT`/`PATCH`/`DELETE` for RESTful RPC calls (`await removeUser(id)`).
+   - Pair mutating actions with `export const invalidates = (args...) => ['tag']` to evict cached reads matching those tags upon completion.
+
 ```ts
 // modules/users/queries/get-user.server.ts: a cached, tagged GET read
 'use server';
@@ -165,8 +191,9 @@ export async function getUser(id: number) { return db.query.users.findFirst({ wh
 ```
 
 ```ts
-// a mutation evicts the tags it touches
+// modules/users/actions/update-user.server.ts: a mutation evicting matching tags
 'use server';
+export const method = 'PATCH';                     // explicit verb
 export const invalidates = (id: number) => ['user:' + id];
 export const middleware = [requireAuth];           // async (ctx, next) => result; read ctx via actionContext()
 export async function updateUser(id: number, patch: Partial<User>) { /* ... */ }

package/templates/.agents/skills/webjs/references/muscle-memory-gotchas.md

@@ -110,6 +110,7 @@ The bound, refused, and allowed shapes in full. Every "no" row is a binding that
 | `action=${fn}` on any other tag | yes | `action` submits nothing off a `<form>`, so it is an ordinary attribute and the function would be stringified |
 | `action="${fn}"`, or a mixed `action="/x/${fn}"` | yes | quoting turns a binding hole back into a plain attribute |
 | `formaction=${fn}` unquoted, on a submitter, ANYWHERE | **no, it BINDS** | the second supported shape (#1207, #1307). A bound submitter carries its WHOLE submission: the identity rides the button's own `name`/`value` pair, the one channel a browser submits for the pressed button alone, and the renderer adds `formmethod="post"` and `formenctype="multipart/form-data"` to the button itself. So it works inside a bound form, an unbound form, a `method="get"` form, or a form with no method at all, and it asks NOTHING of the element around it. No `formaction` url is emitted, and the server takes the LAST `__webjs_action` entry |
+
 | `formaction=${fn}` on a submitter carrying its own `name` or `value` | yes | the identity IS that name/value pair, so both halves are already spoken for. Bind one action on the form and dispatch on `name="intent"` if you need the button's own value |
 | `formaction=${fn}` on a non-submit control, or `<input type="image">` | yes | `formaction` is inert on anything that does not submit, and an image submitter sends `name.x` / `name.y` coordinates instead of `name=value`, so the identity would never arrive |
 | `formaction=${fn}` on a submitter with `form="other"` | yes | it re-points the submitter at a different form owner, which may not be where the identity field it needs lives |
@@ -118,6 +119,8 @@ The bound, refused, and allowed shapes in full. Every "no" row is a binding that
 | `formmethod="dialog"` on a submitter that binds nothing | **no** | a native `<dialog>` dismissal, never a submission, so there is no body for the action to miss. It IS refused on a button that also binds an action, which is a straight contradiction |
 | a plain `formaction="/url"` on a submitter inside a bound form | **no** | it retargets the submission away from the page's bound action entirely, so where it goes and how is your business |
 | `.action=` on a native form | yes | the supported binding is the plain attribute, and a `.prop` on a native element drops at SSR, so accepting it would mean a form that submits under JS and does nothing without it |
+| `export const method = 'GET'` on a form-bound action file | yes | form-bound actions strictly enforce `POST`. Binding a GET action to a form produces a 405 runtime refusal and `webjs check` error (`form-action-not-a-get-action`) |
+| `method="get"` on a bound `<form action=${fn}>` | yes | WebJs supplies `method="post"` and `formenctype` automatically, and a bound form declaring `method="get"` is REFUSED at render (a thrown error, not a warning), because a GET sends no body for the action to read |
 | `.method=` / `.enctype=` / `.encoding=` on a BOUND form | yes | the same reason one level over. All three are reflected IDL attributes, so SSR drops the binding and emits `method="post"` while a browser ends at what you assigned. Write them as plain attributes |
 | a second `action=${fn}` on one form | yes | SSR emits the second as a plain url next to the identity field, the client takes the last. Bind exactly one, in either position |
 | a plain `action="/url"` beside the bound hole | yes | the hole drops only its OWN attribute, so SSR keeps the static one while the client removes it: without JS the browser posts to `/url`, with JS to the page |
@@ -134,6 +137,27 @@ That last row is the one to remember: quoting a binding hole turns it back into
 
 `.action=${fn}` on a native form is refused during SSR too, even though the property is dropped there and nothing could leak, so a page cannot render clean on the server and then throw on hydration.
 
+**A bound submitter is self-sufficient and asks nothing of the form around it.** This is the shape people expect to have to wire up, and do not:
+
+```ts
+// components/publish-button.ts   <- the submitter lives here
+class PublishButton extends WebComponent({}) {
+  render() { return html`<button formaction=${publishDraft}>Publish</button>`; }
+}
+PublishButton.register('publish-button');
+
+// app/triage/page.ts             <- the form lives here
+// BOTH work. The button carries its own submission attributes.
+html`<form><publish-button></publish-button></form>`;
+html`<form action=${saveAll}><publish-button></publish-button></form>`;
+```
+
+The renderer supplies the submission attributes at the level where the action is BOUND (#1307), so a bound `<button>` gains `formmethod="post"` and `formenctype` ON THE BUTTON, alongside the reserved `__webjs_action` identity riding the button's own `name`/`value` pair. A submitter's `formmethod` overrides the form's `method` per HTML, so the submission is a POST whatever the enclosing form declares, including no `method` at all or `method="get"`, and the identity travels in the body where the dispatcher reads it.
+
+That is also why the renderer refuses only a SAME-ELEMENT contradiction (a bound submitter's own `formmethod` other than post, an `formenctype` the server cannot parse, `formmethod="dialog"`) and never a cross-element one. A component renders its template in a separate pass with no view of the host page, so the cross-element question is unanswerable at render time, and self-sufficiency leaves nothing for it to answer. One consequence: no `formaction` url is emitted, so the submission targets whatever the FORM targets, and a form declaring `action="/x"` sends its buttons there. The action still runs when `/x` is a PAGE route, since the identity travels in the body; against a `route.ts` or another origin nothing runs, which the dev-time client guard reports at submit time.
+
+**Two runtime signals cover what is left.** In dev, submitting a form that carries an action identity it cannot deliver logs one `console.error` naming the fix, once per shape; it never throws, so the submission behaves exactly as it does in production. In production, both server-visible fingerprints reach the `onError` hook (the programmatic `createRequestHandler({ onError })` option and any sink an `instrumentation.{js,ts}` installed) with a code to group on: `WEBJS_FORM_SUBMITTED_AS_GET` for a page GET carrying the reserved field in its query string, and `WEBJS_FORM_ACTION_MISSING` for a form body carrying no identity at all. A BOUND submitter carries its own `formmethod="post"`, and a bound form is refused a `method="get"` outright, so what reaches the first one is a PLAIN submitter's `formmethod="get"`, which native precedence lets win and the renderer deliberately honours, or a hand-authored form carrying the reserved field. Both are detect-only, so no status changes, and both carry the submitted field NAMES and never the values.
+
 **Inside a component you may never see the error.** Per-component SSR error isolation contains the throw, so development shows an error box in place of the component and production renders it empty with the page still returning 200. A form that has silently vanished in production is this bug wearing a disguise; the message is in the server log. Nothing leaks either way.
 
 Two things that "renders it empty" understates, both worth knowing before you go looking:

package/templates/.agents/skills/webjs/references/routing-and-pages.md

@@ -192,7 +192,28 @@ Refusals worth knowing: `formaction=${fn}` is supported on a `<button>` anywhere
 
 Metadata routes (`sitemap.ts`, `robots.ts`, `manifest.ts`, `icon.ts`, `apple-icon.ts`, `opengraph-image.ts`, `twitter-image.ts`) live at app root or static segments and default-export a possibly-async function; `sitemap()` / `sitemapIndex()` from `@webjsdev/server` serialize spec-valid XML.
 
-The IMAGE metadata routes (`icon`, `apple-icon`, `opengraph-image`, `twitter-image`) default-export a function returning a `Response` with an explicit `content-type`, so an inline SVG needs no asset file (buildless). Then point `metadata` at the route via `openGraph.images` / `twitter.images` / `icons` (or drop a static file in `public/` instead).
+The IMAGE metadata routes (`icon`, `apple-icon`, `opengraph-image`, `twitter-image`) default-export a function returning a `Response` with an explicit `content-type`, so an inline SVG needs no asset file (buildless).
+
+**`icon` and `apple-icon` are LINKED for you.** An app that declares no `metadata.icons` gets `<link rel="icon" href="/icon">` and `<link rel="apple-touch-icon" href="/apple-icon">` in the head automatically, for whichever of the two routes it defines (base-path prefixed, since that is where the route answers). No `type` or `sizes` is asserted, because the route picks its content type at request time and the browser sniffs the served one.
+
+Declaring `metadata.icons` **suppresses** the routes rather than merging with them, which is what Next does with its static icon files. So an app that outgrows a placeholder `app/icon.ts` names its real icons and the route stops being linked without having to be deleted:
+
+```ts
+// app/layout.ts  ->  these win; /icon and /apple-icon are no longer linked
+export const metadata = {
+  icons: {
+    icon: [
+      { url: '/public/favicon-192.png', type: 'image/png', sizes: '192x192' },
+      { url: '/public/favicon.svg', type: 'image/svg+xml', sizes: 'any' },
+    ],
+    apple: { url: '/public/apple-touch-icon.png', sizes: '180x180' },
+  },
+};
+```
+
+Declare a favicon through `metadata.icons` (or a metadata route), never as a hand-written `<link rel="icon">`: only the root layout may write a shell at all (invariant 8), so a hand-written tag is unavailable to every other layout. A `public/favicon.ico` needs no declaration either way, since the framework serves it at the origin root for crawlers that read no markup.
+
+`opengraph-image` and `twitter-image` are NOT auto-linked (a preview image is a per-page editorial choice, not a site-wide default). Point `metadata` at those via `openGraph.images` / `twitter.images`.
 
 ```ts
 // app/opengraph-image.ts  (OG is 1200x630; apple-icon 180x180)

package/templates/.agents/skills/webjs/references/styling.md

@@ -109,6 +109,19 @@ The default stack is a static compiled Tailwind stylesheet (`css:build` compiles
 
 **Two halves.** (1) `public/input.css` MAPS token names into Tailwind with `@theme inline` (`--color-background: var(--background)`), so `bg-background` resolves to `var(--background)`. That is infrastructure; leave it. (2) The root layout (`app/layout.ts`) DEFINES the values as plain CSS custom properties in a `<style>` block. That is your palette; make it your own. A freshly cleared app (after `npm run gallery:clear`) ships only the OS system-colour base (`Canvas` / `CanvasText`) with NO tokens, so building this palette is your first styling step.
 
+**`@theme` and `@theme inline` differ in whether the token reaches `:root`, and the difference is silent.** Measured on `tailwindcss@4.3.0`, a token mapped in a theme block is emitted as a real `:root` custom property when:
+
+| block | token used only through a utility (`border-border`) | token written as a raw `var(--color-x)` in any SCANNED file | token unused |
+|---|---|---|---|
+| `@theme` | emitted | emitted | not emitted |
+| `@theme inline` | NOT emitted (the value is substituted into the utility) | emitted | not emitted |
+
+The one cell that bites is `inline` plus utility-only usage. Nothing on the page can then inherit `--color-x`, so a raw `var(--color-x)` written somewhere Tailwind never scanned resolves to nothing and the declaration falls back to its initial value (a border or outline silently becomes `currentColor`).
+
+"Scanned" is wider than it looks, and this is the part worth knowing: Tailwind scans source files as raw text, so a `var(--color-ring)` inside a component's `static styles` template DOES count and forces emission, exactly like one in the stylesheet. That is why the `@webjsdev/ui` kit theme works despite using `inline`. So the rule is not "shadow components need a plain `@theme`". It is: **if a token is only ever used through utilities, and something outside the scanned source needs to inherit it, map that token with a plain `@theme`.** Anything under a configured `@source` is scanned and needs no special handling.
+
+Whichever form you use, a token nothing references is dropped in both, so an unused mapping is dead configuration rather than a safety net.
+
 **Light and dark, defined once (DRY).** Write each colour token ONE time with the native CSS `light-dark(LIGHT, DARK)` function and let `color-scheme` pick the side. The default `color-scheme: light dark` follows the OS; a `[data-theme]` attribute forces one. No duplicated light/dark blocks:
 
 ```html

package/templates/.agents/skills/webjs/references/ui-kit.md

@@ -72,5 +72,20 @@ dropdown-menu, hover-card, sonner, tabs, tooltip, plus toggle and toggle-group
   the tokens are missing (re-run `npx webjsdev ui init` or let `add` self-heal them).
 - Custom elements are display-only-safe at SSR and hydrate in the browser, the
   standard WebJs component model (`references/components.md`).
+- A registry module should do no work at module scope, because the elision
+  analyser reads a module-scope call or a `document` reference as client work
+  and then the page that imports it ships whole (#1320). `cn` itself is clean,
+  so importing it never pins a page. Six modules still trip the analyser and DO
+  pin an importing page: `checkbox`, `radio-group`, `pagination`, `progress`,
+  `sonner`, `tabs`. The first two inject a stylesheet for real; the other four
+  are an analyser precision gap (an arrow with an expression body puts its call
+  at brace depth 0). Either way the page ships, so treat the list as fact rather
+  than as a technicality. Keep your own copies clean when you edit them, and run
+  `npx webjsdev elision`, which names the blocker whenever a page ships.
+- `native-select`'s `<option>` colours ride the design tokens, not the module.
+  An app with no theme block gets the browser default `<option>` colours along
+  with everything else unstyled, fixed the same way (re-run `init`, or let `add`
+  plant the block). An app whose block predates the rule keeps the default until
+  the rule is added by hand, because `init` never rewrites an existing block.
 
 Full per-package reference lives in the installed `@webjsdev/ui/AGENTS.md`.

package/templates/gallery/app/icon.ts

@@ -1,9 +1,14 @@
-// app/icon.ts serves /icon (the dynamic favicon). The default export is a
+// app/icon.ts serves /icon (a dynamic favicon). The default export is a
 // (possibly async) server function; returning a Response lets you set the exact
-// content type, so an inline SVG needs no asset file. For a favicon that never
-// changes, put a static file in public/ instead (e.g. public/favicon.ico) and
-// delete this route. Generate it dynamically (per-theme, per-tenant) when the
-// mark must be computed at request time.
+// content type, so an inline SVG needs no asset file. Generate it dynamically
+// (per-theme, per-tenant) when the mark must be computed at request time.
+//
+// This is the DEMO of that surface, not the gallery's own favicon. A metadata
+// route is not auto-linked: the framework emits `<link rel="icon">` only from
+// metadata.icons, so the gallery declares the static WebJs brand mark from
+// public/ there (see app/layout.ts) and this route stays browsable at /icon.
+// For a favicon that never changes, that static path is the one to copy; drop
+// this route when your app has no request-time mark to compute.
 export default function Icon() {
   const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32">
     <rect width="32" height="32" rx="7" fill="#1e2226"/>

package/templates/gallery/modules/gallery/nav.ts

@@ -63,7 +63,7 @@ export const FEATURE_GROUPS: NavGroup[] = [
     items: [
       { href: '/features/caching', title: 'Caching', blurb: 'export const revalidate caches the page HTML per URL, with the safety rule for when a shared cache is allowed.' },
       { href: '/features/env', title: 'Env vars', blurb: 'The server-only vs WEBJS_PUBLIC_ boundary, read during SSR so secrets never reach the browser.' },
-      { href: '/features/rate-limit', title: 'Rate limiting', blurb: 'The rateLimit() middleware scoped to one endpoint, returning a 429 with Retry-After past the window.' },
+      { href: '/features/rate-limit', title: 'Rate limiting', blurb: 'The rateLimit() middleware scoped to one endpoint, returning a 429 with Retry-After once the interval resets.' },
       { href: '/features/file-storage', title: 'File storage', blurb: 'A no-JS multipart upload streamed into the FileStore, then served back through a streaming route.' },
       { href: '/features/service-worker', title: 'Service worker', blurb: 'The opt-in offline enhancement, registered from a browser-only lifecycle hook (never a page or layout).' },
     ],
@@ -75,5 +75,14 @@ export const EXAMPLES: NavItem[] = [
   { href: '/examples/todo', title: 'Optimistic todo', blurb: 'A whole app composing several features: the declarative optimistic() list API, progressive-enhancement forms, accessible labels, the modules split, and SQLite.' },
 ];
 
-/** Flattened single-feature list (for the home card grid). */
-export const FEATURES: NavItem[] = FEATURE_GROUPS.flatMap((g) => g.items);
+/**
+ * Flattened single-feature list (for the home card grid).
+ *
+ * This is a function, not a `const` initialised by a top-level `.flatMap()`
+ * call. A top-level call is a module side effect, so the const form pinned
+ * every page importing this module into the browser bundle, even a home page
+ * with no client behaviour at all. Call it inside the render function.
+ */
+export function featureList(): NavItem[] {
+  return FEATURE_GROUPS.flatMap((g) => g.items);
+}

package/templates/gallery/modules/todo/actions/submit-todo.server.ts

@@ -21,6 +21,13 @@ import { deleteTodo } from './delete-todo.server.ts';
 // control's visible label), and a bound submitter cannot carry its own
 // `name`/`value`, which is exactly the channel `name="intent"` uses below.
 //
+// Third thing to know: no `formaction` url is emitted, because the identity
+// travels in the body instead. So the submission targets whatever the FORM
+// targets, and a form declaring `action="/x"` sends its buttons there. The
+// action still runs when `/x` is a PAGE route; against a `route.ts` or another
+// origin the identity is ignored and nothing runs, which the dev-time client
+// guard reports at submit time.
+//
 // With JS the component intercepts the submit and calls the underlying action
 // directly for the optimistic path, so this runs only with JS off.
 export async function submitTodo(formData: FormData) {

package/templates/.cursor/hooks/nudge-uncommitted.sh

@@ -1,38 +0,0 @@
-#!/bin/bash
-#
-# Cursor afterFileEdit hook.
-#
-# Counterpart of .claude/hooks/nudge-uncommitted.sh. After each
-# file edit, counts uncommitted changes in the working tree.
-# When the count crosses a threshold (default 4, override with
-# WEBJS_COMMIT_NUDGE_THRESHOLD), injects a reminder via the
-# top-level additional_context field (snake_case, unlike Claude
-# Code's nested hookSpecificOutput.additionalContext).
-#
-# Soft nudge. Exit 0 always. Skipped on main/master and outside
-# a git work tree.
-
-set -e
-
-THRESHOLD="${WEBJS_COMMIT_NUDGE_THRESHOLD:-4}"
-
-if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
-  exit 0
-fi
-
-BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null || echo "")
-if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
-  exit 0
-fi
-
-cat /dev/stdin >/dev/null 2>&1 || true
-
-CHANGED=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
-
-if [ -z "$CHANGED" ] || [ "$CHANGED" -lt "$THRESHOLD" ]; then
-  exit 0
-fi
-
-REASON="You have ${CHANGED} uncommitted changes on '${BRANCH}'. The webjs convention is small, focused commits per logical unit (one feature, one fix, one rename, one doc rewrite). Before continuing with more edits, group the current changes into a meaningful commit. See AGENTS.md \"Git workflow\" for the rule and the rationale. To raise the threshold for this hook in long-running tasks, set WEBJS_COMMIT_NUDGE_THRESHOLD."
-
-jq -n --arg ctx "$REASON" '{ additional_context: $ctx }'

package/templates/.cursor/hooks.json

@@ -1,8 +0,0 @@
-{
-  "version": 1,
-  "hooks": {
-    "afterFileEdit": [
-      { "command": ".cursor/hooks/nudge-uncommitted.sh" }
-    ]
-  }
-}

package/templates/.cursorrules

@@ -1,21 +0,0 @@
-# WebJs app rules (Cursor)
-
-Cursor reads `AGENTS.md` natively. This file points you at it and the agent
-skill, and carries the commit rule.
-
-- **Read `AGENTS.md` first, then `.agents/skills/webjs/SKILL.md`** (the guide to
-  building a WebJs app; it routes to focused references under
-  `.agents/skills/webjs/references/`). These are required context, not optional
-  reading: WebJs is not React, Next, or Lit, so gather this context before you
-  write code.
-- **Study the shipped examples, then clear them and build.** The scaffold ships
-  a browsable showcase to learn the real idioms from (a full-stack app ships a
-  UI feature gallery, the api template ships a backend-features showcase). Read
-  the parts that match your task, run `npm run gallery:clear` to shed the
-  showcase and reset to a clean base, then grow the app in place: add routes
-  under `app/`, features under `modules/<feature>/`, and keep server-only code
-  behind `.server.ts`. `AGENTS.md` carries the full template-specific playbook.
-- **Use the wired-up database (Drizzle)** for persistence. Never a JSON file, an
-  in-memory array, or localStorage.
-- **Commit per logical unit** as soon as it is complete, and never commit to
-  `main`.

package/templates/.gemini/hooks/nudge-uncommitted.sh

@@ -1,42 +0,0 @@
-#!/bin/bash
-#
-# Gemini CLI AfterTool hook.
-#
-# Counterpart of .claude/hooks/nudge-uncommitted.sh. After each
-# write_file or replace, counts uncommitted changes in the working
-# tree. When the count crosses a threshold (default 4, override
-# with the WEBJS_COMMIT_NUDGE_THRESHOLD env var), injects a
-# reminder via hookSpecificOutput.additionalContext (same shape
-# as Claude Code).
-#
-# Soft nudge. Does NOT block the edit (exit 0). Skipped on
-# main/master and outside a git work tree.
-
-set -e
-
-THRESHOLD="${WEBJS_COMMIT_NUDGE_THRESHOLD:-4}"
-
-if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
-  exit 0
-fi
-
-BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null || echo "")
-if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
-  exit 0
-fi
-
-cat /dev/stdin >/dev/null 2>&1 || true
-
-CHANGED=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
-
-if [ -z "$CHANGED" ] || [ "$CHANGED" -lt "$THRESHOLD" ]; then
-  exit 0
-fi
-
-REASON="You have ${CHANGED} uncommitted changes on '${BRANCH}'. The webjs convention is small, focused commits per logical unit (one feature, one fix, one rename, one doc rewrite). Before continuing with more edits, group the current changes into a meaningful commit. See AGENTS.md \"Git workflow\" for the rule and the rationale. To raise the threshold for this hook in long-running tasks, set WEBJS_COMMIT_NUDGE_THRESHOLD."
-
-jq -n --arg ctx "$REASON" '{
-  hookSpecificOutput: {
-    additionalContext: $ctx
-  }
-}'

package/templates/.gemini/settings.json

@@ -1,15 +0,0 @@
-{
-  "hooks": {
-    "AfterTool": [
-      {
-        "matcher": "write_file|replace",
-        "hooks": [
-          {
-            "type": "command",
-            "command": ".gemini/hooks/nudge-uncommitted.sh"
-          }
-        ]
-      }
-    ]
-  }
-}

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

@@ -1,9 +0,0 @@
-# Copilot instructions
-
-This is a thin bridge to the single source. GitHub Copilot always reads this
-file; in VS Code it reads `AGENTS.md` directly only when `chat.useAgentsMdFile`
-is enabled, so this bridge keeps Copilot pointed at the instructions regardless.
-
-The instructions for this app live in `AGENTS.md` (the cross-agent source) and
-the skill at `.agents/skills/webjs/SKILL.md`. Read `AGENTS.md` first, then the
-skill (it routes to focused references on demand).

package/templates/.opencode/plugins/nudge-uncommitted.ts

@@ -1,62 +0,0 @@
-/**
- * OpenCode commit-frequency nudge plugin.
- *
- * Counterpart of the Claude Code, Gemini CLI, and Cursor hooks in
- * `.claude/hooks/`, `.gemini/hooks/`, and `.cursor/hooks/`. After
- * each edit/write tool call, counts uncommitted changes in the
- * working tree. When the count crosses a threshold (default 4,
- * override with the WEBJS_COMMIT_NUDGE_THRESHOLD env var), appends
- * a reminder to the tool result so the agent sees it on the next
- * turn.
- *
- * Soft nudge by design. Does NOT block the edit. The goal is to
- * keep the agent honest about the "commit per logical unit" rule,
- * not to interrupt valid work.
- *
- * Skipped on main/master (different guard rules cover that) and
- * outside a git work tree.
- *
- * Auto-discovered by OpenCode at startup. No opencode.json entry
- * needed. Lives in .opencode/plugins/ at the project root.
- *
- * Docs: https://opencode.ai/docs/plugins/
- */
-import type { Plugin } from "@opencode-ai/plugin";
-
-export const NudgeUncommitted: Plugin = async ({ $ }) => {
-  const THRESHOLD = Number(process.env.WEBJS_COMMIT_NUDGE_THRESHOLD ?? 4);
-
-  return {
-    "tool.execute.after": async (input, output) => {
-      if (input.tool !== "edit" && input.tool !== "write") return;
-
-      let branch = "";
-      try {
-        branch = (await $`git symbolic-ref --short HEAD`.text()).trim();
-      } catch {
-        return; // not in a git work tree
-      }
-      if (branch === "main" || branch === "master") return;
-
-      let changed = 0;
-      try {
-        const out = (await $`git status --porcelain`.text()).trim();
-        changed = out === "" ? 0 : out.split("\n").length;
-      } catch {
-        return;
-      }
-      if (changed < THRESHOLD) return;
-
-      const reason =
-        `[webjs] You have ${changed} uncommitted changes on '${branch}'. ` +
-        `The webjs convention is small, focused commits per logical unit ` +
-        `(one feature, one fix, one rename, one doc rewrite). Before ` +
-        `continuing with more edits, group the current changes into a ` +
-        `meaningful commit. See AGENTS.md "Git workflow" for the rule ` +
-        `and the rationale. To raise the threshold for this hook in ` +
-        `long-running tasks, set WEBJS_COMMIT_NUDGE_THRESHOLD.`;
-
-      output.output = output.output ? `${output.output}\n\n${reason}` : reason;
-    },
-  };
-};

package/templates/GEMINI.md

@@ -1,11 +0,0 @@
-# GEMINI.md
-
-Gemini CLI reads `GEMINI.md`, not `AGENTS.md`, by default, so this file is a
-thin bridge to the single source.
-
-The instructions for this app live in `AGENTS.md` (the cross-agent source) and
-the skill at `.agents/skills/webjs/SKILL.md`. Read `AGENTS.md` first, then the
-skill (it routes to focused references on demand).
-
-To have Gemini read `AGENTS.md` directly instead of this bridge, add it to
-`context.fileName` in `.gemini/settings.json`.