@webjsdev/server 0.8.59 → 0.8.60

package/index.d.ts

@@ -478,25 +478,114 @@ export declare function primeComponentRegistry(
 ): Promise<{ count: number }>;
 /** Extract `{ className, tag }` pairs from a component module's source. */
 export declare function extractComponents(src: string): Array<{ className: string; tag: string }>;
-/** Find component classes that no page / component imports (orphans). */
+/**
+ * Find ORPHAN component classes: a `class X extends WebComponent` that its own
+ * file declares and NOTHING in the app registers with a LITERAL tag, either
+ * because there is no registration call anywhere or because the tag is
+ * computed. The registration cross-reference is app-wide, so a class a sibling
+ * module registers is not an orphan. Neither is visible to the
+ * scanner, so both always lose the elision verdict, the tag-to-module registry
+ * entry, and the preload hint; assume the element does not upgrade either.
+ * This is about REGISTRATION, never about import reachability. The full
+ * semantics, including the one case where a computed tag still upgrades, live
+ * on `findOrphanComponents` in `src/component-scanner.js`.
+ */
 export declare function findOrphanComponents(
   appDir: string,
 ): Promise<Array<{ className: string; file: string }>>;
 
 // ---------------------------------------------------------------------------
-// elision-report.js (#646)
+// elision-report.js (#646, #1308)
 // ---------------------------------------------------------------------------
 
+/** Which rule in the analyser forced a component to ship. First match wins. */
+export type ElisionEvidence = 'own' | 'observed' | 'closure' | 'render' | 'import' | 'unreadable';
+
+/** One component module's verdict. `evidence` / `reason` / `by` are null when elided. */
+export interface ElisionComponentRow {
+  /** App-relative path of the component module. */
+  file: string;
+  /** Every tag this file registers, sorted. */
+  tags: string[];
+  verdict: 'elided' | 'shipped';
+  evidence: ElisionEvidence | null;
+  reason: string | null;
+  /** App-relative path of the module that forced the ship, where one did. */
+  by: string | null;
+}
+
+/** One page/layout route module's verdict. */
+export interface ElisionRouteModuleRow {
+  file: string;
+  verdict: 'inert' | 'import-only' | 'shipped';
+  /** For `import-only`: the component modules the boot emits in its place. */
+  emits: string[];
+  /** For `shipped`: the first client-effecting blocker, or null when its own code is the cause. */
+  blocker: string | null;
+  reason: string | null;
+}
+
+/** A `class X extends WebComponent` with no literal-tag registration. */
+export interface ElisionOrphanRow {
+  file: string;
+  className: string;
+}
+
+export interface ElisionSummary {
+  components: number;
+  elided: number;
+  shipped: number;
+  routeModules: number;
+  inert: number;
+  importOnly: number;
+  shippedWhole: number;
+  orphans: number;
+}
+
+/** The whole app-level elision verdict. Every path is app-relative; every array is sorted by `file`. */
+export interface ElisionReport {
+  analysed: boolean;
+  /** Why nothing was analysed, when `analysed` is false. */
+  skipped: 'no-app' | 'elide-off' | 'unanalysable' | null;
+  components: ElisionComponentRow[];
+  routeModules: ElisionRouteModuleRow[];
+  orphans: ElisionOrphanRow[];
+  summary: ElisionSummary;
+}
+
 /**
- * App-level elision report: the page/layout route modules that SHIP WHOLE to
- * the browser instead of being elided as carriers, each with the first
- * client-effecting blocker that pins it (or `null` when the module's own code
- * is the cause) plus a human reason. A reporting layer over `analyzeElision`,
- * consumed by the `webjs doctor` carrier-hygiene advisory (#646).
+ * App-level elision report, BOTH directions (#646, #1308): every component
+ * module as elided or shipped (a shipped one naming the evidence and the module
+ * that forced it), every page/layout as inert / import-only / shipped (a
+ * shipped one naming the first client-effecting blocker), and every orphan
+ * component class that gets no verdict at all. A reporting layer over
+ * `analyzeElision`, never a second analysis and never a build artifact.
+ * Consumed by `webjs elision`, the MCP `list_elision` tool, and both `webjs
+ * doctor` elision checks.
  */
-export declare function analyzeAppElision(
-  appDir: string,
-): Promise<{ analysed: boolean; shipped: Array<{ file: string; blocker: string | null; reason: string }> }>;
+export declare function analyzeAppElision(appDir: string): Promise<ElisionReport>;
+
+// ---------------------------------------------------------------------------
+// elision-differential.js (#1308)
+// ---------------------------------------------------------------------------
+
+/**
+ * Mask the JS-loaded set (importmap, boot script, modulepreload hints, vendor
+ * connection hints, content stamps) out of an SSR response so a diff sees only
+ * observable output. The ONE definition shared by the framework's own
+ * differential guard and `webjs elision --verify`, so an app can diff its own
+ * two captures with exactly the framework's comparator.
+ */
+export declare function maskJsSet(html: string): string;
+
+/**
+ * The URL paths of every STATIC page route in a `buildRouteTable` result,
+ * sorted and deduped. Dynamic routes are excluded (rendering one would mean
+ * inventing param values).
+ */
+export declare function staticPageRoutes(table: {
+  pages?: Array<{ routeDir?: string; paramNames?: string[] }>;
+}): string[];
 
 // ---------------------------------------------------------------------------
 // context.js (per-request context helpers)

package/index.js

@@ -44,6 +44,7 @@ export {
 export { buildModuleGraph, transitiveDeps } from './src/module-graph.js';
 export { scanComponents, primeComponentRegistry, extractComponents, findOrphanComponents } from './src/component-scanner.js';
 export { analyzeAppElision } from './src/elision-report.js';
+export { maskJsSet, staticPageRoutes } from './src/elision-differential.js';
 export { headers, cookies, getRequest, withRequest, cspNonce, requestId } from './src/context.js';
 export { defaultLogger } from './src/logger.js';
 export { rateLimit, parseWindow, clientIp, stampRemoteIp } from './src/rate-limit.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.59",
+  "version": "0.8.60",
   "type": "module",
   "description": "The server for WebJs, a full-stack JavaScript framework built on web components with server-side rendering and no build step. Provides the file-based router, SSR, server actions, route handlers, middleware, and live reload on Node 24+ or Bun.",
   "main": "index.js",
@@ -28,7 +28,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@webjsdev/core": "^0.7.47",
+    "@webjsdev/core": "^0.7.48",
     "ws": "^8.20.0"
   },
   "publishConfig": {

package/src/action-seed.js

@@ -75,6 +75,8 @@ const als = new AsyncLocalStorage();
 
 /** Whether seed COLLECTION is on (the `webjs.seed` switch). */
 let _seedEnabled = false;
+/** Dev mode, threaded from `dev.js` at boot. Gates the determinism assertion. */
+let _devMode = false;
 /** Whether the load hook is installed at all (so identity is available). */
 let _hookInstalled = false;
 /** Idempotency guard: `module.registerHooks` must run at most once. */
@@ -194,12 +196,50 @@ async function recordSeed(collector, file, fnName, args, value) {
   try {
     const hash = await actionFileHash(file);
     const argsKey = await stringify(args);
-    collector.set(`${hash}/${fnName}/${argsKey}`, value);
+    const key = `${hash}/${fnName}/${argsKey}`;
+    // Dev-only determinism assertion (#1309). A duplicate key means the SAME
+    // action ran twice with the SAME arguments in ONE render; the collector
+    // keeps the LAST result, so a component that painted the first one hydrates
+    // with the second. Compared on the FULL key, never on `hash/fn`: a
+    // legitimate second call with different arguments has a different key and
+    // cannot false-fire. In its OWN try/catch so a diagnostic failure can never
+    // skip `collector.set` and turn observability into a dropped seed.
+    if (_devMode && collector.has(key)) {
+      try { await assertDeterministic(collector.get(key), value, hash, fnName); } catch { /* never affect the seed */ }
+    }
+    collector.set(key, value);
   } catch {
     // Drop the seed; the client stub falls back to a normal RPC.
   }
 }
 
+/** Warned-once ids, keyed `hash/fn` so the Set is bounded by the action count. */
+const _nonDeterministic = new Set();
+
+/**
+ * Warn (once per action function) when one render recorded two DIFFERENT results
+ * for the same key. `Object.is` settles a memoized or cached return for free;
+ * the fallback compares through the SAME serializer the seed uses, so
+ * "different" means different on the wire, which is the only difference that can
+ * reach a client. Dev only, and only on a duplicate key.
+ * @param {unknown} prev
+ * @param {unknown} next
+ * @param {string} hash
+ * @param {string} fnName
+ */
+async function assertDeterministic(prev, next, hash, fnName) {
+  if (Object.is(prev, next)) return;
+  const id = `${hash}/${fnName}`;
+  if (_nonDeterministic.has(id)) return;
+  if ((await stringify(prev)) === (await stringify(next))) return;
+  _nonDeterministic.add(id);
+  console.warn(
+    `[webjs] SSR action seeding: "${fnName}" returned two DIFFERENT results for the SAME arguments during one render. `
+    + 'The seed carries the LAST result, so a component that painted the first one hydrates with the second. '
+    + 'Make the action deterministic for a given argument list, or turn seeding off with "webjs": { "seed": false }.',
+  );
+}
+
 /**
  * Register one exported action function's identity, and, when seeding is on,
  * wrap it so that a resolved result is recorded into an active collector.
@@ -599,11 +639,13 @@ function seedLoadHook(url, context, nextLoad) {
  * The hook installs whatever `seed` says, because action IDENTITY (#1155) rides
  * it and is not optional. `seed` gates only whether results are COLLECTED.
  *
- * @param {{ seed?: boolean }} [opts]
+ * @param {{ seed?: boolean, dev?: boolean }} [opts] `dev` gates the determinism
+ *   assertion in `recordSeed` (a console warning has no place in production).
  * @returns {Promise<void>}
  */
 export async function registerActionHooks(opts = {}) {
   _seedEnabled = opts.seed !== false;
+  _devMode = opts.dev === true;
   if (_registered) return;
   _registered = true;
 
@@ -644,6 +686,15 @@ export async function collectSeeds(fn) {
   return { value, collector };
 }
 
+/**
+ * The dev-only block emitted when the serializer THREW and the whole payload was
+ * dropped. Exported so the SSR emitter can tell it apart from a real block: it
+ * carries a marker so the browser can name the cause, but it ships NO seeds, so
+ * counting it as emitted would report a total success on the one failure the
+ * counts exist to expose.
+ */
+export const SEED_DROP_BLOCK = '<script type="application/json" id="__webjs-seeds" data-webjs-dev="drop">{}</script>';
+
 /**
  * Serialize a collector into a `<script type="application/json">` block to embed
  * in the page. Returns '' for an empty collector (so a render with no seeded
@@ -651,14 +702,21 @@ export async function collectSeeds(fn) {
  * format the RPC stub's `parse` reads) and HTML-escaped so it can never break out
  * of the script element. A `type="application/json"` script is DATA, not
  * executable JS, so it needs no CSP nonce.
- * @param {Map<string, unknown>} collector
+ * @param {Map<string, unknown> | null} collector
+ * @param {{ dev?: boolean, reason?: string }} [opts] in DEV, stamp a
+ *   `data-webjs-dev` marker and emit the block even when the collector is EMPTY.
+ *   The marker is the only dev signal the browser gets (#1309): a
+ *   `process.env.NODE_ENV` gate is a compile-time constant in the built core
+ *   bundle, so the client cannot decide this for itself. Emitting an empty block
+ *   in dev is what lets a page that seeded NOTHING still be reported on.
  * @returns {Promise<string>}
  */
-export async function buildSeedScript(collector) {
-  if (!collector || collector.size === 0) return '';
+export async function buildSeedScript(collector, opts = {}) {
+  const dev = opts.dev === true;
+  if ((!collector || collector.size === 0) && !dev) return '';
   try {
     const obj = {};
-    for (const [k, v] of collector) obj[k] = v;
+    if (collector) for (const [k, v] of collector) obj[k] = v;
     const payload = await stringify(obj);
     const safe = payload
       .replace(/</g, '\\u003c')
@@ -666,8 +724,18 @@ export async function buildSeedScript(collector) {
       .replace(/&/g, '\\u0026')
       .replace(/\u2028/g, '\\u2028')
       .replace(/\u2029/g, '\\u2029');
-    return `<script type="application/json" id="__webjs-seeds">${safe}</script>`;
+    // Attribute-safe by construction: `reason` is a framework literal ('ok' /
+    // 'streamed' / 'drop'), never app input, and is emitted only in dev.
+    const marker = dev ? ` data-webjs-dev="${opts.reason || 'ok'}"` : '';
+    return `<script type="application/json" id="__webjs-seeds"${marker}>${safe}</script>`;
   } catch {
+    // The serializer threw, so the whole block is dropped. This is the ONE
+    // failure the counting exists to expose (`collected` above `emitted`), and
+    // in prod it stays silent as before. In DEV emit a marker-only block so the
+    // browser can name it: with no marker at all the client opens no report
+    // window, so every missed hydration call on the page prints nothing, which
+    // is precisely the invisible failure this feature removes.
+    if (dev) return SEED_DROP_BLOCK;
     return '';
   }
 }

package/src/component-elision.js

@@ -145,9 +145,13 @@ export const CLIENT_METHOD_CALLS = ['addController', 'removeController', 'reques
  *   - `interactive`: `static interactive = true` is the explicit author
  *     override that forces a component to ship even when the analyser would
  *     elide it. It is the escape hatch for interactivity the analyser cannot
- *     see statically (a dynamically-computed tag string, a `:defined` rule in
- *     an external stylesheet outside the module graph). Context-free: any value
- *     other than `false` ships.
+ *     see statically (an OBSERVER that computes the tag it waits for, a
+ *     `:defined` rule in an external stylesheet outside the module graph, a
+ *     consumer reaching the element through a string selector). It
+ *     cannot rescue a component whose OWN registration tag is computed: the
+ *     scanner requires a literal tag (invariant 3), so such a component is
+ *     never in `components` at all and nothing consults this analyser for it.
+ *     Context-free: any value other than `false` ships.
  *
  * @type {readonly string[]}
  */
@@ -904,12 +908,12 @@ export async function computeElidableComponents(components, moduleGraph, readFil
  * global (`window`, `document`, …), or a shipping component. Anything
  * ambiguous or unreadable keeps shipping.
  *
- * @param {Array<{ tag: string, file: string }>} components
+ * @param {Array<{ tag: string, file: string, className?: string }>} components
  * @param {string[]} routeModules  absolute paths of page + layout files
  * @param {import('./module-graph.js').ModuleGraph} moduleGraph
  * @param {(file: string) => Promise<string>} readFileFn
  * @param {string} [appDir]
- * @returns {Promise<{ elidableComponents: Set<string>, inertRouteModules: Set<string>, importOnlyRouteModules: Map<string, string[]>, shippedRouteModules: Map<string, { blocker: string|null, reason: string }> }>}
+ * @returns {Promise<{ elidableComponents: Set<string>, inertRouteModules: Set<string>, importOnlyRouteModules: Map<string, string[]>, shippedRouteModules: Map<string, { blocker: string|null, reason: string }>, componentVerdicts: Map<string, { tags: string[], className: string|null, shipped: boolean, evidence: string|null, by: string|null, reason: string|null }> }>}
  */
 export async function analyzeElision(components, routeModules, moduleGraph, readFileFn, appDir) {
   /** @type {Set<string>} */
@@ -926,6 +930,23 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
 
   /** @type {Set<string>} */
   const mustShip = new Set();
+  /**
+   * WHY each shipping component ships (#1308), so the app-level report can name
+   * the evidence instead of only the verdict. Written alongside every
+   * `mustShip.add` of a COMPONENT file; FIRST write wins, matching the
+   * first-match convention the analyser uses everywhere else.
+   * @type {Map<string, { evidence: string, by: string|null, reason: string|null }>}
+   */
+  const shipEvidence = new Map();
+  /**
+   * @param {string} file      the component file that ships
+   * @param {string} evidence  one of own | observed | closure | render | import | unreadable
+   * @param {string|null} by   the module that forced it, where one exists
+   * @param {string|null} [reason]
+   */
+  const noteShip = (file, evidence, by, reason) => {
+    if (!shipEvidence.has(file)) shipEvidence.set(file, { evidence, by, reason: reason ?? null });
+  };
   /** @type {Map<string, Set<string>>} */
   const fileTags = new Map();
   /** @type {Set<string>} modules importing a reactive primitive from core */
@@ -939,6 +960,8 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
   /** @type {Set<string>} component files forced to ship because some module
    * observes their registration (whenDefined / :defined / instanceof). */
   const observedComponentFiles = new Set();
+  /** @type {Map<string, string>} observed component file -> the module observing it (#1308) */
+  const observedBy = new Map();
 
   /** @type {Set<string>} */
   const allFiles = new Set(componentFiles);
@@ -957,7 +980,7 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
     catch {
       // A component file we cannot read ships conservatively; a helper we
       // cannot read simply contributes no tags.
-      if (componentFiles.has(file)) mustShip.add(file);
+      if (componentFiles.has(file)) { mustShip.add(file); noteShip(file, 'unreadable', null, null); }
       continue;
     }
     if (typeof src !== 'string') continue;
@@ -989,8 +1012,9 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
         hasModuleScopeSideEffect(redacted, literals)) {
       clientGlobalOrBareFiles.add(file);
     }
-    if (componentFiles.has(file) && analyzeComponentSource(masked).interactive) {
-      mustShip.add(file);
+    if (componentFiles.has(file)) {
+      const v = analyzeComponentSource(masked);
+      if (v.interactive) { mustShip.add(file); noteShip(file, 'own', null, v.reason); }
     }
     // Cross-module registration observation (#169): if THIS module observes
     // another component's tag, that component must register client-side, so
@@ -999,13 +1023,13 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
     // (all components are known up front, but we collect here while we hold
     // each source). Verdict-safe: only ever forces MORE components to ship.
     for (const m of masked.matchAll(WHEN_DEFINED_RE)) {
-      const f = tagToFile.get(m[1]); if (f) observedComponentFiles.add(f);
+      const f = tagToFile.get(m[1]); if (f) { observedComponentFiles.add(f); if (!observedBy.has(f)) observedBy.set(f, file); }
     }
     for (const m of masked.matchAll(TAG_DEFINED_RE)) {
-      const f = tagToFile.get(m[1]); if (f) observedComponentFiles.add(f);
+      const f = tagToFile.get(m[1]); if (f) { observedComponentFiles.add(f); if (!observedBy.has(f)) observedBy.set(f, file); }
     }
     for (const m of masked.matchAll(INSTANCEOF_RE)) {
-      const f = classToFile.get(m[1]); if (f) observedComponentFiles.add(f);
+      const f = classToFile.get(m[1]); if (f) { observedComponentFiles.add(f); if (!observedBy.has(f)) observedBy.set(f, file); }
     }
   }
 
@@ -1013,7 +1037,7 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
   // render/import rules propagate from it too. Dynamic tag strings and external
   // (non graph-reachable) stylesheets remain an author-facing caveat, since
   // static analysis cannot see them.
-  for (const f of observedComponentFiles) mustShip.add(f);
+  for (const f of observedComponentFiles) { mustShip.add(f); noteShip(f, 'observed', observedBy.get(f) ?? null, null); }
 
   // Reverse import edges (who imports each file), built once from the graph.
   // Drives both the closure-client-work reachability below and the fixpoint's
@@ -1065,7 +1089,7 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
       if (!deps) continue;
       for (const dep of deps) {
         if (serverFiles.has(dep)) continue;
-        if (reachesClientWork.has(dep)) { mustShip.add(file); break; }
+        if (reachesClientWork.has(dep)) { mustShip.add(file); noteShip(file, 'closure', dep, null); break; }
       }
     }
   }
@@ -1108,14 +1132,14 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
     if (tags) {
       for (const tag of tags) {
         const childFile = tagToFile.get(tag);
-        if (childFile && !mustShip.has(childFile)) { mustShip.add(childFile); queue.push(childFile); }
+        if (childFile && !mustShip.has(childFile)) { mustShip.add(childFile); noteShip(childFile, 'render', node, null); queue.push(childFile); }
       }
     }
     const importers = importersOf.get(node);
     if (importers) {
       for (const imp of importers) {
         if (!componentFiles.has(imp)) continue;  // import rule is component -> component
-        if (!mustShip.has(imp)) { mustShip.add(imp); queue.push(imp); }
+        if (!mustShip.has(imp)) { mustShip.add(imp); noteShip(imp, 'import', node, null); queue.push(imp); }
       }
     }
   }
@@ -1146,6 +1170,41 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
     return 'does client work';
   };
 
+  // Per-component verdict plus the evidence that produced it (#1308). Assembled
+  // ENTIRELY from what the passes above already computed: nothing is re-read and
+  // nothing is re-analysed, so this is a projection, not a second analysis. A
+  // file may register more than one tag, so rows are keyed by FILE with a
+  // sorted tag list.
+  /** @type {Map<string, { tags: string[], className: string|null, shipped: boolean, evidence: string|null, by: string|null, reason: string|null }>} */
+  const componentVerdicts = new Map();
+  for (const c of components) {
+    let row = componentVerdicts.get(c.file);
+    if (!row) {
+      const shipped = mustShip.has(c.file);
+      const ev = shipped ? shipEvidence.get(c.file) : undefined;
+      row = {
+        tags: [], className: c.className ?? null, shipped,
+        evidence: ev ? ev.evidence : null,
+        by: ev ? ev.by : null,
+        // An ELIDED component carries no reason on purpose: elision is the
+        // ABSENCE of every signal, so there is no positive fact to report.
+        // A shipping component with no evidence is only reachable if a future
+        // rule adds to `mustShip` without calling `noteShip`, so report null
+        // rather than a wrong claim (sigil-coverage guards against that drift).
+        reason: !shipped || !ev ? null
+          : ev.evidence === 'own' ? ev.reason
+          : ev.evidence === 'observed' ? `its registration is observed by ${ev.by}`
+          : ev.evidence === 'closure' ? `its import ${ev.by} ${clientEffectReason(/** @type {string} */ (ev.by))}`
+          : ev.evidence === 'render' ? `${ev.by} ships and can render its tag`
+          : ev.evidence === 'import' ? `${ev.by} ships and imports it`
+          : 'its source could not be read (ships conservatively)',
+      };
+      componentVerdicts.set(c.file, row);
+    }
+    if (!row.tags.includes(c.tag)) row.tags.push(c.tag);
+  }
+  for (const row of componentVerdicts.values()) row.tags.sort();
+
   // Route modules fall into three classes by their effective client closure
   // (skipping elided components and server stubs, which never load on the
   // client):
@@ -1242,7 +1301,7 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
     }
   }
 
-  return { elidableComponents, inertRouteModules, importOnlyRouteModules, shippedRouteModules };
+  return { elidableComponents, inertRouteModules, importOnlyRouteModules, shippedRouteModules, componentVerdicts };
 }
 
 /** Match a whole-line side-effect import: `import './x.js';` (no bindings). */

package/src/component-scanner.js

@@ -7,15 +7,13 @@
  * renders a component tag, `lookupModuleUrl(tag)` already has the URL
  * ready for `<link rel="modulepreload">` hints.
  *
- * The convention WebJs uses is the web-standard one:
- *
- *     class Counter extends WebComponent { … }
- *     customElements.define('my-counter', Counter);
- *
- * The scanner looks for `customElements.define('<tag>', <ClassName>)`
- * calls: static text patterns that are cheap to regex-match without
- * a full TS parse. A full parse would be ~50× slower for no payoff;
- * we only need `{ tag, className, moduleUrl }` tuples.
+ * The idiomatic WebJs registration is `Class.register('my-counter')`; the
+ * web-standard `customElements.define('my-counter', Counter)` is equally
+ * supported. The scanner matches BOTH, as static text patterns that are cheap
+ * to regex-match without a full TS parse. A full parse would be ~50× slower
+ * for no payoff; we only need `{ tag, className, moduleUrl }` tuples. Either
+ * way the tag must be a LITERAL (invariant 3): a computed one is invisible
+ * here, which is what makes it an orphan (see `findOrphanComponents`).
  */
 
 import { readFile, stat } from 'node:fs/promises';
@@ -148,10 +146,36 @@ export async function primeComponentRegistry(appDir, components) {
 }
 
 /**
- * Find `class X extends WebComponent` (or its subclasses) declarations
- * that are NOT accompanied by a `customElements.define(tag, X)` call in
- * the same file. Lets the dev server warn authors early when they
- * forget the registration step.
+ * Find ORPHAN components: a `class X extends WebComponent` that NOTHING in the
+ * app registers with a LITERAL tag, via either `X.register('tag')` or
+ * `customElements.define('tag', X)`. The declaration is per-file, the
+ * registration cross-reference is app-wide.
+ *
+ * TWO shapes land here and they fail differently, so any message about this
+ * must cover both:
+ *
+ *   - No registration call ANYWHERE in the app (the forgot-to-register case).
+ *     Nothing ever registers the tag, so the element NEVER upgrades. The
+ *     cross-reference is app-wide precisely so a class registered by a sibling
+ *     module is not accused of this.
+ *   - A registration whose tag is COMPUTED (`X.register(TAG)`). That call is
+ *     ordinary code, so it runs IF the module reaches the browser, which
+ *     requires the importing module 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 does not upgrade either. Assume it does not. An
+ *     orphan is not in `componentFiles`, so it never joins the frontier an
+ *     import-only page emits in its place, and a page that renders a real
+ *     component alongside the orphan is import-only unless it ALSO does its
+ *     own client work (which ships it whole, #963). Shipping whole is the
+ *     narrower case, so treat the upgrade as lost until proven otherwise.
+ *
+ * Lost in EVERY case, whichever shape: the elision verdict, the tag-to-module
+ * registry entry, and the modulepreload hint. That, not the upgrade, is the
+ * part that is always true, and it is what every message about this should
+ * lead with.
+ *
+ * Matches the literal `extends WebComponent` only, so a class extending a
+ * component SUBCLASS is not reported.
  *
  * @param {string} appDir
  * @returns {Promise<Array<{ className: string, file: string }>>}
@@ -164,30 +188,62 @@ export async function findOrphanComponents(appDir) {
     !/\.(test|spec)\.m?[jt]sx?$/.test(p) &&
     !/\.server\.m?[jt]s$/.test(p);
 
+  // TWO passes, because registration is an APP-WIDE fact while the declaration
+  // is per-file. A class may legitimately be declared in one module and
+  // registered by a sibling (`customElements.define('my-badge', Badge)` in a
+  // separate file), which the scanner header calls equally supported and which
+  // `extractComponents` already picks up as a real component. Reporting it as
+  // an orphan is a FALSE positive, and a false warning on a legitimate pattern
+  // is exactly what makes an author stop reading the warnings.
+  //
+  // Trade-off, deliberate: the cross-reference is by class NAME, so two
+  // same-named classes in different files, one registered and one genuinely
+  // orphaned, hide the real orphan. That is rarer than the sibling-registration
+  // pattern and errs toward silence rather than toward a wrong accusation.
+  /** @type {Array<{ file: string, declared: Set<string> }>} */
+  const declaredPerFile = [];
+  /** @type {Set<string>} every class name registered ANYWHERE in the app */
+  const registeredAnywhere = new Set();
+
   for await (const file of walk(appDir, filter)) {
     let src;
     try { src = await readFile(file, 'utf8'); } catch { continue; }
+    // Scan REDACTED source, the same way `extractComponents` above does. A
+    // `class X extends WebComponent` written inside an `html` template or a
+    // string is a CODE SAMPLE (every docs page is full of them), not a real
+    // declaration, and reporting it as an unregistered component is a false
+    // orphan. Redaction blanks comments and swaps each string / template body
+    // for a `__STR_<idx>__` placeholder, so a genuine top-level declaration
+    // still matches while a sample inside a template does not. It does NOT
+    // preserve offsets (a placeholder is a different length than the body it
+    // replaces), which is fine here because an orphan is reported by class
+    // name and file, never by position. If this scan ever needs a line or
+    // column, reach for `redactStringsAndTemplates(src, true)`, WITH the
+    // blank-strings argument: the default form keeps plain-string bodies and
+    // single-line untagged templates verbatim, so a sample written either way
+    // would match again and the false orphan would be back.
+    const { redacted } = redactToPlaceholders(src);
     // Find every class that extends WebComponent (exact name: we trust
     // the framework convention).
     const classRe = /\b(?:export\s+)?(?:default\s+)?class\s+([A-Z][A-Za-z0-9_$]*)\s+extends\s+WebComponent\b/g;
-    // A class counts as "registered" if either Class.register('tag') or
-    // customElements.define('tag', Class) appears in the file.
-    const registerRe = /\b([A-Z][A-Za-z0-9_$]*)\.register\s*\(\s*['"][^'"]+['"]\s*\)/g;
-    const defineRe = /\bcustomElements\.define\s*\(\s*['"][^'"]+['"]\s*,\s*([A-Z][A-Za-z0-9_$]*)\b/g;
-
     const declared = new Set();
     let m;
-    while ((m = classRe.exec(src)) !== null) declared.add(m[1]);
-    if (declared.size === 0) continue;
+    while ((m = classRe.exec(redacted)) !== null) declared.add(m[1]);
 
-    const registered = new Set();
-    while ((m = registerRe.exec(src)) !== null) registered.add(m[1]);
-    while ((m = defineRe.exec(src)) !== null) registered.add(m[1]);
+    // "Registered" is whatever `extractComponents` accepts, reused rather than
+    // re-expressed. The two scans MUST agree on what a literal tag is: when
+    // this used its own looser pattern, a redacted interpolated template
+    // (`Class.register(\`${p}__STR_1__\`)`) satisfied the orphan scan but not
+    // `extractComponents`, so a computed template-literal tag was neither a
+    // component NOR an orphan and vanished from every surface, which is the
+    // exact shape the orphan report exists to catch.
+    for (const c of extractComponents(src)) registeredAnywhere.add(c.className);
+    if (declared.size) declaredPerFile.push({ file, declared });
+  }
 
+  for (const { file, declared } of declaredPerFile) {
     for (const cls of declared) {
-      if (!registered.has(cls)) {
-        orphans.push({ className: cls, file });
-      }
+      if (!registeredAnywhere.has(cls)) orphans.push({ className: cls, file });
     }
   }
   return orphans;