@webjsdev/cli 0.10.51 → 0.10.52

package/bin/webjs.js

@@ -49,6 +49,40 @@ if (cmd !== 'help' && cmd !== undefined && !wantsHelp && !wantsVersion) {
 // .agents/rules/workflow.md / .github/copilot-instructions.md mirror it.
 const TEMPLATES = ['full-stack', 'api'];
 
+/**
+ * The one thing `webjs elision --verify` must say about its own boundary, in
+ * the command's own output rather than only in the docs. The differential masks
+ * the JS-loaded set by construction, so it can only ever see the DANGEROUS
+ * direction (elision changed the served bytes); a wrongly dropped module shows
+ * up as a dead click, which is bytes-identical.
+ */
+const VERIFY_CAVEAT = `
+This proves elision did not change the bytes your app serves. It does NOT prove
+post-hydration behaviour: a wrongly dropped module shows up as a dead click, not
+as different bytes. Run your browser or e2e suite twice to cover that half:
+  WEBJS_ELIDE=1 <your e2e command>
+  WEBJS_ELIDE=0 <your e2e command>`;
+
+/**
+ * `--routes /a,/b` or `--routes=/a,/b` -> ['/a', '/b']. Every value is
+ * normalized to a leading slash; empties drop.
+ * @param {string[]} argv
+ * @returns {string[]}
+ */
+function parseRoutesFlag(argv) {
+  /** @type {string[]} */
+  const raw = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--routes') { if (argv[i + 1]) raw.push(argv[i + 1]); i++; }
+    else if (argv[i].startsWith('--routes=')) raw.push(argv[i].slice('--routes='.length));
+  }
+  return raw
+    .flatMap((v) => v.split(','))
+    .map((v) => v.trim())
+    .filter(Boolean)
+    .map((v) => (v.startsWith('/') ? v : '/' + v));
+}
+
 const USAGE = `webjs commands:
   webjs dev   [--port 8080] [--no-hot]            Start dev server with live reload
                                                   (--no-hot: run in-process, no hot-reload supervisor)
@@ -56,8 +90,10 @@ const USAGE = `webjs commands:
   webjs test  [--server|--browser]                 Run server + browser tests
   webjs check [--json]                            Run correctness checks (--json emits structured violations)
   webjs routes [--json|--table] [--no-headers]    Print the route table (path / owner file / methods). Default tree; --json matches the MCP list_routes shape; --no-headers drops the --table header
-  webjs mcp                                       Start the read-only MCP server (routes / actions / components / check)
-  webjs doctor [--json] [--strict]                Verify project health (Node, tsconfig, env, vendor pins, importmap coherence, @webjsdev versions, git hook, page/layout elision, un-versioned stylesheet links).
+  webjs elision [--json] [--verify]               Report which component modules are elided and why each shipped one ships;
+                                                  --verify diffs SSR output with elision on vs off (exits non-zero on a divergence)
+  webjs mcp                                       Start the read-only MCP server (routes / actions / components / elision / check)
+  webjs doctor [--json] [--strict]                Verify project health (Node, tsconfig, env, vendor pins, importmap coherence, @webjsdev versions, git hook, page/layout elision, component elision, un-versioned stylesheet links).
                                                   --json emits the structured results (with stable codes). --strict additionally fails on every remaining warning.
                                                   Per-check severity is CONFIG: map a code to off/warn/error under "webjs": { "doctor": { "gate": {...} } }
                                                   in package.json, so CI gates on a chosen subset without every warning becoming fatal
@@ -144,6 +180,24 @@ const HELP = {
     ],
     examples: ['webjs routes', 'webjs routes --table', 'webjs routes --table --no-headers', 'webjs routes --json'],
   },
+  elision: {
+    usage: 'webjs elision [--json] [--verify] [--routes <paths>]',
+    summary:
+      'Report the elision verdict: which component modules the browser never downloads, and why each one that ships does.',
+    options: [
+      { flag: '--json', description: 'Emit the verdict as JSON (byte-identical to the MCP list_elision tool).' },
+      { flag: '--verify', description: 'Render every static page route with elision on and off and diff the observable SSR bytes. Exits non-zero on a divergence.' },
+      { flag: '--routes <paths>', description: 'Comma-separated URL paths to add to the --verify corpus (the only way to cover a dynamic route).' },
+    ],
+    notesTitle: 'What --verify proves',
+    notes: [
+      '--verify proves elision did not change the bytes your app serves. It does NOT',
+      'prove post-hydration behaviour: a wrongly dropped module shows up as a dead',
+      'click, not as different bytes. Run your browser or e2e suite twice',
+      '(WEBJS_ELIDE=1 then WEBJS_ELIDE=0) to cover that half.',
+    ],
+    examples: ['webjs elision', 'webjs elision --json', 'webjs elision --verify', 'webjs elision --verify --routes /,/blog/hello'],
+  },
   doctor: {
     usage: 'webjs doctor [--json] [--strict]',
     summary: 'Verify project health. Each result carries a stable code so an agent branches on the failure kind.',
@@ -215,7 +269,7 @@ const HELP = {
   },
   mcp: {
     usage: 'webjs mcp',
-    summary: 'Start the read-only MCP server (routes / actions / components / check + a docs/source knowledge layer).',
+    summary: 'Start the read-only MCP server (routes / actions / components / elision / check + a docs/source knowledge layer).',
     examples: ['webjs mcp'],
   },
   version: {
@@ -255,9 +309,12 @@ function printCommandHelp(name) {
   console.log('Options:');
   for (const o of options) console.log(`  ${o.flag.padEnd(width)}  ${o.description}`);
   // Optional per-command prose for surface a flag table cannot carry (doctor's
-  // package.json severity gate is the one that needs it).
+  // package.json severity gate is the one that needs it). The heading defaults
+  // to `Config:` because that is what doctor's block is and what its help test
+  // pins; a command whose prose is not configuration names its own heading
+  // (`webjs elision`'s is a caveat about what --verify proves).
   if (h.notes) {
-    console.log('\nConfig:');
+    console.log(`\n${h.notesTitle || 'Config'}:`);
     for (const line of h.notes) console.log(`  ${line}`);
   }
   console.log('\nExamples:');
@@ -887,6 +944,251 @@ async function main() {
       }
       break;
     }
+    case 'elision': {
+      // Report the elision verdict for the app in cwd (#1308): which component
+      // modules the browser never downloads, why each one that ships does,
+      // which page/layout is inert / import-only / ships whole, and any orphan
+      // class that gets no verdict at all. Reuses the ONE analysis pass
+      // (`analyzeAppElision`, the same reporting layer `webjs doctor` and
+      // the MCP `list_elision` tool call), so `--json` is byte-identical to
+      // that tool. Read-only: no autofix, and nothing is written to disk.
+      const appDir = process.cwd();
+
+      // --verify: the app-level differential. Renders every static page route
+      // with elision ON and OFF in this one process and diffs the observable
+      // SSR bytes, which is literally the framework's own guard
+      // (`packages/server/test/elision/differential-elision.test.js`) pointed
+      // at an arbitrary app's route table.
+      if (rest.includes('--verify')) {
+        const { createRequestHandler, buildRouteTable, maskJsSet, staticPageRoutes } =
+          await import('@webjsdev/server');
+
+        const extra = parseRoutesFlag(rest);
+        let table;
+        try {
+          table = await buildRouteTable(appDir);
+        } catch (err) {
+          console.error(`webjs elision --verify: cannot read the route table here (${err && err.message}).`);
+          process.exit(1);
+        }
+        const staticRoutes = staticPageRoutes(table);
+        const dynamic = (table.pages || [])
+          .filter((r) => r.paramNames && r.paramNames.length)
+          .map((r) => (r.routeDir && r.routeDir !== '.' ? '/' + r.routeDir : '/'))
+          .sort();
+        // An extra route the author named explicitly is REQUIRED to render; a
+        // static one that does not is merely reported (a page may legitimately
+        // throw notFound() for every visitor).
+        const required = new Set(extra);
+        const routes = [...new Set([...staticRoutes, ...extra])];
+
+        // The app's access log would drown the verdict, and a verification
+        // run is not a server: keep errors (a real boot failure must surface)
+        // and drop the per-request info lines.
+        const quiet = { info: () => {}, warn: () => {}, debug: () => {}, error: (...a) => console.error(...a) };
+
+        const capture = async (h, r) => {
+          const resp = await h.handle(new Request('http://localhost' + r));
+          return { status: resp.status, html: await resp.text() };
+        };
+        // The module URLs a response preloads, with the content-hash query
+        // stripped. Comparing the two sides' sets is how the run reports what
+        // elision actually DROPPED, which is the only thing that distinguishes
+        // a real pass from two identical renders.
+        const preloadSet = (html) => new Set(
+          [...html.matchAll(/<link rel="modulepreload" href="([^"]+)"/g)].map((m) => m[1].split('?')[0]),
+        );
+
+        const ORIG = process.env.WEBJS_ELIDE;
+        /** @type {Record<string, {status:number, html:string}>} */
+        const onA = {}, onB = {}, off = {};
+        try {
+          // Elision ON, FORCED. Deleting the override would only fall back to
+          // `webjs.elide`, so on an app that opts out this side would run with
+          // elision OFF too and the command would compare two identical renders
+          // and report them "identical with elision on vs off", which is false
+          // about a run where elision was never on. The env override wins over
+          // the config key, which is exactly what makes it the right seam here.
+          // Warm fully so the memoized verdict is locked before the env flips
+          // for the second handler.
+          process.env.WEBJS_ELIDE = '1';
+          const hOn = await createRequestHandler({ appDir, dev: false, logger: quiet });
+          if (hOn.warmup) await hOn.warmup();
+          for (const r of routes) onA[r] = await capture(hOn, r);
+          // A SECOND capture through the same warm handler. A route whose two
+          // ON captures already differ is nondeterministic (live data, a random
+          // id, a clock the masker does not normalize), so a differential over
+          // it proves nothing and reporting it as a failure would be a red the
+          // author cannot act on. The framework's own test needs no such pass
+          // because its corpus is fixed and known; an arbitrary app's is not.
+          for (const r of routes) onB[r] = await capture(hOn, r);
+          // Elision OFF via the env override; a fresh handler reads it on its
+          // own first warm.
+          process.env.WEBJS_ELIDE = '0';
+          const hOff = await createRequestHandler({ appDir, dev: false, logger: quiet });
+          if (hOff.warmup) await hOff.warmup();
+          for (const r of routes) off[r] = await capture(hOff, r);
+        } catch (err) {
+          console.error(`webjs elision --verify: could not boot the app (${err && err.message}).`);
+          process.exit(1);
+        } finally {
+          if (ORIG === undefined) delete process.env.WEBJS_ELIDE;
+          else process.env.WEBJS_ELIDE = ORIG;
+        }
+
+        const unrenderable = [], nondeterministic = [], diverged = [];
+        /** @type {Set<string>} modules the OFF side preloads and the ON side does not */
+        const dropped = new Set();
+        let compared = 0;
+        for (const r of routes) {
+          if (onA[r].status >= 400) { unrenderable.push(`${r} (${onA[r].status})`); continue; }
+          if (maskJsSet(onA[r].html) !== maskJsSet(onB[r].html)) { nondeterministic.push(r); continue; }
+          compared++;
+          // What elision removed on this route. A pass over a corpus where this
+          // stays empty is TRUE but trivially so, and the author needs to see
+          // that rather than read it as proof elision was exercised.
+          const onSet = preloadSet(onA[r].html);
+          for (const u of preloadSet(off[r].html)) if (!onSet.has(u)) dropped.add(u);
+          const a = maskJsSet(onA[r].html);
+          const b = maskJsSet(off[r].html);
+          if (onA[r].status !== off[r].status) {
+            diverged.push({ route: r, kind: 'status', a: String(onA[r].status), b: String(off[r].status), at: 0 });
+            continue;
+          }
+          if (a !== b) {
+            let i = 0;
+            while (i < a.length && i < b.length && a[i] === b[i]) i++;
+            diverged.push({
+              route: r, kind: 'body', at: i,
+              a: a.slice(Math.max(0, i - 40), i + 40),
+              b: b.slice(Math.max(0, i - 40), i + 40),
+            });
+          }
+        }
+
+        for (const d of diverged) {
+          console.error(
+            d.kind === 'status'
+              ? `FAIL ${d.route}: status differs with elision on vs off (on=${d.a}, off=${d.b})`
+              : `FAIL ${d.route}: elision changed observable output near offset ${d.at}\n` +
+                `  ON : ...${JSON.stringify(d.a)}\n  OFF: ...${JSON.stringify(d.b)}`,
+          );
+        }
+        const badRequired = unrenderable.filter((u) => required.has(u.split(' ')[0]));
+        for (const u of badRequired) console.error(`FAIL ${u}: a --routes path must render`);
+
+        const skips = [
+          dynamic.length ? `${dynamic.length} skipped (dynamic: ${dynamic.join(', ')})` : '0 skipped (dynamic)',
+          `${nondeterministic.length} skipped (nondeterministic${nondeterministic.length ? ': ' + nondeterministic.join(', ') : ''})`,
+        ];
+        if (unrenderable.length) skips.push(`${unrenderable.length} skipped (did not render: ${unrenderable.join(', ')})`);
+
+        if (diverged.length || badRequired.length) {
+          console.error(`\nwebjs elision --verify: ${diverged.length} route(s) diverged out of ${compared} compared.`);
+          process.exit(1);
+        }
+        if (compared === 0) {
+          // A vacuous pass is a failure, the same posture scripts/run-bun-tests.js
+          // takes for a run that executed zero tests.
+          console.error(
+            `webjs elision --verify: nothing was compared (${skips.join(', ')}).\n` +
+            'Pass --routes /a,/b to name renderable paths, or add a static page route.',
+          );
+          process.exit(1);
+        }
+        console.log(
+          `webjs elision --verify: ${compared} route(s) identical with elision on vs off, ${skips.join(', ')}.\n` +
+          (dropped.size
+            ? `Elision dropped ${dropped.size} module(s) across that corpus, so the comparison was a real one.`
+            : 'Elision dropped NO modules across that corpus: nothing on these routes was elidable, so '
+              + 'there was nothing for elision to change. The comparison holds, it just had no work to '
+              + 'do. Run `WEBJS_ELIDE=1 webjs elision` to see why every module here ships (the same '
+              + 'override this run used, so the verdict matches even in an app that opts out).'),
+        );
+        console.log(VERIFY_CAVEAT);
+        break;
+      }
+
+      const { analyzeAppElision } = await import('@webjsdev/server');
+      const report = await analyzeAppElision(appDir);
+
+      // --json: the machine contract, identical to the MCP `list_elision` shape.
+      if (rest.includes('--json')) {
+        console.log(JSON.stringify(report));
+        break;
+      }
+
+      if (!report.analysed) {
+        const why = {
+          'no-app': 'no app/ directory here, so there is nothing to analyse',
+          'elide-off': 'elision is disabled (webjs.elide false, or WEBJS_ELIDE), so every module ships',
+          unanalysable: 'the app could not be analysed (`webjs check` and `webjs dev` name the real problem)',
+        }[report.skipped] || 'nothing was analysed';
+        console.log(`webjs elision: ${why}.`);
+        break;
+      }
+
+      const s = report.summary;
+      console.log(
+        `webjs elision: ${s.components} component module(s), ${s.elided} elided, ${s.shipped} shipped. ` +
+        `${s.routeModules} route module(s): ${s.inert} inert, ${s.importOnly} import-only, ${s.shippedWhole} ship whole.\n`,
+      );
+
+      const elided = report.components.filter((c) => c.verdict === 'elided');
+      const shipped = report.components.filter((c) => c.verdict === 'shipped');
+      // Column width, capped so one outlier does not push every other row off
+      // the terminal. An over-long cell overflows its own row rather than
+      // widening the table. The FILE column gets the generous cap because a
+      // module path is what a reader scans by; the tag column gets the tight
+      // one because a file registering five tags is the rare case.
+      const pad = (rows, col, cap) => Math.min(cap, Math.max(0, ...rows.map((r) => r[col].length)));
+      const FILE_W = 58, TAG_W = 30;
+
+      if (elided.length) {
+        console.log('Elided components (the browser never downloads these)');
+        const rows = elided.map((c) => [c.file, c.tags.join(', ')]);
+        const w = pad(rows, 0, FILE_W);
+        for (const [file, tags] of rows) console.log(`  ${file.padEnd(w)}  ${tags}`.trimEnd());
+        console.log();
+      }
+      if (shipped.length) {
+        console.log('Shipped components (and the evidence that forced each one)');
+        const rows = shipped.map((c) => [c.file, c.tags.join(', '), `${c.evidence || 'unknown'}: ${c.reason || 'no evidence recorded'}`]);
+        const w0 = pad(rows, 0, FILE_W), w1 = pad(rows, 1, TAG_W);
+        for (const [file, tags, why] of rows) console.log(`  ${file.padEnd(w0)}  ${tags.padEnd(w1)}  ${why}`.trimEnd());
+        console.log();
+      }
+      if (report.routeModules.length) {
+        console.log('Route modules');
+        const rows = report.routeModules.map((r) => [
+          r.verdict, r.file,
+          r.verdict === 'import-only' ? `emits ${r.emits.join(', ') || '(nothing)'}`
+            : r.verdict === 'shipped' ? (r.blocker ? `blocked by ${r.blocker}, which ${r.reason}` : `it ${r.reason}`)
+            : '',
+        ]);
+        const w0 = pad(rows, 0, 12), w1 = pad(rows, 1, FILE_W);
+        for (const [verdict, file, note] of rows) {
+          console.log(`  ${verdict.padEnd(w0)}  ${file.padEnd(w1)}${note ? '  ' + note : ''}`.trimEnd());
+        }
+        console.log();
+      }
+      if (report.orphans.length) {
+        console.log('Orphan components (no elision verdict; `static interactive = true` cannot rescue these)');
+        for (const o of report.orphans) {
+          console.log(`  ${o.className} in ${o.file} is never registered with a literal tag`);
+        }
+        console.log('  Either there is no registration call at all, or the tag is computed. The scanner matches');
+        console.log('  only a literal tag, so either way the module gets no verdict, no registry entry, and no');
+        console.log('  preload hint. With no registration call the element never upgrades at all; with a computed');
+        console.log('  tag it upgrades only while its module still reaches the browser through a shipping importer.');
+        console.log('  Fix: register it with a literal tag, Class.register(\'my-tag\'), or delete the class.');
+        console.log();
+      }
+      if (!report.components.length && !report.routeModules.length) {
+        console.log('  Nothing to report. Add a component or a page under app/.');
+      }
+      break;
+    }
     case 'types': {
       // Generate `.webjs/routes.d.ts` from the app's `app/` routes (#258),
       // narrowing the @webjsdev/core `Route` href union + per-route `params`.

package/lib/doctor.js

@@ -103,6 +103,7 @@ export const DOCTOR_CODES = {
   'importmap-coherence': 'IMPORTMAP_COHERENCE',
   'git-hook': 'GIT_HOOK',
   'Page/layout elision (carrier hygiene)': 'ELISION_CARRIERS',
+  'Component elision (what the browser drops)': 'ELISION_COMPONENTS',
   'Static build outputs (dev.regenerate freshness)': 'STATIC_ASSET_FRESHNESS',
   'Asset urls (unmarked stylesheet links)': 'UNMARKED_ASSET_LINKS',
 };
@@ -1002,43 +1003,104 @@ function checkGitHook(appDir) {
  * named line. WARN only: a page legitimately MAY ship, and the analyser is
  * biased toward shipping by design (server AGENTS invariant 7), so this is a
  * "you may not have intended this" hint, never a hard fail.
- * @param {string} appDir
+ * @param {Promise<any|null>} elisionPromise  the ONE shared report (#1308)
  * @returns {Promise<DoctorResult>}
  */
-async function checkElisionCarriers(appDir) {
+async function checkElisionCarriers(elisionPromise) {
   const name = 'Page/layout elision (carrier hygiene)';
-  let report;
-  try {
-    const { analyzeAppElision } = await import('@webjsdev/server');
-    report = await analyzeAppElision(appDir);
-  } catch {
+  const report = await elisionPromise;
+  if (!report) {
     // Analysis unavailable (no app, malformed, server import failed): no advice.
     return { name, status: 'pass', message: 'not analysed (no routable app or analysis unavailable)' };
   }
   if (!report.analysed) {
     return { name, status: 'pass', message: 'not analysed (no routable app, or elision is disabled)' };
   }
-  if (report.shipped.length === 0) {
+  // Paths and reasons arrive app-relative from `analyzeAppElision` (#1308).
+  const shipped = report.routeModules.filter((r) => r.verdict === 'shipped');
+  if (shipped.length === 0) {
     return { name, status: 'pass', message: 'every page/layout is elided (a pure import-only or inert carrier)' };
   }
-  const rel = (f) => relative(appDir, f) || f;
   // Name the FIRST client-effecting blocker (there may be more than one; the
   // module stays shipped until every such blocker is moved out).
-  const lines = report.shipped.map(({ file, blocker, reason }) =>
+  const lines = shipped.map(({ file, blocker, reason }) =>
     blocker
-      ? `${rel(file)} ships whole. Its first client-effecting blocker is ${rel(blocker)}, which ${reason} and is not a component`
-      : `${rel(file)} ships whole because it ${reason}`,
+      ? `${file} ships whole. Its first client-effecting blocker is ${blocker}, which ${reason} and is not a component`
+      : `${file} ships whole because it ${reason}`,
   );
   return {
     name,
     status: 'warn',
     message:
-      `${report.shipped.length} page/layout module(s) ship to the browser instead of being elided:\n` +
+      `${shipped.length} page/layout module(s) ship to the browser instead of being elided:\n` +
       lines.map((l) => `    ${l}`).join('\n'),
     fix: 'Move the client work out of the page/layout closure (into a component, or a .server module reached through an action) so the carrier can be elided, or accept that it ships. See references/components.md in the skill.',
   };
 }
 
+/**
+ * The OTHER direction of the elision verdict (#1308): which COMPONENT modules
+ * the browser never downloads. `checkElisionCarriers` above reports the benign
+ * over-ship direction; this one reports what was DROPPED, which is where a
+ * wrong verdict silently costs an app its interactivity.
+ *
+ * Pass-only except for orphans, deliberately. An elided component is the
+ * DESIRED outcome, so warning on one would fire on every healthy app and train
+ * the reader to skip doctor output. The passing message carries the elided
+ * inventory instead, which makes it the discovery surface, while `webjs
+ * elision` is the detail surface. The one always-wrong condition is an ORPHAN:
+ * a `class X extends WebComponent` with no literal-tag registration is
+ * invisible to the scanner, so it gets no verdict at all and `static
+ * interactive = true` cannot rescue it (nothing consults the component
+ * analyser for a component the scanner never saw). Never `fail`:
+ * an app that wants an orphan to break CI gates `ELISION_COMPONENTS` to
+ * `error` via `webjs.doctor.gate`.
+ *
+ * @param {Promise<any|null>} elisionPromise  the ONE shared report
+ * @returns {Promise<DoctorResult>}
+ */
+async function checkElisionComponents(elisionPromise) {
+  const name = 'Component elision (what the browser drops)';
+  const report = await elisionPromise;
+  const notAnalysed = { name, status: /** @type {const} */ ('pass'), message: 'not analysed (no routable app or analysis unavailable)' };
+  if (!report) return notAnalysed;
+  if (!report.analysed) {
+    return report.skipped === 'elide-off'
+      ? { name, status: 'pass', message: 'elision is disabled (webjs.elide false or WEBJS_ELIDE), so every component module ships' }
+      : notAnalysed;
+  }
+  if (report.orphans.length > 0) {
+    const lines = report.orphans.map(({ file, className }) =>
+      `${className} in ${file} is never registered with a literal tag`,
+    );
+    return {
+      name,
+      status: 'warn',
+      message:
+        `${report.orphans.length} component class(es) get NO elision verdict:\n` +
+        lines.map((l) => `    ${l}`).join('\n') +
+        '\n    Either it has no registration call at all, or it registers a computed tag. The component '
+        + 'scanner matches only a literal tag, so either way it never sees the class: no elision verdict, no '
+        + 'registry entry, no preload hint, and `static interactive = true` cannot rescue it. With no '
+        + 'registration call the element never upgrades at all; with a computed tag it upgrades only while '
+        + 'its module still reaches the browser through an importer that ships.',
+      fix: 'Register it with a literal tag, Class.register(\'my-tag\') (invariant 3 already requires one), or delete the class if nothing uses it.',
+    };
+  }
+  const elided = report.components.filter((c) => c.verdict === 'elided');
+  const tags = elided.flatMap((c) => c.tags);
+  const shown = tags.slice(0, 8).join(', ');
+  const tail = tags.length > 8 ? `, +${tags.length - 8} more` : '';
+  return {
+    name,
+    status: 'pass',
+    message:
+      `${report.summary.elided} of ${report.summary.components} component module(s) are elided (never downloaded)` +
+      (tags.length ? `: ${shown}${tail}` : '') +
+      '. Run `webjs elision` for the full verdict.',
+  };
+}
+
 // Directories never worth walking for the CSS-freshness advisory (mirrors
 // dev-regenerate's IGNORE_DIRS): build output, deps, VCS + framework caches.
 const FRESHNESS_IGNORE = new Set(['node_modules', '.git', '.webjs', 'dist', '.next', 'coverage']);
@@ -1517,6 +1579,16 @@ export function checkFrameworkResolves(appDir) {
 
 export async function runDoctorChecks(appDir, opts = {}) {
   const cliDir = opts.cliDir || new URL('.', import.meta.url).pathname;
+  // ONE elision report for BOTH elision checks (#1308). Started before the
+  // batch and awaited inside each check, so the module graph is built once per
+  // doctor run and the two checks still run in parallel with everything else.
+  // Fails soft to null, exactly as the carrier check's own try/catch did.
+  const elision = (async () => {
+    try {
+      const { analyzeAppElision } = await import('@webjsdev/server');
+      return await analyzeAppElision(appDir);
+    } catch { return null; }
+  })();
   const results = await Promise.all([
     checkNode(cliDir, opts),
     checkTsconfig(appDir),
@@ -1527,7 +1599,8 @@ export async function runDoctorChecks(appDir, opts = {}) {
     Promise.resolve(checkFrameworkResolves(appDir)),
     checkImportmapCoherence(appDir, opts),
     Promise.resolve(checkGitHook(appDir)),
-    checkElisionCarriers(appDir),
+    checkElisionCarriers(elision),
+    checkElisionComponents(elision),
     checkStaticAssetFreshness(appDir),
     checkUnmarkedAssetLinks(appDir),
   ]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.51",
+  "version": "0.10.52",
   "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": {

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

@@ -39,6 +39,7 @@ Classify the task first, then load the smallest useful reference set. Each refer
 | --------------------------------------------------------------------------- | --------------------------------------------- |
 | Pages, layouts, dynamic routes, route handlers, metadata, redirects, 404s   | `references/routing-and-pages.md`             |
 | Writing components: reactive props, signals, lifecycle, light vs shadow DOM  | `references/components.md`                     |
+| Why a component's JS was or was not downloaded, `webjs elision`, `static interactive = true` | `references/components.md`                     |
 | Server actions, mutations, queries, validation, the `ActionResult` envelope | `references/data-and-actions.md`              |
 | Sessions, login flows, route protection, `forbidden()` / `unauthorized()`   | `references/auth-and-sessions.md`             |
 | Tailwind, light-DOM tag-prefix rule, tokens, fixed headers, no-reflow layout | `references/styling.md`                        |
@@ -105,7 +106,7 @@ App-internal imports use the `#` root alias (`import { db } from '#db/connection
 9. No backtick characters inside an `html\`...\`` body, even in comments (it closes the literal and 500s).
 10. TypeScript must be erasable (`erasableSyntaxOnly: true`): no `enum`, no value `namespace`, no constructor parameter properties, no legacy decorators.
 11. Reactive properties are declared ONLY through the base-class factory `extends WebComponent({ count: Number })`. Never a `static properties` block, never a class-field initializer (it clobbers the reactive accessor).
-12. A form that writes binds its action: `<form action=${importedAction}>`, or a per-button `<button formaction=${importedAction}>` inside a bound form. Quoted bindings, non-submit controls, `<input type="submit">` (the identity needs its `value`, which is also its label, so use a `<button>`), submitter `name` / `value` / `form` / static `formaction` attributes, a `.prop` spelling of any of those, `action=${fn}` off a `<form>`, a bound form with `method="get"`, `formmethod="get"` or an unparseable `formenctype` on ANY submitter in a bound form, and a non-action function all throw. A page has no `action` export, so a bare `<form method="post">` is a 405.
+12. A form that writes binds its action: `<form action=${importedAction}>`, or a per-button `<button formaction=${importedAction}>`. A bound submitter is SELF-SUFFICIENT (#1307): the renderer puts `formmethod="post"` and `formenctype` on the button itself, so it needs no bound form around it and works inside any form or none. Quoted bindings, non-submit controls, `<input type="submit">` (the identity needs its `value`, which is also its label, so use a `<button>`), submitter `name` / `value` / `form` / static `formaction` attributes, a `.prop` spelling of any of those, `action=${fn}` off a `<form>`, a bound form with `method="get"`, a BOUND submitter's own non-post `formmethod` or unparseable `formenctype`, and a non-action function all throw. A PLAIN button's own `formmethod` / `formenctype` is a legal native override and is left alone. A page has no `action` export, so a bare `<form method="post">` is a 405.
 
 ## Export Map
 
@@ -236,7 +237,7 @@ Success is a 303 (PRG); failure re-renders the page at 422 with the result on `a
 - Writing `fetch()` to call your own server instead of importing the action.
 - 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 any button inside a bound form. Neither can carry the action's body, so both are refused even when the button binds nothing.
+- 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.
 - 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()`.

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

@@ -233,7 +233,7 @@ Wired at the single response funnel, covering pages, routes, actions, and assets
 
 - **Access log.** One structured `info` line per handled request (`method`, `path`, `status`, `durationMs`, `requestId`). Never logs bodies or secrets; framework `/__webjs/*` traffic is suppressed.
 - **Request id.** Each request gets a `crypto.randomUUID()` correlation id, set as `X-Request-Id` (honoring a trusted inbound one) and readable server-side with `requestId()` from `@webjsdev/server` (returns `null` outside a request scope).
-- **`onError` hook.** Register via `createRequestHandler({ onError })` or `startServer({ onError })`. Called with `(error, { request, requestId, phase })` on any caught pipeline error, before the sanitized response is sent. Best-effort (a throwing hook is ignored), purely additive (the sanitized 500 / action digest is unchanged). Point it at Sentry or an APM.
+- **`onError` hook.** Register via `createRequestHandler({ onError })` or `startServer({ onError })`. Called with `(error, { request, requestId, phase })` on any caught pipeline error, before the sanitized response is sent. Best-effort (a throwing hook is ignored), purely additive (the sanitized 500 / action digest is unchanged). Point it at Sentry or an APM. It also carries two framework DIAGNOSTICS that are not request failures, each with an `err.code` to group or filter on, both under `phase: 'action'`: `WEBJS_FORM_SUBMITTED_AS_GET` (a page GET carrying the reserved `__webjs_action` field in its query string, so a submission holding a bound action's identity went out as a GET and the action never ran, #1307; a bound submitter carries its own `formmethod="post"`, so what reaches this is an explicit `formmethod="get"` / `method="get"` the author wrote and the renderer honours rather than refuses) and `WEBJS_FORM_ACTION_MISSING` (a PARSEABLE form body carrying no identity, the 405; an `enctype="text/plain"` submission is answered before its body is read, so it stays a bare 405). Both are detect-only, so the 200 and the 405 are unchanged; both carry `method`, `pathname`, and for the second the submitted field NAMES, never the values; and both are deduplicated per process on the code, the method, and the matched ROUTE (not the request pathname, so crafted urls on a dynamic route cannot exhaust the 256-entry cap and silence the diagnostics), since either is reachable by an unauthenticated request and an uncapped report would be a free amplifier into a paid sink.
 
 ```ts
 const app = await createRequestHandler({

package/templates/.agents/skills/webjs/references/client-router-and-streaming.md

@@ -56,6 +56,16 @@ revalidate();                                 // clear the entire snapshot cache
 
 The router keeps a URL-keyed snapshot cache (LRU, cap 16) so Back/Forward restores instantly, then refetches in the background. Call `revalidate(path)` after a server action mutates data a cached page depends on. Wire bytes are minimized by an `X-Webjs-Have` header, so the server returns only the divergent layout fragment. Concurrent navigations abort the prior in-flight fetch, and scroll is restored on Back/Forward.
 
+**Back/Forward scroll restore vs late layout growth.** The router SUPPRESSES the browser's scroll anchoring (`overflow-anchor`) for the duration of a Back/Forward restore, then puts it back. The saved offset was recorded against the page at its SETTLED height, while the DOM the restore swaps in is still shorter until its components upgrade and render. Without the suppression the browser treats that late growth as content appearing above a reader and adds it to the offset the router just replayed, so the reader lands BELOW where they left (the reported case was 763px, exactly the height a page gained after its swap). What follows for an app:
+
+- **Do not write your own scroll restore.** A `popstate` listener that calls `scrollTo`, a saved offset in `sessionStorage`, a `scrollIntoView` on a remembered element: all of them fight the router, which already set `history.scrollRestoration = 'manual'` and is the sole authority on scroll during a navigation. If Back lands in the wrong place, that is a framework bug to report, not something to patch in app code.
+- **An app that sets `overflow-anchor` on `<html>` itself sees it overridden during a restore and restored afterwards**, including a value set inline by your own script. Setting it in a stylesheet is unaffected between restores. Nothing else on the page is touched, and the router never sets `overflow-anchor` anywhere but the root element.
+- **A new PAGE navigation ends an open window.** The window outlives its own restore on purpose (a floor, then a ceiling), so a page navigation or a page-level form submission starting inside that span closes it first, and reopens only if it earns one. Otherwise a second Back, or a click, would inherit suppressed anchoring on a page it was never meant for. A FRAME-TARGETED navigation or submission is the exception, on exactly the rule that decides frame targeting everywhere else (the enclosing frame, an explicit `data-webjs-frame="<id>"` from anywhere, or the frame's own `src`; `_top` and an unresolvable id are page navigations and do close the window). It swaps one region and leaves the page, and so the restored offset, intact, so it leaves the restore running. Closing there would hand anchoring back mid-restore and bring the double count straight back, and it needs no user input to happen, since a component upgrading in the just-restored page can drive a frame on its own.
+- **Suppression is conditional on the offset being reachable, and follows the chase onto it.** A page that has not grown yet can be too short to scroll that far, so the browser clamps to its current maximum. There the shortfall IS the growth still to come, and anchoring adding it is what carries the reader back down, so the router leaves anchoring alone. Suppressing in that case would freeze the clamp and strand the reader a full page-growth above where they left, which is this same defect pointing the other way. That case is not left to anchoring alone, though, because anchoring adds the FULL growth however far short the clamp fell, so by itself it only lands a reader who left at the very bottom. The router also CHASES the recorded offset there, re-asserting it the moment the page is tall enough to hold it, and then stopping. That is the one place the router writes scroll after the initial restore, it is scoped to the clamped path, and it stops on the same inputs that close a suppression window. It is also time-boxed, and more tightly than the window a landed restore gets: a few hundred milliseconds from the RESTORE, not the 2s ceiling, and the suppression it installs on landing shares that same deadline rather than starting a fresh one. That bound is what keeps it from moving a reader who has landed and started reading, since such a reader generates no input to cancel it and the chase cannot tell the restore settling apart from any other growth. Anchoring is left on only WHILE the offset is out of reach, which is the part that heals the clamp. The moment the chase lands on the offset it suppresses anchoring too, because the growth that made the offset reachable is rarely all of it and every later stage would otherwise be added on top of what was just written. Both halves end together on the bound. After it, the router writes no more scroll and anchoring is back on, so a component that reaches its final height later than the bound (a chart, an embed measured from its content) has its growth added and the reader drifts BELOW the offset, the same way they would without this fix at all, rather than sitting at the clamp.
+- **The window closes on the first real input** (`wheel`, `touchmove`, `keydown`, `pointerdown`), so a reader who starts scrolling mid-restore immediately gets normal browser anchoring back. Absent that it closes once the restore is over, which is the LATER of the restore's own background revalidation settling and a short floor, and at the latest on a 2s ceiling. The floor is load-bearing: waiting on the revalidation alone ties the window's length to network latency rather than to the growth it guards, so a server answering faster than the page renders would close it early and the reader would land low again. Suppression only ever WITHHOLDS a browser correction, it never moves the viewport, so it cannot yank someone who has taken over.
+
+Components that reach their final size only after they render (a chart, a media embed with no intrinsic dimensions, anything sized from measured content) are exactly the shape that triggers this, and they need no special handling: give them a placeholder height where you can, and let the router own the restore.
+
 **Error recovery.** A 2xx/3xx swap applies in place, and an HTML error body of any status (a 422 re-rendered form, a 5xx error page) is ALSO applied in place with no reload. For a non-HTML error or a transport failure the router dispatches a cancelable `webjs:navigation-error` on `document` (detail `{ url, status, error }`). Call `preventDefault()` to own recovery, otherwise the router renders a minimal in-place alert into the layout slot.
 
 ```ts

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

@@ -183,7 +183,7 @@ The boundary also covers `watch(signal)` (its notify microtask) and `until()` (i
 
 **A commit that throws leaves the directive's own state consistent, so the NEXT valid render is correct.** This matters because the corruption is otherwise silent: the renders that expose it are fully valid and log nothing after the first throw. The hole whose commit threw is marked so the next render re-applies it rather than skipping it as unchanged (its recorded value is never advanced past a throw, and would otherwise match exactly what the recovering render supplies, leaving a child region blank for good). Both list reconcilers additionally repair their own bookkeeping so it describes the DOM again, and the next render is an ordinary reconcile rather than a rebuild of the region, which would discard the node identity the reconcilers exist to preserve. `repeat()` re-unites its key map and repositions every row (the failure was a permanently duplicated row). A plain `.map()` array splices the part of its slot list the failed pass never reached back on, which matters whenever a slot is REPLACED rather than updated in place (its template shape changed, its kind changed between text, template and empty, or the array grew past its old length), since that is the branch that inserts the replacement before removing what it replaced (the failure was a stranded row that outlived even a render of an empty array). `guard()` records its new deps only once the commit succeeds, so a later render with those same deps re-renders the region instead of short-circuiting past a region the throw had blanked; `until()` advances its resolved priority only after the commit succeeds, so a failed high-priority resolution does not refuse the lower-priority one behind it.
 
-**Teardown is total as well.** Removing a row is not a commit and has no retry, so a throw while tearing one down cannot be allowed to abandon the rest. Unbinding a `ref` during teardown can never abort the removal of the remaining rows, and `repeat()` drops each leftover key from its map before touching that row, so the map never describes a row that has already been removed (which used to leave the row the app DELETED on screen, reorder the survivors, and let a later render that re-added that key reinsert the disposed instance). To make that hold, a `ref` whose object `value` setter throws is now SWALLOWED on teardown, matching the ref CALLBACK, which was already swallowed everywhere. That is a deliberate divergence from lit, which guards neither and propagates from both. It applies to teardown only: on the COMMIT path a throwing object-ref setter still reaches `renderError()`, because there the boundary can report it and the next render can repair it.
+**Teardown is total as well.** Removing a row is not a commit and has no retry, so a throw while tearing one down cannot be allowed to abandon the rest. Unbinding a `ref` during teardown can never abort the removal of the remaining rows, and `repeat()` drops each leftover key from its map before touching that row, so the map never describes a row that has already been removed (which used to leave the row the app DELETED on screen, reorder the survivors, and let a later render that re-added that key reinsert the disposed instance). To make that hold, a `ref` whose object `value` setter throws is now SWALLOWED on teardown, matching the ref CALLBACK, which was already swallowed everywhere. That is a deliberate divergence from lit, which guards neither and propagates from both. It applies to teardown only: on the COMMIT path a throwing object-ref setter still reaches `renderError()`, because there the boundary can report it and the next render can repair it. Total also means a removal takes the row's own boundary markers with it, so a list that grows and shrinks all day is net zero on the nodes the renderer added, rather than accruing one invisible comment per removed row for the life of the region.
 
 Decision rules. Use `async render()` for request-time server data that should be in the first paint (the default). Add `renderFallback()` when a client re-fetch's stale content would mislead. Use `Task` / signals for genuinely client-only data (a click, viewport, live updates). For SLOW data where blocking the first byte hurts, wrap the region in `<webjs-suspense .fallback=${html\`Loading...\`}>` to stream it (the only way to show a first-paint fallback; see `client-router-and-streaming.md`). Do NOT fetch in `connectedCallback` for data knowable server-side, and do NOT prop-drill what a leaf can fetch itself.
 
@@ -264,7 +264,56 @@ A component that does no client-side work renders the same SSR'd HTML with or wi
 - the dynamic slot READ surface (`slotchange`, `assignedNodes` / `assignedElements` / `assignedSlot`); merely RENDERING a `<slot>` does not ship (the SSR output carries the placed children, so a display-only slotted wrapper is byte-identical without its JS; native-write liveness is consumer-driven and the consumer's tag reference forces the ship)
 - being rendered by a component that itself ships
 
-A bare `async render()` (no other signal, light DOM) is elided too: the SSR'd data is the complete first paint. Force shipping with `static interactive = true` when interactivity is invisible to static analysis (a dynamically-built tag string, a `:defined` rule in an external stylesheet). `static shadow = true` always ships (Declarative Shadow DOM re-attaches only during parsing). Turn elision off app-wide with `{ "webjs": { "elide": false } }` or `WEBJS_ELIDE=0`.
+A bare `async render()` (no other signal, light DOM) is elided too: the SSR'd data is the complete first paint. Force shipping with `static interactive = true` when interactivity is invisible to static analysis. `static shadow = true` always ships (Declarative Shadow DOM re-attaches only during parsing). Turn elision off app-wide with `{ "webjs": { "elide": false } }` or `WEBJS_ELIDE=0`.
+
+### What `static interactive = true` does and does not rescue
+
+The analyser reads source lexically, so a few real shapes escape it. The override covers them:
+
+- **An OBSERVER that computes the tag it waits for.** `customElements.whenDefined(TAG)` where `TAG` is a variable does not name a tag the analyser can resolve, so the observed component is elided, its `register` never runs, and the `await` never settles. Put `static interactive = true` on the OBSERVED component.
+- **A `:defined` rule in an external stylesheet.** `public/app.css` is not in the module graph, so a `my-badge:defined { … }` rule is invisible. Same fix, on the component the rule names.
+- **A consumer that reaches the element through a string selector.** The analyser matches `whenDefined` / `:defined` / `instanceof`, so a `document.querySelector('my-wrapper')` consumer escapes all three. Same fix, on the component being reached.
+
+**It does NOT rescue a component whose OWN registration tag is computed.** `Badge.register(TAG)` is not a registration the scanner recognises (invariant 3 requires a literal tag), so that component is never in the component set at all: it gets no verdict, nothing consults the analyser for it, and the override has nothing to attach to. The registration still runs if the module reaches the browser, so what you ALWAYS lose is the verdict, the tag-to-module registry entry, and the preload hint. Whether the element upgrades depends on one thing: the importing module has to ship WHOLE. An inert, import-only, or elided importer is dropped from the boot and takes the import with it, and then the element never registers at all. A page rendering a real component alongside the orphan is import-only unless it ALSO does its own client work, so shipping whole is the narrower case: assume the element does not upgrade. Always pass a literal: `Badge.register('my-badge')`.
+
+`webjs dev` warns, and `webjs elision` / `webjs doctor` report it, as an **orphan**. That name covers TWO shapes and they fail differently, so read the warning carefully: a computed tag is the case above, while a class with NO registration call anywhere in the app is the plainer one (someone forgot to register it), and that element never upgrades. The check is app-wide, so registering the class from a sibling module is fine and is not reported. Both lose the verdict, the registry entry, and the preload hint.
+
+### Inspecting and proving the verdict
+
+Elision is the one thing WebJs decides about your code that you did not write down, so it is inspectable rather than something to reason about from the rules above.
+
+```sh
+webjs elision                      # per-module verdict, and the evidence behind every ship
+webjs elision --json               # the same object, for a tool or an agent
+webjs elision --verify             # prove elision changed nothing your app serves
+webjs elision --verify --routes /,/blog/hello   # add paths (the only way to cover a dynamic route)
+```
+
+**Reading the report.** Every component is `elided` or `shipped`. A shipped one carries the `evidence` that forced it, first match wins:
+
+| `evidence` | Means | `by` |
+|---|---|---|
+| `own` | its own source carries a signal; `reason` is the exact one | null |
+| `observed` | another module observes its registration (`whenDefined` / `:defined` / `instanceof`) | the observer |
+| `closure` | something it imports does client work | the import |
+| `render` | a shipping component can render its tag | that component |
+| `import` | a shipping component imports it | that component |
+| `unreadable` | its source could not be read, so it ships conservatively | null |
+
+An elided row carries no reason on purpose: elision is the ABSENCE of every signal, so there is no positive fact to report.
+
+**What to do with each verdict.** `elided` on a component you believe is interactive is the one result worth acting on: find the signal it is missing (the list above), and if the interactivity is genuinely invisible to static analysis, add `static interactive = true`. `shipped` with an `evidence` you did not expect is usually a `closure` row, and the fix is to move the client-effecting import out of that component's path. An `orphans` row is always a bug, and the fix depends on which shape it is: give the class a literal registration tag if its tag is computed, or add the missing `Class.register('my-tag')` call if there is none at all (delete the class instead if nothing uses it).
+
+**What `--verify` proves.** It renders every static page route with elision on and off and diffs the bytes with the JS-loaded set masked out, which is the framework's own guard pointed at your app. So it proves elision did not change what your app SERVES. It does not prove post-hydration behaviour, because a wrongly dropped module shows up as a dead click, not as different bytes. Cover that half by running your own browser or e2e suite twice:
+
+```sh
+WEBJS_ELIDE=1 npm run test:e2e
+WEBJS_ELIDE=0 npm run test:e2e
+```
+
+It exits non-zero on a divergence AND on a corpus where nothing could be compared, so it is safe to put in CI. The ON side is forced on rather than read from your config, so the comparison is a real one even in an app that has elision switched off, and the run reports how many modules elision actually dropped so a trivially-true pass is visible. Dynamic routes are skipped by name (rendering one would mean inventing param values); pass real ones with `--routes`. A route whose two same-side renders already differ is reported as nondeterministic and excluded, since a differential over live data proves nothing.
+
+`webjs doctor` carries the same verdict as a one-line inventory, and warns only on an orphan.
 
 ## Members app code must not shadow
 

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

@@ -135,7 +135,7 @@ import { createPost } from '#modules/posts/actions/create-post.server.ts';
 html`<form action=${createPost}><input name="title"></form>`;
 ```
 
-The renderer omits the `action` attribute so the form posts to the page's own url, supplies `method="post"` and an enctype, and emits a hidden `__webjs_action` field carrying the action's `<hash>/<fn>` identity, the same identity the RPC endpoint resolves. Nothing about the action's source reaches the browser. With JS off this is an ordinary HTML submission; with JS the client router posts the same body to the same url, so the two paths are identical by construction.
+The renderer omits the `action` attribute so the form posts to the page's own url, supplies `method="post"` and an enctype, and emits a hidden `__webjs_action` field carrying the action's `<hash>/<fn>` identity, the same identity the RPC endpoint resolves. Nothing about the action's source reaches the browser. With JS off this is an ordinary HTML submission; with JS the client router posts the same body to the same url, encoded per the declared `enctype` (#1307: multipart stays `FormData`, urlencoded, which is the HTML default, is sent as `URLSearchParams`), so the two paths are identical by construction.
 
 **A form-bound action always receives the `FormData`**, which is where it differs from the same function called over RPC (rich arguments) or server-to-server. `validate` is the typing seam: it takes the `FormData` and its transform-return becomes the action's typed input.
 
@@ -236,3 +236,55 @@ import { posts } from '#db/schema.server.ts';
 ```
 
 Keep the wire shape in a browser-safe `modules/<feature>/types.ts` with NO runtime import from a `.server.ts` file or from `db/`. Define a hand-written DTO, or a type-only derivation (`import type { Post } ...; export type PostFormatted = Omit<Post, 'createdAt'> & { createdAt: string }`). Never `export *` or a value re-export from a `.server.ts` in `types.ts`; that carries the runtime table bindings and breaks any component importing the types. Full reference at https://webjs.dev/docs.
+
+## SSR action seeding, and how to tell it is working
+
+When a shipping component's `async render()` awaits an action during SSR, WebJs serializes that result into the page and the generated RPC stub reads it on its FIRST client call. So `const u = await getUser(this.id)` runs once, on the server, and hydration reuses the result with no network round-trip.
+
+**You write nothing for this.** It is automatic, on by default, and there is no API to call. The only thing you can do is break it, so the section below is about noticing when you have.
+
+### The correctness boundary
+
+A seed hit returns the value the SSR render that produced this page computed for exactly this action, function, and argument list, so a hit cannot show the user something different from the HTML they are already looking at. A page navigation evicts whatever the outgoing page left unconsumed, both the block still in the DOM and anything already ingested from it, so a departed render's value is never served. On an HTML-cached page (`export const revalidate`) the seed rides inside the cached bytes, so it is exactly as fresh as the HTML it came with. A miss simply re-fetches.
+
+There is one shape where a hit can differ from the paint, and WebJs warns about it in dev: **an action that returns a DIFFERENT result for the SAME arguments twice in one render.** The seed carries the last result while the first component painted the first one. So keep an action deterministic for a given argument list. A counter, a `Math.random()`, a `new Date()` in the return value, or a read of mutable module state all break that rule, and dev prints:
+
+```
+[webjs] SSR action seeding: "getUser" returned two DIFFERENT results for the SAME arguments during one render. ...
+```
+
+The fix is to make the action deterministic, or to move the varying part into an argument so the two calls get different keys.
+
+### Reading the dev diagnostics
+
+A miss is invisible from the outside: the page still renders correctly, it just pays a round-trip per async component on every first load. Two channels make it visible in dev, and neither exists in production.
+
+**Server side, per request.** The `X-Webjs-Seed` response header, also folded into the dev access-log line as a `seed` field:
+
+| Value | What it means |
+|---|---|
+| `off` | Seeding is switched off (`"webjs": { "seed": false }` or `WEBJS_SEED=0`). Not a defect. |
+| `html-cache` | The #241 HTML response cache answered. The seeds rode inside the cached bytes. |
+| `collected=3, emitted=3` | Healthy. Three action results were captured and all three reached the page. |
+| `collected=3, emitted=0` | The serializer threw and dropped the whole block. Something in a returned value is not serializer-safe. |
+| `collected=3, emitted=0, streamed` | The page streams, so nothing could be emitted (see below). |
+
+Check it with `curl -sSI localhost:3000/` or in the network tab.
+
+**Browser side, per page view.** One `console.warn` at the first idle after hydration, and only when a call missed AND the client can be certain why. It stays silent otherwise, including on a page that emitted no seeds at all: every action call routes through the seed lookup, including ones that were never SSR-invoked and never could have been seeded (a mutation, a `Task` autorun, a `connectedCallback` read), so a miss there is not evidence of a defect. That case is the server header's job, where `collected=0` is unambiguous. The line names one of these:
+
+- *"This page streams"*, so no seeds could be emitted. Expected, not a bug (see below).
+- *"The page's seeds could not be serialized."* Something an action returned is not serializer-safe, so the whole block was dropped. The response header shows `collected` above `emitted` for the same reason.
+- *"The page seeded these actions under DIFFERENT arguments."* The key is `hash(action file) / function name / serialized arguments`, so the client asked with an argument the SSR render never used. Common cause: the component computes its argument from browser-only state (a `localStorage` read, a `connectedCallback` assignment), which the server render could not have known. A miss on an action the page never seeded at all is NOT reported, because a mutation or a client-only read routes through the same lookup and could never have been seeded.
+
+A miss AFTER hydration is correct and is not reported: the seed is consume-once, so a deliberate refetch or an argument change is supposed to go to the network.
+
+`seedStats()` from `@webjsdev/core` returns `{ ingested, replaced, hits, misses, keyMisses, pending }` (`keyMisses` being the provable subset of `misses`, a call for an action the page seeded under other arguments) if you want to assert this in a browser test or read it from the console. A non-zero `pending` at rest usually means the seeding component ELIDED, so its module never shipped and nothing on the client was ever going to consume the seed. `pending` covers the page you are on: a page navigation evicts whatever the outgoing page left unconsumed, both the block still sitting in the DOM and anything already ingested from it, since those values belong to a render no longer on screen.
+
+### The streamed-page exception
+
+A page carrying a `Suspense` or `<webjs-suspense>` boundary emits NO seed block at all, not just none for the streamed region: a streamed render's deferred boundaries resolve after the first flush, so their results cannot ride the block. Every action call on that page goes to the network on hydration. That is a real trade, so make it deliberately: reach for a streaming boundary when a slow region would otherwise block the first byte, and leave a fast page buffered so it seeds.
+
+### Switching it off
+
+`"webjs": { "seed": false }` in `package.json`, or `WEBJS_SEED=0`. The client then re-fetches on hydration exactly as it did before the feature, and stale-while-revalidate hides the flicker. Turn it off only to isolate a problem; there is no reason to ship with it off.

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

@@ -64,7 +64,21 @@ html`<form action=${saveDraft}>
 </form>`;
 ```
 
-The identity rides the pressed button's own `name`/`value` pair, which a browser submits for that button alone, so this works with JS off exactly as it does with JS on. Both entries reach the server and the LAST wins, which is always the submitter's when one was pressed. The submitter must be a `<button>` and cannot carry its own `name`, `value`, or `form` attribute, because the identity already occupies that pair. `<input type="submit">` is refused for the binding: the identity has to occupy its `value`, which on that control is also the visible caption, so the button would render captioned with the action id and could never be labelled. A `<button>` has no such conflict, since its label is its children.
+The identity rides the pressed button's own `name`/`value` pair, which a browser submits for that button alone, so this works with JS off exactly as it does with JS on. Both entries reach the server and the LAST wins, which is always the submitter's when one was pressed.
+
+**A bound submitter is self-sufficient, so the enclosing form does not have to be bound** (#1307). The renderer puts `formmethod="post"` and `formenctype="multipart/form-data"` on the button itself, alongside the identity, exactly as React emits `formMethod` and `formEncType` on a button carrying a function `formAction`. 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:
+
+```js
+// Every button below submits a POST its action can read, with JS on or off.
+html`<form>
+  <button formaction=${saveDraft}>Save</button>
+  <button formaction=${publishPost}>Publish</button>
+</form>`;
+```
+
+One consequence worth knowing rather than discovering: no `formaction` url is emitted (an empty one is an HTML conformance error), so the submission targets whatever the FORM targets. A form declaring its own `action="/x"` sends its buttons to `/x`, which is native precedence. The action still runs if `/x` is a PAGE route, because the identity travels in the body, but against a `route.ts` or another origin the identity is ignored and nothing runs. In dev the client logs a warning at submit time naming the url. Leaving the form's `action` off, the ordinary shape, keeps the submission on the current page.
+
+The submitter must be a `<button>` and cannot carry its own `name`, `value`, or `form` attribute, because the identity already occupies that pair. `<input type="submit">` is refused for the binding: the identity has to occupy its `value`, which on that control is also the visible caption, so the button would render captioned with the action id and could never be labelled. A `<button>` has no such conflict, since its label is its children.
 
 **Only the bare, unquoted `action=${fn}` on a `<form>` binds.** Every near-miss is a hard render error rather than a silently-inert form, and the reason is a source leak. During SSR a `.server.ts` import is the ACTUAL function (the RPC stub exists only in the browser), and `action=` is an ordinary attribute hole, so stringifying it would write the function's body into the HTML every visitor downloads, including any literal inside it. The renderer throws instead, on the server and on the client, for `action=` and `formaction=` alike.
 
@@ -95,21 +109,21 @@ The bound, refused, and allowed shapes in full. Every "no" row is a binding that
 | `action=${fn}` unquoted, on a `<form>` | **no, it BINDS** | the one supported shape: the identity is resolved and emitted as a hidden field, nothing is stringified |
 | `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 inside a bound form | **no, it BINDS** | the second supported shape (#1207). The identity rides the button's own `name`/`value` pair, the one channel a browser submits for the pressed button alone, so no `formaction` url is emitted and the server takes the LAST `__webjs_action` entry |
-| `formaction=${fn}` inside an UNBOUND `<form>` | yes | `method="post"` and the enctype are forced on the FORM's start tag, which SSR has already emitted by the time it reaches the button, so a per-button action cannot retrofit them |
+| `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 form other than the bound one it sits in, so the boundness just checked was about the wrong element |
-| `formmethod="get"` / `formenctype="text/plain"` on ANY submitter inside a bound form | yes | this is the Part B rule, and it applies whether or not that button binds an action of its own: a GET sends no body and `text/plain` is not parseable, so the submission works under JS (the router posts `FormData`) and 405s without it |
+| `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 |
+| `formmethod` / `formenctype` the BOUND submitter cannot submit with (`get`, `PATCH`, `text/plain`, `dialog`, a padded `" post "`) | yes | a same-element contradiction: you attached an action to THIS button and told THIS button to submit in a way that action could never read. The renderer supplies `formmethod="post"` and the enctype only where you supplied neither, so your own parseable value always wins |
+| `formmethod="get"` / `formenctype="text/plain"` on a PLAIN submitter inside a bound form | **no** | #1307 reversed this. Native HTML says the submitter's override wins, you typed it deliberately, and the form's action simply does not run, exactly as the same markup behaves anywhere else. In dev the client logs a console error at submit time if the submission is carrying an identity it cannot deliver |
 | `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 its own `formmethod` is the author's business and Part B leaves it alone |
+| 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 |
 | `.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 |
 | `method=" post "` / `enctype=" multipart/form-data "` | yes | `method` and `enctype` are enumerated attributes matched against exact keywords with no whitespace stripping, so a padded value falls to the invalid-value default and the form submits as a GET with no body. Trimming it for you would emit the padded value anyway |
 | `encoding="..."` as an ATTRIBUTE on a bound form | **no** | inert in HTML (`form.encoding` reads back `enctype`), so both renderers ignore it and still supply `enctype`. Only the `.encoding` PROPERTY aliases enctype, and that spelling IS refused, one row up |
-| `.formAction=` on a button or input | yes | same reason, that is where `formAction` reflects |
+| `.formAction=` / `.formMethod=` / `.formEnctype=` on a BOUND submitter | yes | same reason, that is where they reflect: SSR drops the property and the browser applies it, so the button would submit one way with JS and another way without. On a PLAIN button they are ordinary native properties and are left alone |
 | `.action=` on any other native tag | **no** | a plain expando (`<div .action=${fn}>`, `<button .action=${fn}>`), reflecting nothing, so nothing reaches the markup |
 | `.action=` on a custom element | **no** | an author-defined property, not a reflected IDL attribute, so a function is a legitimate value. One declared `reflect: true` reflects on a path outside these commit sites, which used to write `String(value)` and emit the source. It now removes the attribute and warns instead, for a bare function and for an array carrying one, unless the prop supplies its own `converter.toAttribute`, which runs first and stays the author's call |
 | `?action=` | yes | a function never leaked through a boolean hole, but the binding is meaningless, so it is refused rather than emitting the bare `action=""` that ANY truthy value produces there. Two separate facts worth carrying: `action=""` is a conformance error (the spec wants a valid non-empty URL whenever the attribute is present), and deleting the attribute is still not the WebJs fix, since a page has no `action` export and an unbound `method="post"` form is a 405 (a bare GET form just re-renders). Bind it: `<form action=${fn}>` |
@@ -170,6 +184,12 @@ The file stays `middleware.ts`, NOT Next 16's renamed `proxy.ts`. WebJs middlewa
 
 Navigation is automatic. The client router auto-enables when `@webjsdev/core` loads (any page with a component), so a plain `<a href>` gets soft navigation for free. There is no `<Link>` to import and no `useRouter`. For programmatic navigation import `navigate()` / `revalidate()` from `@webjsdev/core`. There is no `next/image`, `next/font`, `next/script`, or `next/dynamic`. WebJs is no-build: use a plain `<img>`, a `<link>` / `@font-face`, a component's `static lazy = true` for viewport lazy-loading, and a dynamic `import()` where code should load lazily.
 
+### No `<ScrollRestoration>`, and no scroll restore of your own
+
+Remix ships a `<ScrollRestoration />` component, Next has a `scrollRestoration` flag and a pile of community `useEffect` + `scrollTo` recipes, and every one of them is a thing to NOT port. WebJs restores scroll on Back/Forward automatically: the router sets `history.scrollRestoration = 'manual'` on boot and is the sole authority on scroll for the whole navigation. There is no component to render and no option to enable. An app-level `popstate` listener that calls `scrollTo`, a remembered offset in `sessionStorage`, or a `scrollIntoView` on a saved element all race the router and win sometimes, which is worse than losing consistently.
+
+This includes the case that most tempts a hand-rolled fix: Back landing BELOW where the reader left, on a page whose components size themselves after they render. The router already handles it, by suppressing the browser's scroll anchoring across the restore so late growth above the viewport is not added to the offset it just replayed (see `client-router-and-streaming.md`). If a restore still lands wrong, report it rather than patching around it in app code.
+
 ### Server-only code: the `.server.ts` boundary, not a `server-only` package
 
 Next poisons a client-imported module with the `server-only` package. WebJs uses the file extension: `*.server.ts` is the path-level boundary (the file router refuses to serve the source). A `'use server'` file's exports are RPC-callable; a `.server.ts` file WITHOUT `'use server'` is a server-only utility whose browser import throws at load. Reach a no-`'use server'` utility through a `'use server'` action, `route.ts`, or `middleware`, never by direct import into a shipping page or component.

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

@@ -104,7 +104,7 @@ render() {
 
 `method` and the enctype are supplied by the renderer, and the hidden identity field is re-inserted as the form's first child on every client render, so there is nothing to manage by hand.
 
-When a page owns SEVERAL mutations (create, toggle, delete), give each form its OWN binding (`action=${createTodo}` / `action=${toggleTodo}` / `action=${deleteTodo}`), or use per-button submitter server action bindings via `formaction=${action}` on submitter buttons inside a bound form (#1207). Alternatively, a form that dispatches dynamically can bind ONE action and inspect a submit button's `name="intent"`.
+When a page owns SEVERAL mutations (create, toggle, delete), give each form its OWN binding (`action=${createTodo}` / `action=${toggleTodo}` / `action=${deleteTodo}`), or use per-button submitter server action bindings via `formaction=${action}` on submitter buttons (#1207, #1307: a bound submitter carries its own submission, so the enclosing form need not be bound). Alternatively, a form that dispatches dynamically can bind ONE action and inspect a submit button's `name="intent"`.
 
 ## Seed the list from the server for SSR plus optimistic
 

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

@@ -179,7 +179,7 @@ Three responses that are not the happy path:
 
 The submission is Origin-verified (the same `Sec-Fetch-Site` / `Origin` check the RPC endpoint applies), so a no-JS form needs no CSRF token field.
 
-Refusals worth knowing: `formaction=${fn}` is supported only on a `<button>` inside a bound form, and that button may not carry `name`, `value`, `form`, or a static `formaction` attribute (`<input type="submit">` is refused, because the identity needs its `value`, which is also its label). A bound form may not declare `method="get"`, and a function bound to `action=` that is not a `'use server'` export throws at render rather than producing a form that posts nowhere. See `muscle-memory-gotchas.md` for the full table.
+Refusals worth knowing: `formaction=${fn}` is supported on a `<button>` anywhere, bound form or not (#1307: the renderer gives the button its own `formmethod` and `formenctype`), and that button may not carry `name`, `value`, `form`, or a static `formaction` attribute (`<input type="submit">` is refused, because the identity needs its `value`, which is also its label). A bound form may not declare `method="get"`, and a function bound to `action=` that is not a `'use server'` export throws at render rather than producing a form that posts nowhere. See `muscle-memory-gotchas.md` for the full table.
 
 ## Error, loading, and 404 boundaries
 

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

@@ -170,6 +170,25 @@ A cross-runtime proof is often a plain assert script rather than a test file, so
 - **Assert the exit code, never the logs.** These scripts conventionally pass a `quiet` logger, so anything that only logs is invisible. If your script catches its own failure, report it with an explicit `process.exit(1)` rather than a `console.error` alone, guarded as `if (import.meta.main) process.exit(1); else throw failure;`. The guard matters when a `.test.mjs` wrapper imports the script under `node --test`: an unguarded exit kills the whole single-process run and hides every other file's results, while the throw lets the harness report one failed test.
 - **Prove the script can FAIL before you trust it passing.** Break one assertion on purpose and confirm the run exits non-zero. A proof that cannot go red is worse than no proof: it reports success forever.
 
+## Proving display-only elision did not break anything
+
+WebJs strips the JavaScript of every component that does no client work, so a wrong verdict costs an app real interactivity and does it silently. Two commands cover the two halves, and you need both.
+
+```sh
+webjs elision --verify
+```
+
+renders every static page route with elision on and off and diffs the served bytes. It is the framework's own differential guard pointed at your route table, and it exits non-zero on a divergence AND on a corpus where nothing could be compared, so it belongs in CI. It forces the ON side on rather than reading your config, and reports how many modules elision actually dropped, so a pass that compared two identical renders is visible rather than silent. Dynamic routes are skipped by name; add real paths with `--routes /,/blog/hello`.
+
+That proves the bytes you SERVE did not change. It cannot prove post-hydration behaviour, because a wrongly dropped module shows up as a dead click, not as different bytes. Run your own browser or e2e suite twice for that half:
+
+```sh
+WEBJS_ELIDE=1 npm run test:e2e
+WEBJS_ELIDE=0 npm run test:e2e
+```
+
+A test that passes under one and fails under the other is a wrong verdict, and `webjs elision` tells you which module and on what evidence. If the component's interactivity is genuinely invisible to static analysis, the fix is `static interactive = true` on it; see `components.md` for what that override does and does not rescue.
+
 ## Convention validation (`webjs check`)
 
 `npm run check` is the correctness validator. Every rule catches code that is wrong to ship, a crash, a security leak, a reactive prop that silently stops re-rendering, or a type-strip failure. Run it and fix every violation before considering the change done (`npm run check -- --json` for an agent loop, `npm run check -- --rules` to list the rules). It is separate from `CONVENTIONS.md`, which carries the customizable project conventions you follow by judgment.

package/templates/gallery/modules/async-render/components/server-clock.ts

@@ -16,8 +16,9 @@ export class ServerClock extends WebComponent {
   // serves it with ZERO JavaScript and skips the redundant on-hydration
   // re-fetch. This is the common fetch-and-display leaf shape. If you ever need
   // to force a component to ship when the analyser would elide it (for
-  // interactivity static analysis cannot see, like a dynamically-computed tag
-  // string), declare `static interactive = true`.
+  // interactivity static analysis cannot see, like an observer that computes
+  // the tag it waits for), declare `static interactive = true`. Run
+  // `webjs elision` to see the verdict for every component in this app.
   async render() {
     const info = await serverGreeting();
     return html`<p class="font-mono text-sm">server rendered this at

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

@@ -12,9 +12,11 @@ import { deleteTodo } from './delete-todo.server.ts';
 // action: this form carries the todo's `id` on a hidden input and needs the
 // SAME id for whichever mutation runs, so one action reading both fields is the
 // simpler shape. When the buttons need no shared payload, bind each one
-// directly instead, with `formaction=${action}` on a <button> inside the bound
-// form. The identity then rides that button's own name/value pair, so it works
-// with JS off too. Two things to know: it must be a <button> (on an
+// directly instead, with `formaction=${action}` on a <button>. The enclosing
+// <form> does NOT have to be bound: a bound submitter carries its own
+// `formmethod` and enctype, so it works in any form or none. The identity rides
+// that button's own name/value pair, so it works with JS off too. Two things to
+// know: it must be a <button> (on an
 // <input type="submit"> the identity would occupy `value`, which is also that
 // control's visible label), and a bound submitter cannot carry its own
 // `name`/`value`, which is exactly the channel `name="intent"` uses below.