@webjsdev/server 0.8.58 → 0.8.60

package/src/dev.js

@@ -15,7 +15,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { buildRouteTable, matchPage, matchApi } from './router.js';
 import { generateRouteTypes } from './route-types.js';
 import { ssrPage, ssrNotFound, setClientRouterEnabled } from './ssr.js';
-import { loadPageAction, runPageAction } from './page-action.js';
+import { runFormAction, reportFormSubmittedAsGet } from './form-dispatch.js';
 import { handleApi } from './api.js';
 import {
   buildActionIndex,
@@ -26,7 +26,7 @@ import {
   hasUseServerDirective,
   hashFile,
 } from './actions.js';
-import { registerSeedHooks } from './action-seed.js';
+import { registerActionHooks } from './action-seed.js';
 import { readRegenerateRules, maybeRegenerate, isRegenerateOutputPath } from './dev-regenerate.js';
 import { stripTypeScript, ensureStripper } from './ts-strip.js';
 import { defaultLogger } from './logger.js';
@@ -93,7 +93,8 @@ import { setVendorEntries, setCoreInstall, publishBuildId, setAppSourceId, setBa
 import { readBasePath, stripBasePath, withBasePath } from './base-path.js';
 import { propagateTrustedRemoteIp } from './rate-limit.js';
 import { readAllowedOrigins } from './csrf.js';
-import { setAssetUrlProvider } from '@webjsdev/core';
+import { setAssetUrlProvider, setFormActionResolver } from '@webjsdev/core';
+import { resolveActionIdentity } from './form-action-identity.js';
 import { setAssetRoots, clearAssetHashCache, setElisionFingerprint, withAssetHash, assetHashFor, versionModuleImports, resolveAssetUrl } from './asset-hash.js';
 import { urlFromRequest } from './forwarded.js';
 import { compileHeaderRules, applySecurityHeaders, webRequestIsHttps } from './headers.js';
@@ -640,13 +641,17 @@ export async function createRequestHandler(opts) {
   // never touched the disk.
   setAssetUrlProvider((p) => resolveAssetUrl(p, basePath()));
 
-  // SSR action-result seeding (#472). Install the process-global module load
-  // hook NOW, at boot, before any `'use server'` action module is imported (ESM
-  // caches by URL, so a module loaded before the hook would never be faceted).
-  // Read once (not per-rebuild): the hook is global and cannot be cleanly
-  // un-installed, so toggling needs a restart. Disabled -> no hook, no ambient
-  // collector wrap in ssr.js, and module loading stays byte-identical.
-  if (await readSeedEnabled(appDir)) await registerSeedHooks();
+  // The `'use server'` load hook. Install it NOW, at boot, before any action
+  // module is imported (ESM caches by URL, so a module loaded before the hook
+  // would never be wrapped). Read once (not per-rebuild): the hook is global
+  // and cannot be cleanly un-installed, so toggling needs a restart.
+  //
+  // It installs UNCONDITIONALLY, and only seed collection (#472) follows the
+  // `webjs.seed` switch. Action identity (#1155) rides the same hook, and it is
+  // what a bound `<form action=${action}>` resolves through, so gating the hook
+  // on seeding would mean `webjs.seed: false` silently broke every no-JS form.
+  await registerActionHooks({ seed: await readSeedEnabled(appDir), dev });
+
 
   // When an app commits a vendor pin (.webjs/vendor/importmap.json) it carries a
   // deterministic vendor map that is cheap to read (one file, no analysis, no
@@ -757,7 +762,7 @@ export async function createRequestHandler(opts) {
   // package.json `webjs.maxBodyBytes` / `webjs.maxMultipartBytes` plus the env
   // overrides. The secure defaults (1 MiB JSON/RPC, 10 MiB form) apply when
   // unconfigured. Stamped on every request via `setBodyLimits` so `readBody`
-  // (used inside route handlers) enforces the same cap the RPC and page-action
+  // (used inside route handlers) enforces the same cap the RPC and form-dispatch
   // paths do.
   const bodyLimits = await readBodyLimitsFromApp(appDir);
 
@@ -797,14 +802,27 @@ export async function createRequestHandler(opts) {
     regenerateRules: dev ? await readRegenerateRules(appDir) : [],
   };
 
+  // Teach the renderers how to turn a real server-action function into the
+  // `<hash>/<fn>` identity a form submits (#1155). The hook path is
+  // process-global and needs no index; `state.actionIndex` is consulted only as
+  // a hash memo, and by the scan fallback for a runtime with no hook. In a
+  // process running several handlers the fallback therefore resolves against
+  // the most recently booted one, which is the same scope the asset-url
+  // provider already has.
+  setFormActionResolver((fn) => (state.actionIndex ? resolveActionIdentity(state.actionIndex, fn) : null));
+
   /**
    * Report a dev error (#264): build a frame and push it to the open tab via
    * the SSE overlay channel. DEV-ONLY and best-effort, so it can never affect a
    * response or crash the server (a frame-build failure is swallowed). No file
    * path or source is ever built in prod (the early return), so nothing leaks.
    *
+   * `info.url` stamps a `render` frame with the URL that produced it (#1047), so
+   * the browser overlay can refuse a frame for a page the tab is not viewing.
+   * A `ts-strip` / `rebuild` frame passes none and stays unscoped.
+   *
    * @param {unknown} error
-   * @param {{ kind?: 'render'|'ts-strip'|'rebuild', file?: string, line?: number, column?: number, hint?: string }} [info]
+   * @param {{ kind?: 'render'|'ts-strip'|'rebuild', file?: string, line?: number, column?: number, hint?: string, url?: string }} [info]
    */
   function reportDevError(error, info = {}) {
     if (!dev) return;
@@ -891,10 +909,14 @@ export async function createRequestHandler(opts) {
             // Client-router opt-out (#629): re-read each pass so toggling
             // `webjs.clientRouter` takes effect on rebuild without a restart.
             setClientRouterEnabled(await readClientRouterEnabled(appDir));
-            const r = (await readElideEnabled(appDir))
+            // Read the switch ONCE: the dev summary below reports it too, and
+            // calling readElideEnabled twice per warm re-reads package.json.
+            const elideOn = await readElideEnabled(appDir);
+            const r = elideOn
               ? await analyzeElision(components, collectRouteModules(state.routeTable),
                   state.moduleGraph, (f) => readFile(f, 'utf8'), appDir)
-              : { elidableComponents: new Set(), inertRouteModules: new Set(), importOnlyRouteModules: new Map() };
+              : { elidableComponents: new Set(), inertRouteModules: new Set(), importOnlyRouteModules: new Map(),
+                  shippedRouteModules: new Map(), componentVerdicts: new Map() };
             state.elidableComponents = r.elidableComponents;
             state.inertRouteModules = r.inertRouteModules;
             state.importOnlyRouteModules = r.importOnlyRouteModules;
@@ -964,12 +986,40 @@ export async function createRequestHandler(opts) {
             }
             t.elision = now() - m;
             if (dev) {
+              // An orphan is EITHER shape `findOrphanComponents` reports: no
+              // registration call at all, or one whose tag is computed. The
+              // scanner matches only a literal tag, so it sees neither, and
+              // what is ALWAYS lost is the verdict, the registry entry, and the
+              // preload hint. The upgrade is the part that differs, and a
+              // computed tag only survives when its importer ships WHOLE (see
+              // findOrphanComponents for why that is the exception). The doctor
+              // check and `webjs elision` say the same thing.
               for (const { className, file } of await findOrphanComponents(appDir)) {
                 logger.warn?.(
-                  `[webjs] ${className} extends WebComponent but has no customElements.define(...) call in ${file}. ` +
-                    `Add \`customElements.define('<tag-name>', ${className});\` or <${kebab(className)}> tags won't upgrade.`,
+                  `[webjs] ${className} extends WebComponent but is never registered with a literal tag in ${file} ` +
+                    `(either there is no registration call, or its tag is computed), so the scanner cannot see it: ` +
+                    `no elision verdict, no registry entry, no preload hint. ` +
+                    `<${kebab(className)}> tags never upgrade with no registration call, and a computed tag ` +
+                    `upgrades only while its importing module ships whole. ` +
+                    `Add \`${className}.register('<tag-name>');\` with a literal tag.`,
                 );
               }
+              // The elision summary (#1308), one server-console line. NOT a
+              // browser push: an inert route ships zero application JS, and the
+              // most useful manual check an author has is opening the network
+              // tab on that route and seeing nothing, which a dev-only boot
+              // script would corrupt on exactly the pages this proves. The fact
+              // is also app-wide while a browser channel is per-tab, and the
+              // per-page detail already has a home in `webjs elision`.
+              // Re-emitted after each fs.watch rebuild, because doRebuild sets
+              // analysisDone = false and this sits inside that stage.
+              logger.info?.(
+                elideOn
+                  ? `[webjs] elision: ${r.elidableComponents.size}/${new Set(components.map((c) => c.file)).size} components elided, ` +
+                    `${r.inertRouteModules.size} route modules inert, ${r.importOnlyRouteModules.size} import-only, ` +
+                    `${r.shippedRouteModules.size} ship whole. Run \`webjs elision\` for the per-module verdict.`
+                  : `[webjs] elision: disabled (WEBJS_ELIDE / webjs.elide), every module ships.`,
+              );
             }
             analysisDone = true;
             ranAnalysis = true;
@@ -1181,7 +1231,7 @@ export async function createRequestHandler(opts) {
 
       // Make the resolved body-size limits (issue #237) readable from the
       // request scope, so `readBody` inside a route handler enforces the same
-      // cap the framework's own RPC / page-action body reads do.
+      // cap the framework's own RPC / form-dispatch body reads do.
       setBodyLimits(state.bodyLimits);
 
       let pathname = '/';
@@ -1298,12 +1348,18 @@ export async function createRequestHandler(opts) {
       // root-mounted `/__webjs/*`. The logged `path` stays the RAW client URL.
       if (shouldAccessLog(headerPathname)) {
         try {
+          // #1309: fold the dev-only seeding counters into the ONE access-log
+          // line rather than adding a second one. Present only on a response
+          // that carried the header, so only page renders gain the field and
+          // production is unchanged.
+          const seed = dev ? conditioned.headers.get('x-webjs-seed') : null;
           logger.info?.('request', {
             requestId: reqId,
             method: req.method,
             path: pathname,
             status: conditioned.status,
             durationMs: Math.round((performance.now() - startedAt) * 100) / 100,
+            ...(seed ? { seed } : {}),
           });
         } catch { /* never let logging crash the response */ }
       }
@@ -1349,7 +1405,7 @@ export async function createRequestHandler(opts) {
             // to the inbound `x-webjs-remote-ip` header that the copied
             // `req.headers` still carries, which a client can spoof. So strip
             // that header on the rebuild and propagate the framework-trusted IP
-            // across the new object, the same pattern page-action.js uses.
+            // across the new object, the same pattern form-dispatch.js uses.
             const headers = new Headers(req.headers);
             headers.delete('x-webjs-remote-ip');
             const hasBody = req.method !== 'GET' && req.method !== 'HEAD';
@@ -1461,7 +1517,7 @@ export async function createRequestHandler(opts) {
       // Build all whole-app analysis on the first request (memoized), before
       // any SSR, module serve, gate check, action dispatch, or middleware runs.
       await ensureReady();
-      const next = () => handleCore(req, { state, appDir, coreDir, dev, reportError, reportDevError, cspEnabled: cspConfig.enabled, allowedOrigins: allowedOriginsValue });
+      const next = () => handleCore(req, { state, appDir, coreDir, dev, reportError, reportDevError, hasOnError, logger, cspEnabled: cspConfig.enabled, allowedOrigins: allowedOriginsValue });
       if (state.middleware) {
         try {
           return await state.middleware(req, next);
@@ -1839,7 +1895,7 @@ function startNodeListener(ctx) {
   // Catch-all process handlers: log, but don't tear the process down on a
   // single mishandled promise. Uncaught exceptions are different: state may be
   // corrupted, so log + start an orderly shutdown rather than continuing.
-  installProcessHandlers(logger, () => shutdown('uncaughtException'));
+  installProcessHandlers(logger, () => shutdown('uncaughtException', { fatal: true }));
 
   return {
     server,
@@ -1958,7 +2014,7 @@ async function tryServeFrameworkStatic(path, method, ctx) {
 }
 
 async function handleCore(req, ctx) {
-  const { state, appDir, coreDir, dev, reportError, reportDevError, cspEnabled, allowedOrigins } = ctx;
+  const { state, appDir, coreDir, dev, reportError, reportDevError, hasOnError, logger, cspEnabled, allowedOrigins } = ctx;
   const url = new URL(req.url);
   // Decode percent-encoded characters so filesystem lookups match real
   // filenames. Dynamic route segments like `[slug]` and route groups like
@@ -2179,14 +2235,30 @@ async function handleCore(req, ctx) {
   }
 
   // Page route. GET/HEAD render the page. A NON-GET/HEAD method (POST/PUT/…)
-  // is only routed here when the page module exports an `action` (#244); the
-  // action runs inside the page's segment middleware, then either PRG-redirects
-  // (303) on success, re-renders the same page (422) with field errors on
-  // failure, or honors a thrown redirect()/notFound(). Without an `action`
-  // export, a non-GET/HEAD request falls through to the 404 below, unchanged.
+  // is a form submission (#1155): the `__webjs_action` hidden field names the
+  // server action to run, it runs inside the page's segment middleware, and the
+  // result either PRG-redirects (303), re-renders the same page (422) with
+  // field errors, or honors a thrown redirect()/notFound(). A non-GET carrying
+  // no action identity is a 405 on a path that exists but only renders.
   {
     const page = matchPage(state.routeTable, path);
     if (page) {
+      // The URL this render is FOR, in the form the browser sees it (#1047), so
+      // the overlay's scope gate can compare it against `location.pathname +
+      // location.search`. Two details are load-bearing: the RAW `url.pathname`
+      // (not the decoded `path`) is used, because `location.pathname` is
+      // percent-encoded too; and the base path is put back, because the ingress
+      // strip already removed it from `url` while the browser's location still
+      // carries it, so without this the gate would suppress every overlay on a
+      // sub-path deploy.
+      const devErrorUrl = withBasePath(url.pathname, basePath()) + url.search;
+      // A speculative link prefetch must never raise an overlay (#1047): the
+      // user is only hovering a link to a page that throws, and the page they
+      // are actually looking at is fine. Dropping the hook also keeps the throw
+      // out of `state.lastDevError`, so the SSE replay cannot hand it to a
+      // freshly-connected tab either. The APM `onError` sink below still fires,
+      // because the render really did throw.
+      const isPrefetch = req.headers.get('x-webjs-prefetch') === '1';
       const ssrOpts = {
         dev, appDir, moduleGraph: state.moduleGraph,
         serverFiles: state.actionIndex.fileToHash,
@@ -2213,17 +2285,58 @@ async function handleCore(req, ctx) {
         // Dev error overlay (#264): a render crash pushes a frame to the open
         // tab. Dev-only (reportDevError early-returns in prod), so no source
         // leaks. Distinct from onError (the APM sink), which always fires.
-        onDevError: dev ? (e) => reportDevError(e, { kind: 'render' }) : undefined,
+        onDevError: dev && !isPrefetch
+          ? (e) => reportDevError(e, { kind: 'render', url: devErrorUrl })
+          : undefined,
       };
       if (method === 'GET' || method === 'HEAD') {
-        const handler = () => ssrPage(page.route, page.params, url, { ...ssrOpts, req });
-        return runWithSegmentMiddleware(req, page.route.middlewares, handler, dev);
-      }
-      const loaded = await loadPageAction(page.route.file, dev);
-      if (loaded) {
-        const handler = () => runPageAction(page.route, page.params, url, loaded, req, ssrOpts);
+        // #1307: `__webjs_action` in the QUERY STRING means a submission
+        // carrying a bound action's identity went out as a GET, so the action
+        // never ran. Nothing else in the framework puts that reserved field in
+        // a url. Detect only, so the render below is unchanged: answering a GET
+        // differently because of a query parameter would hand any visitor a way
+        // to turn any page into an error.
+        reportFormSubmittedAsGet(
+          url, req,
+          // Gated on hasOnError, not on `reportError`: that is always a
+          // function here and no-ops internally, so passing it would spend a
+          // dedupe slot on a report nobody receives.
+          hasOnError ? (e) => reportError(e, req, 'action') : undefined,
+          logger, dev, page.route,
+        );
+        // A successful render of URL U supersedes a RETAINED render error for
+        // that same URL (#1047), so a reconnecting tab is not handed a frame the
+        // page has since recovered from. Keyed on BOTH frame identity and url:
+        // identity so a frame this very render just reported is never wiped, url
+        // so a good render of an unrelated page cannot erase an error that is
+        // still current for the page the user is looking at (the #893 gap the
+        // retention exists to close). Dev-only, and skipped for a prefetch,
+        // which is not the user's view of anything.
+        const handler = dev && !isPrefetch
+          ? async () => {
+            const before = state.lastDevError;
+            const resp = await ssrPage(page.route, page.params, url, { ...ssrOpts, req });
+            if (
+              before && state.lastDevError === before
+              && before.kind === 'render' && before.url === devErrorUrl
+            ) state.lastDevError = null;
+            return resp;
+          }
+          : () => ssrPage(page.route, page.params, url, { ...ssrOpts, req });
         return runWithSegmentMiddleware(req, page.route.middlewares, handler, dev);
       }
+      // Every non-GET/HEAD to a page runs the page's segment middleware, and
+      // the dispatcher always answers with a Response (a 405 when there is no
+      // action to run), so a middleware that post-processes `await next()`
+      // never has to handle an absent one.
+      const deps = {
+        actionIndex: state.actionIndex,
+        allowedOrigins,
+        onError: hasOnError ? (e) => reportError(e, req, 'action') : undefined,
+        logger,
+      };
+      const handler = () => runFormAction(page.route, page.params, url, req, ssrOpts, deps);
+      return runWithSegmentMiddleware(req, page.route.middlewares, handler, dev);
     }
   }
 
@@ -2845,6 +2958,11 @@ function __webjsApplyError(data) {
   let f; try { f = JSON.parse(data); } catch (_) { return; }
   renderDevOverlay(f);
 }
+// Keep the overlay tracking the page actually on screen (#1047): a render frame
+// is scoped to the URL that produced it, so navigating away takes it down, and a
+// frame that arrived before the URL advanced goes up once it does. The gate
+// itself lives inside renderDevOverlay, so __webjsApplyError needs no change.
+installDevOverlayNavSync();
 // Never reload INTO a server that is still restarting (Node's node --watch
 // briefly kills the process on an edit), which would paint a style-less,
 // half-rendered page (#893). Probe the lightweight /__webjs/version endpoint

package/src/elision-differential.js

@@ -0,0 +1,101 @@
+/**
+ * The differential-elision primitives, shared by the framework's own guard and
+ * by the app-facing one (#1308).
+ *
+ * Elision's defining invariant is that removing the elided JS NEVER changes
+ * observable output. `packages/server/test/elision/differential-elision.test.js`
+ * proves that for the blog corpus by rendering every route with elision ON and
+ * OFF and diffing the bytes with the JS-loaded set masked out. `webjs elision
+ * --verify` runs the identical comparison over an arbitrary app's own route
+ * table, so every app gets the framework's own guard rather than inheriting a
+ * guarantee it cannot verify locally.
+ *
+ * `maskJsSet` therefore lives HERE and not in either consumer: it is the
+ * definition of "the JS-loaded set", and two copies is the one way the two
+ * guards could silently disagree about what the invariant even means.
+ *
+ * A leaf module: `node:path` is not even needed, and nothing here reads the
+ * filesystem or builds a graph.
+ */
+
+/**
+ * Mask the JS-loaded set so the diff sees only observable output. The
+ * importmap, the boot module script, and the modulepreload hints are
+ * REMOVED (not placeheld) because their COUNT differs on vs off, and the
+ * build-id hash is derived from them; collapsing whitespace afterwards
+ * means the differing-length preload block in the head leaves no trace. The
+ * two responses come from the identical SSR template pipeline, so any
+ * legitimate text/whitespace is the same on both sides regardless.
+ *
+ * Because the whole JS-loaded set is masked BY CONSTRUCTION, only the
+ * DANGEROUS direction (elision changed what the SSR emits) can fail a diff
+ * built on this. The SAFE direction (over-ship) lives entirely inside the
+ * masked region and is invisible here, by design.
+ *
+ * @param {string} html
+ * @returns {string}
+ */
+export function maskJsSet(html) {
+  return html
+    .replace(/<script type="importmap"[\s\S]*?<\/script>/g, '')
+    .replace(/<script type="module"[\s\S]*?<\/script>/g, '')
+    .replace(/<link rel="modulepreload"[^>]*>/g, '')
+    // The auto vendor preconnect / dns-prefetch (#243) is a connection-warming
+    // HINT derived from the served vendor map, which legitimately differs on vs
+    // off (a vendor reachable only through an elided component is pruned on the
+    // ON side, so its preconnect drops too, exactly like its modulepreload). It
+    // is part of the same JS-loaded set, so mask it. The blog corpus declares
+    // no `metadata.preconnect` of its own, so every preconnect/dns-prefetch
+    // there is the auto vendor one.
+    .replace(/<link rel="preconnect"[^>]*>/g, '')
+    .replace(/<link rel="dns-prefetch"[^>]*>/g, '')
+    .replace(/ data-webjs-build="[^"]*"/g, '')
+    .replace(/ data-webjs-src="[^"]*"/g, '')
+    // Render-clock nondeterminism: a page that SSRs a live wall-clock time
+    // ("posts loaded · 3:10:10 AM") ticks between the on and off captures. This
+    // is unrelated to elision (elision never changes rendered text), so
+    // normalise it. The counterfactual in differential-elision.test.js still
+    // fails because a removed element is a structural change, not a clock tick.
+    .replace(/\b\d{1,2}:\d{2}:\d{2}\s?[AP]M\b/gi, 'TIME')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/**
+ * The URL paths of every STATIC page route in a route table, sorted and
+ * deduped. The corpus `webjs elision --verify` renders on both sides.
+ *
+ * A DYNAMIC route is excluded rather than guessed at: rendering it would mean
+ * inventing param values, and a route that 404s or throws on invented params
+ * proves nothing. The command reports the excluded routes by name and takes
+ * `--routes` for an author who wants to cover them with real values.
+ *
+ * Normalization is `routePathFromDir`'s, restated here so this leaf does not
+ * depend on `@webjsdev/mcp`: a route group `(group)` and a `_private` segment
+ * drop out of the URL, and the root `.` is `/`.
+ *
+ * @param {{ pages?: Array<{ routeDir?: string, paramNames?: string[] }> }} table  a `buildRouteTable(appDir)` result
+ * @returns {string[]}
+ */
+export function staticPageRoutes(table) {
+  const out = new Set();
+  for (const r of table?.pages || []) {
+    if (r.paramNames && r.paramNames.length) continue;
+    out.add(routePath(r.routeDir));
+  }
+  return [...out].sort();
+}
+
+/**
+ * `blog` -> `/blog`, the root `.` -> `/`. Route groups and `_private` segments
+ * drop, the same normalization `buildRouteTable` uses for matching.
+ * @param {string|undefined} routeDir
+ * @returns {string}
+ */
+function routePath(routeDir) {
+  if (!routeDir || routeDir === '.') return '/';
+  const segs = routeDir
+    .split('/')
+    .filter((s) => !(s.startsWith('(') && s.endsWith(')')) && !s.startsWith('_'));
+  return segs.length ? '/' + segs.join('/') : '/';
+}

package/src/elision-report.js

@@ -1,49 +1,82 @@
 /**
- * App-level elision report (#646).
+ * App-level elision report (#646, extended in #1308).
  *
  * A reporting layer over the `analyzeElision` verdict, NOT a second analysis
  * and NOT a build (WebJs is no-build; elision is the server's analysis pass,
  * run at dev-server start and re-derived after each fs.watch rebuild). It
- * builds the module graph, runs `analyzeElision`, and returns the page / layout
- * route modules that SHIP WHOLE to the browser, each with the first
- * client-effecting blocker that pins it (a non-component on a component-free
- * path from the module, #963, or its own signal when the module itself is
- * the cause).
+ * builds the module graph, runs `analyzeElision` ONCE, and projects the whole
+ * verdict into a sorted, app-relative, JSON-serializable object.
  *
- * Consumed by `webjs doctor` to ADVISE why a page/layout is not elided (an
- * import-only #605 / inert #179 carrier stays out of the browser; a module that
- * ships whole does not). Advisory only: a page legitimately MAY ship, and the
- * analyser is biased toward shipping by design (server AGENTS invariant 7), so
- * this never fails anything.
+ * It carries BOTH directions:
+ *
+ *   - `components`: every component module with `elided` or `shipped`, and for
+ *     a shipped one the evidence that forced it plus the module that did the
+ *     forcing. This is the direction where a wrong verdict silently loses
+ *     interactivity in production, and before #1308 an app had no way to ask
+ *     "what did you drop from my page?".
+ *   - `routeModules`: every page / layout as `inert` / `import-only` /
+ *     `shipped`, a module that ships whole naming the first client-effecting
+ *     blocker that pins it (a non-component on a component-free path from the
+ *     module, #963, or its own signal when the module itself is the cause).
+ *   - `orphans`: a `class X extends WebComponent` with no literal-tag
+ *     registration, either because there is no registration call or because
+ *     the tag is computed. The scanner never sees it (invariant 3 requires a
+ *     literal tag), so it always loses its elision verdict, its tag-to-module
+ *     registry entry, and its preload hint, and `static interactive = true`
+ *     cannot rescue it. Whether the ELEMENT still upgrades differs by shape:
+ *     with no registration call it never does, and with a computed tag only
+ *     while its importing module ships WHOLE, which is the exception rather
+ *     than the rule. It is the one shape the verdict cannot speak for.
+ *
+ * Consumed by `webjs elision` (the CLI report + `--json`), the MCP
+ * `list_elision` tool, and `webjs doctor`'s two elision checks, which share
+ * ONE call so the module graph is built once per doctor run. Advisory only: a
+ * page legitimately MAY ship, and the analyser is biased toward shipping by
+ * design (server AGENTS invariant 7), so this never fails anything.
+ *
+ * Nothing is cached here. Every out-of-process consumer runs the analysis once
+ * and exits, so a cache would never hit and would only add a staleness bug.
  */
 import { readFile, stat } from 'node:fs/promises';
-import { join } from 'node:path';
+import { join, relative, sep } from 'node:path';
 
 import { buildModuleGraph } from './module-graph.js';
-import { scanComponents } from './component-scanner.js';
+import { scanComponents, findOrphanComponents } from './component-scanner.js';
 import { buildRouteTable } from './router.js';
 import { analyzeElision } from './component-elision.js';
 
+/**
+ * @typedef {'own'|'observed'|'closure'|'render'|'import'|'unreadable'} ElisionEvidence
+ * @typedef {{ file: string, tags: string[], verdict: 'elided'|'shipped', evidence: ElisionEvidence|null, reason: string|null, by: string|null }} ElisionComponentRow
+ * @typedef {{ file: string, verdict: 'inert'|'import-only'|'shipped', emits: string[], blocker: string|null, reason: string|null }} ElisionRouteModuleRow
+ * @typedef {{ file: string, className: string }} ElisionOrphanRow
+ * @typedef {{ components: number, elided: number, shipped: number, routeModules: number, inert: number, importOnly: number, shippedWhole: number, orphans: number }} ElisionSummary
+ * @typedef {{ analysed: boolean, skipped: 'no-app'|'elide-off'|'unanalysable'|null, components: ElisionComponentRow[], routeModules: ElisionRouteModuleRow[], orphans: ElisionOrphanRow[], summary: ElisionSummary }} ElisionReport
+ */
+
 /**
  * @param {string} appDir
- * @returns {Promise<{ analysed: boolean, shipped: Array<{ file: string, blocker: string|null, reason: string }> }>}
+ * @returns {Promise<ElisionReport>}
  */
 export async function analyzeAppElision(appDir) {
   // No `app/` means this is not a routable app (a bare component library, a
-  // lib-only fixture); nothing ships, so there is nothing to advise on.
-  if (!(await pathExists(join(appDir, 'app')))) return { analysed: false, shipped: [] };
-  // Elision off (opt-out) ships everything by design, so the advisory is moot.
-  if (!(await readElideEnabled(appDir))) return { analysed: false, shipped: [] };
+  // lib-only fixture); nothing ships, so there is nothing to report on.
+  if (!(await pathExists(join(appDir, 'app')))) return empty('no-app');
+  // Elision off (opt-out) ships everything by design, so the verdict is moot.
+  if (!(await readElideEnabled(appDir))) return empty('elide-off');
 
-  let moduleGraph, components, routeTable;
+  let moduleGraph, components, routeTable, orphans;
   try {
     moduleGraph = await buildModuleGraph(appDir);
     components = await scanComponents(appDir);
     routeTable = await buildRouteTable(appDir);
+    // Not a second elision analysis: a lexical scan for the one shape elision
+    // never gets to judge, reusing what the dev server already runs.
+    orphans = await findOrphanComponents(appDir);
   } catch {
-    // A malformed app the analysis cannot process degrades to no advice (the
+    // A malformed app the analysis cannot process degrades to no report (the
     // dev server and `webjs check` surface the real problem).
-    return { analysed: false, shipped: [] };
+    return empty('unanalysable');
   }
 
   // Exactly the page + layout set the dev server feeds to analyzeElision, so
@@ -55,16 +88,86 @@ export async function analyzeAppElision(appDir) {
     for (const f of page.layouts || []) routeModuleSet.add(f);
   }
 
-  const { shippedRouteModules } = await analyzeElision(
-    components, [...routeModuleSet], moduleGraph, (f) => readFile(f, 'utf8'), appDir,
-  );
+  const { inertRouteModules, importOnlyRouteModules, shippedRouteModules, componentVerdicts } =
+    await analyzeElision(components, [...routeModuleSet], moduleGraph, (f) => readFile(f, 'utf8'), appDir);
+
+  const rel = (f) => (f == null ? null : relative(appDir, f) || f);
+  const byFile = (a, b) => a.file.localeCompare(b.file);
+
+  /** @type {ElisionComponentRow[]} */
+  const componentRows = [...componentVerdicts.entries()].map(([file, v]) => ({
+    file: /** @type {string} */ (rel(file)),
+    tags: v.tags,
+    verdict: v.shipped ? 'shipped' : 'elided',
+    evidence: v.shipped ? /** @type {ElisionEvidence|null} */ (v.evidence) : null,
+    reason: v.shipped ? relativizeReason(v.reason, appDir) : null,
+    by: v.shipped ? rel(v.by) : null,
+  })).sort(byFile);
+
+  /** @type {ElisionRouteModuleRow[]} */
+  const routeRows = [
+    ...[...inertRouteModules].map((f) => ({
+      file: /** @type {string} */ (rel(f)), verdict: /** @type {const} */ ('inert'), emits: [], blocker: null, reason: null,
+    })),
+    ...[...importOnlyRouteModules].map(([f, emits]) => ({
+      file: /** @type {string} */ (rel(f)), verdict: /** @type {const} */ ('import-only'),
+      emits: emits.map((e) => /** @type {string} */ (rel(e))).sort(), blocker: null, reason: null,
+    })),
+    ...[...shippedRouteModules].map(([f, v]) => ({
+      file: /** @type {string} */ (rel(f)), verdict: /** @type {const} */ ('shipped'), emits: [],
+      blocker: rel(v.blocker), reason: relativizeReason(v.reason, appDir),
+    })),
+  ].sort(byFile);
+
+  /** @type {ElisionOrphanRow[]} */
+  const orphanRows = orphans
+    .map((o) => ({ file: /** @type {string} */ (rel(o.file)), className: o.className }))
+    .sort((a, b) => byFile(a, b) || a.className.localeCompare(b.className));
 
-  const shipped = [...shippedRouteModules.entries()].map(([file, v]) => ({
-    file,
-    blocker: v.blocker,
-    reason: v.reason,
-  }));
-  return { analysed: true, shipped };
+  return {
+    analysed: true, skipped: null,
+    components: componentRows, routeModules: routeRows, orphans: orphanRows,
+    summary: {
+      components: componentRows.length,
+      elided: componentRows.filter((c) => c.verdict === 'elided').length,
+      shipped: componentRows.filter((c) => c.verdict === 'shipped').length,
+      routeModules: routeRows.length,
+      inert: inertRouteModules.size,
+      importOnly: importOnlyRouteModules.size,
+      shippedWhole: shippedRouteModules.size,
+      orphans: orphanRows.length,
+    },
+  };
+}
+
+/**
+ * The no-verdict report, naming WHY nothing was analysed so a machine consumer
+ * can tell "elision is switched off" from "this is not an app".
+ * @param {'no-app'|'elide-off'|'unanalysable'} skipped
+ * @returns {ElisionReport}
+ */
+function empty(skipped) {
+  return {
+    analysed: false, skipped,
+    components: [], routeModules: [], orphans: [],
+    summary: { components: 0, elided: 0, shipped: 0, routeModules: 0, inert: 0, importOnly: 0, shippedWhole: 0, orphans: 0 },
+  };
+}
+
+/**
+ * `analyzeElision` bakes ABSOLUTE paths into its reason phrases (it works in
+ * absolute paths throughout). No absolute filesystem path may reach the JSON
+ * contract, so strip the app dir prefix wherever it appears in the sentence.
+ * A plain split/join rather than a regex, so an appDir containing regex
+ * metacharacters (a `(group)` directory, a `+`) is safe.
+ *
+ * @param {string|null} reason
+ * @param {string} appDir
+ * @returns {string|null}
+ */
+function relativizeReason(reason, appDir) {
+  if (reason == null) return null;
+  return reason.split(appDir.endsWith(sep) ? appDir : appDir + sep).join('');
 }
 
 /** Mirror of the dev server's elide flag: WEBJS_ELIDE override, then webjs.elide. */