@webjsdev/server 0.8.32 → 0.8.34

package/src/component-elision.js

@@ -42,8 +42,9 @@ import {
   matchClosingBrace,
   redactStringsAndTemplates,
   maskComments,
+  redactToPlaceholders,
 } from './js-scan.js';
-import { transitiveDeps } from './module-graph.js';
+import { transitiveDeps, expandImportAlias } from './module-graph.js';
 
 /**
  * Named imports from a `@webjsdev/core` specifier that imply the
@@ -215,8 +216,30 @@ const COMPONENT_CLIENT_GLOBAL_RE = /\b(?:window|document|navigator|localStorage|
  *
  * @param {string} src raw module source
  */
-function hasModuleScopeSideEffect(src) {
-  const redacted = redactStringsAndTemplates(src);
+/**
+ * Constructors that produce inert DATA with no side effect, so a module-scope
+ * `export const X = new Set([...])` (a lookup table, a compiled RegExp, a
+ * parsed URL) is not client work and must not pin an importing page/layout
+ * (#623). Any constructor NOT in this set (`new WebSocket()`, `new Worker()`,
+ * `new EventSource()`, `new Audio()`) IS a side effect and still ships.
+ */
+const PURE_DATA_CONSTRUCTORS = new Set([
+  'Set', 'Map', 'WeakSet', 'WeakMap', 'Date', 'RegExp', 'Array', 'Object',
+  'Number', 'String', 'Boolean', 'BigInt', 'Symbol',
+  'Error', 'TypeError', 'RangeError', 'SyntaxError',
+  'URL', 'URLSearchParams', 'ArrayBuffer', 'DataView',
+  'Int8Array', 'Uint8Array', 'Uint8ClampedArray', 'Int16Array', 'Uint16Array',
+  'Int32Array', 'Uint32Array', 'Float32Array', 'Float64Array',
+  'BigInt64Array', 'BigUint64Array',
+]);
+
+function hasModuleScopeSideEffect(src, literals) {
+  let redacted = src;
+  if (!literals) {
+    const r = redactToPlaceholders(src);
+    redacted = r.redacted;
+    literals = r.literals;
+  }
   // Keep only depth-0 text (outside every `{}`). Skip quoted-string bodies so
   // braces/parens inside a string neither desync the depth nor read as a call.
   let depth = 0;
@@ -252,9 +275,16 @@ function hasModuleScopeSideEffect(src) {
   // Optional-chaining call/index: `foo?.()`, `x?.[i]()` (the `?.` defeats the
   // identifier-before-paren match below).
   if (/\?\.\s*[([]/.test(frame)) return true;
-  // Top-level `new` (a `new X()` constructor also trips the call check, but a
-  // `new X` without parens would not) and top-level `await`.
-  if (/(?<![.\w])(?:new|await)\s/.test(frame)) return true;
+  // Top-level `new X`: a pure-data builtin constructor (Set / Map / Date /
+  // RegExp / typed array / URL / ...) is inert module data, not client work, so
+  // it stays elidable (#623); any other constructor is a side effect. Catches
+  // both `new X` and `new X(...)` (the constructor's own `(`, if present, is
+  // then skipped in the call scan below).
+  for (const nm of frame.matchAll(/(?<![.\w])new\s+([A-Za-z_$][\w$]*)/g)) {
+    if (!PURE_DATA_CONSTRUCTORS.has(nm[1])) return true;
+  }
+  // Top-level `await`.
+  if (/(?<![.\w])await\s/.test(frame)) return true;
   // A call: `(` preceded (ignoring whitespace) by an identifier, `)`, or `]`.
   const CALL_RE = /(?:([A-Za-z_$][\w$]*)|[)\]])\s*\(/g;
   // Identifiers that precede a `(` WITHOUT it being a call (keywords + a
@@ -274,6 +304,19 @@ function hasModuleScopeSideEffect(src) {
     if (ident && /\bfunction\s*\*?\s*$/.test(frame.slice(0, m.index))) continue;
     // The component registration call is the one permitted top-level call.
     if (ident === 'register' || ident === 'define') continue;
+    // `extends WebComponent({ … })` is the declare-free reactive-prop DX (#597
+    // / #599): a class-declaration construct, not an independent side-effecting
+    // statement. Exempt it so a display-only factory-form component stays
+    // elidable; a genuinely interactive one still ships via the per-class and
+    // module-level signal checks below (events, slots, shadow, lifecycle, a
+    // non-state factory prop, a reactive import). Scoped to the `extends`
+    // position, so a top-level `WebComponent(...)` call used anywhere else
+    // still counts as a side effect (#604).
+    if (ident === 'WebComponent' && /\bextends\s+$/.test(frame.slice(0, m.index))) continue;
+    // A `new X(...)` constructor call: the `new`-prefixed cases were already
+    // vetted above (a non-pure constructor returned true; a pure-data one is
+    // inert), so its `(` here is not an independent side-effecting call.
+    if (ident && /(?<![.\w])new\s+$/.test(frame.slice(0, m.index))) continue;
     return true;                                         // any other top-level call
   }
   return false;
@@ -290,26 +333,38 @@ const SIDE_EFFECT_BARE_IMPORT_RE = /^\s*import\s*(['"])([^'"]+)\1\s*;?\s*(?:\/\/
  * a router/nav API from the core main entry). A page or layout that does so
  * is enabling client-side navigation and must ship.
  * @param {string} src
+ * @param {string[]} [literals]
  * @returns {boolean}
  */
-function importsClientRouter(src) {
-  if (CLIENT_ROUTER_SUBPATH_RE.test(src)) return true;
-  for (const m of src.matchAll(CORE_IMPORT_RE)) {
+function importsClientRouter(src, literals) {
+  let redacted = src;
+  if (!literals) {
+    const r = redactToPlaceholders(src);
+    redacted = r.redacted;
+    literals = r.literals;
+  }
+  if (literals.includes('@webjsdev/core/client-router')) return true;
+  for (const m of redacted.matchAll(CORE_IMPORT_RE)) {
     const clause = m[1];
+    const spec = m[2];
+    const idx = m[3];
+    if (idx !== undefined) {
+      const resolved = literals[parseInt(idx, 10)];
+      if (!resolved || (!resolved.startsWith('@webjsdev/core') && !resolved.includes('/__webjs/core/'))) {
+        continue;
+      }
+    }
     if (clause.startsWith('{')) {
       const names = clause.slice(1, -1).split(',').map((s) => s.trim().split(/\s+as\s+/)[0].trim());
       if (names.some((n) => CLIENT_ROUTER_IMPORTS.includes(n))) return true;
     } else if (clause.startsWith('*')) {
-      // Namespace import: a router/nav member reached through `ns.member`,
-      // a destructure of `ns`, or computed access. Mirrors the reactive
-      // primitive detection so the two stay symmetric.
       const ns = clause.replace(/^\*\s+as\s+/, '').trim();
       if (!ns || !/^\w+$/.test(ns)) continue;
       for (const name of CLIENT_ROUTER_IMPORTS) {
-        if (new RegExp(`\\b${ns}\\.${name}\\b`).test(src)) return true;
+        if (new RegExp(`\\b${ns}\\.${name}\\b`).test(redacted)) return true;
       }
-      if (new RegExp(`(?:const|let|var)\\s*\\{[^}]*\\}\\s*=\\s*${ns}\\b`).test(src)) return true;
-      if (new RegExp(`\\b${ns}\\s*\\[`).test(src)) return true;
+      if (new RegExp(`(?:const|let|var)\\s*\\{[^}]*\\}\\s*=\\s*${ns}\\b`).test(redacted)) return true;
+      if (new RegExp(`\\b${ns}\\s*\\[`).test(redacted)) return true;
     }
   }
   return false;
@@ -336,13 +391,46 @@ function importsClientRouter(src) {
  * the fix is `.server.{js,ts}` for genuinely server-only deps, or an
  * interactivity signal on the consumer. (It is not caught by an SSR crash:
  * the SSR `customElements` shim makes `define` a no-op server-side.)
+ *
+ * A `#` PATH-ALIAS specifier (#555, e.g. `import '#components/x.ts'`, the
+ * idiomatic way a page/layout registers a component) is NOT a bare npm
+ * package: Node's `package.json` "imports" resolves it, in the scaffold's
+ * catch-all `"#*": "./*"` to a LOCAL file. Expanding it through the same
+ * `expandImportAlias` the module graph uses, a local-resolving alias is
+ * treated like a relative import (skipped); only an alias mapped to a real
+ * bare package (`"#crypto": "crypto-browserify"`) falls through to the
+ * package check. Without this, every `#`-imported component side effect
+ * wrongly pinned its importing page/layout to the browser (#623). An
+ * unexpandable `#` (no `appDir`, or no matching key) is assumed local,
+ * since `#` is the local-subpath sigil and an unmapped `#` is a Node error,
+ * not a package.
  * @param {string} src
+ * @param {string} [appDir] app root, used to expand `#` path aliases
+ * @param {string[]} [literals]
  * @returns {boolean}
  */
-function importsSideEffectNonCorePackage(src) {
-  for (const m of src.matchAll(SIDE_EFFECT_BARE_IMPORT_RE)) {
-    const spec = m[2];
+function importsSideEffectNonCorePackage(src, appDir, literals) {
+  let redacted = src;
+  if (!literals) {
+    const r = redactToPlaceholders(src);
+    redacted = r.redacted;
+    literals = r.literals;
+  }
+  for (const m of redacted.matchAll(SIDE_EFFECT_BARE_IMPORT_RE)) {
+    let spec = m[2];
+    const match = /^__STR_(\d+)__$/.exec(spec);
+    if (match) {
+      const idx = parseInt(match[1], 10);
+      spec = literals[idx];
+    }
+    if (!spec) continue;
     if (spec.startsWith('.') || spec.startsWith('/')) continue; // relative / absolute
+    if (spec.startsWith('#')) {
+      const expanded = appDir ? expandImportAlias(spec, appDir) : null;
+      if (expanded == null) continue;                                   // unmapped alias: local
+      if (expanded.startsWith('.') || expanded.startsWith('/')) continue; // resolves to a local file
+      spec = expanded;                                                  // mapped to a bare spec: check it below
+    }
     if (spec === '@webjsdev/core' || spec.startsWith('@webjsdev/core/')) continue; // inert framework / router handled separately
     if (spec.startsWith('node:')) continue; // server-only builtins
     return true;
@@ -350,9 +438,9 @@ function importsSideEffectNonCorePackage(src) {
   return false;
 }
 
-/** Match a named-import clause from a `@webjsdev/core` specifier. */
+/** Match a named-import clause from a `@webjsdev/core` specifier (or its placeholder). */
 const CORE_IMPORT_RE =
-  /import\s+(?:type\s+)?(\{[^}]*\}|\*\s+as\s+\w+|\w+)\s+from\s+['"](@webjsdev\/core[^'"]*|[^'"]*\/__webjs\/core\/[^'"]*)['"]/g;
+  /import\s+(?:type\s+)?(\{[^}]*\}|\*\s+as\s+\w+|\w+)\s+from\s+['"`](@webjsdev\/core[^'"`]*|[^'"`]*\/__webjs\/core\/[^'"`]*|__STR_(\d+)__)['"`]/g;
 
 /**
  * Decide whether a component module is interactive (must ship) or
@@ -483,11 +571,26 @@ function declaresStaticTrue(classBody, name) {
 
 /**
  * @param {string} src
+ * @param {string[]} [literals]
  * @returns {string | null} the offending imported name, or null
  */
-function importsReactivePrimitive(src) {
-  for (const m of src.matchAll(CORE_IMPORT_RE)) {
+function importsReactivePrimitive(src, literals) {
+  let redacted = src;
+  if (!literals) {
+    const r = redactToPlaceholders(src);
+    redacted = r.redacted;
+    literals = r.literals;
+  }
+  for (const m of redacted.matchAll(CORE_IMPORT_RE)) {
     const clause = m[1];
+    const spec = m[2];
+    const idx = m[3];
+    if (idx !== undefined) {
+      const resolved = literals[parseInt(idx, 10)];
+      if (!resolved || (!resolved.startsWith('@webjsdev/core') && !resolved.includes('/__webjs/core/'))) {
+        continue;
+      }
+    }
     if (clause.startsWith('{')) {
       const names = clause
         .slice(1, -1)
@@ -505,14 +608,14 @@ function importsReactivePrimitive(src) {
       const ns = clause.replace(/^\*\s+as\s+/, '').trim();
       if (!ns || !/^\w+$/.test(ns)) continue;
       for (const name of REACTIVE_IMPORTS) {
-        if (new RegExp(`\\b${ns}\\.${name}\\b`).test(src)) return name;
+        if (new RegExp(`\\b${ns}\\.${name}\\b`).test(redacted)) return name;
       }
       // Destructuring the namespace (`const { signal } = core`) or computed
       // access (`core['signal']`) hides which members are pulled. Ship.
-      if (new RegExp(`(?:const|let|var)\\s*\\{[^}]*\\}\\s*=\\s*${ns}\\b`).test(src)) {
+      if (new RegExp(`(?:const|let|var)\\s*\\{[^}]*\\}\\s*=\\s*${ns}\\b`).test(redacted)) {
         return `${ns} (destructured namespace)`;
       }
-      if (new RegExp(`\\b${ns}\\s*\\[`).test(src)) {
+      if (new RegExp(`\\b${ns}\\s*\\[`).test(redacted)) {
         return `${ns} (computed namespace access)`;
       }
     }
@@ -551,18 +654,11 @@ function hasNonStateReactiveProperty(classBody) {
   // see; ship rather than guess they are all { state: true }.
   if (/\.\.\./.test(obj)) return true;
   for (const entry of topLevelPropertyValues(obj)) {
-    // Object-literal descriptor: inert only when it carries state: true.
+    // Object-literal descriptor: inert only when it carries `state: true` at
+    // its top level (descriptorDeclaresState blanks strings and ignores a
+    // nested state flag, e.g. inside a converter, so it cannot be forged).
     if (entry.startsWith('{')) {
-      // Blank string / template bodies first. Redaction keeps quoted
-      // string contents verbatim (so register('tag') stays readable), so
-      // a descriptor like `{ attribute: 'data-state: true' }` would
-      // otherwise forge the state flag. The real `state: true` is code,
-      // not a string, so it survives this blanking.
-      const code = entry
-        .replace(/'[^'\n]*'/g, "''")
-        .replace(/"[^"\n]*"/g, '""')
-        .replace(/`[^`]*`/g, '``');
-      if (!/\bstate\s*:\s*true\b/.test(code)) return true;
+      if (!descriptorDeclaresState(entry)) return true;
     } else {
       // Shorthand like `count: Number` rides an attribute, not state.
       return true;
@@ -572,8 +668,20 @@ function hasNonStateReactiveProperty(classBody) {
 }
 
 /**
- * True if the class factory argument declares any property that is NOT
- * marked `{ state: true }`.
+ * True if the class factory argument (`extends WebComponent({ … })`) declares
+ * any reactive property that is NOT `{ state: true }`. A non-state property
+ * rides an HTML attribute or a `.prop` hydration binding, the channel that
+ * forces the component to ship; a `state: true` property is component-local
+ * reactive state with no such channel, so a component whose only signal is
+ * state props stays elidable.
+ *
+ * A property value is treated as state ONLY when its descriptor declares
+ * `state: true` at the TOP LEVEL (see `descriptorDeclaresState`), which covers
+ * the bare descriptor `{ state: true }` and the `prop()` helper forms
+ * `prop({ state: true })` / `prop(Type, { state: true })`. Anything else (a bare
+ * type `Number`, `prop(Number)`, an options object without `state: true`) is
+ * non-state and ships. Conservative on a spread or an unbalanced brace (cannot
+ * prove every entry is state, so ship).
  *
  * @param {string} factoryArg
  * @returns {boolean}
@@ -582,25 +690,50 @@ function hasNonStateFactoryProperty(factoryArg) {
   if (!factoryArg) return false;
   const objStart = factoryArg.indexOf('{');
   if (objStart === -1) return false;
-  const objEnd = matchClosingBrace(factoryArg, objStart);
+  // matchClosingBrace starts at depth 1, so pass the index AFTER the brace.
+  const objEnd = matchClosingBrace(factoryArg, objStart + 1);
   if (objEnd === -1) return true;
   const obj = factoryArg.slice(objStart + 1, objEnd);
-  if (/\.\.\./.test(obj)) return true; // spread
+  if (/\.\.\./.test(obj)) return true; // spread: cannot prove all entries state
   for (const entry of topLevelPropertyValues(obj)) {
-    if (entry.startsWith('{')) {
-      const code = entry
-        .replace(/'[^'\n]*'/g, "''")
-        .replace(/"[^"\n]*"/g, '""')
-        .replace(/`[^`]*`/g, '``');
-      if (!/\bstate\s*:\s*true\b/.test(code)) return true;
-    } else {
-      // Shorthand like `count: Number` rides an attribute, not state
-      return true;
-    }
+    if (!descriptorDeclaresState(entry)) return true;
   }
   return false;
 }
 
+/**
+ * True if a reactive-property descriptor declares `state: true` at the TOP
+ * LEVEL of its options object (brace-depth 1). Restricting to depth 1 is a
+ * direction-of-safety fix: a `state: true` buried deeper (a converter /
+ * hasChanged body that happens to return `{ state: true }`) must NOT forge the
+ * flag, because wrongly treating an attribute-riding property as state would
+ * ELIDE an interactive component and break the page. Strings / templates are
+ * blanked first, so `attribute: 'data-state: true'` does not match, and the
+ * `\b` word boundary keeps a key like `firstate: true` from matching. In every
+ * legitimate shape (`{ state: true }`, `prop({ state: true })`,
+ * `prop(Type, { state: true })`) the descriptor object is the only brace group,
+ * so its `state` key sits at depth 1.
+ *
+ * @param {string} entry  the property VALUE text
+ * @returns {boolean}
+ */
+function descriptorDeclaresState(entry) {
+  const code = entry
+    .replace(/'[^'\n]*'/g, "''")
+    .replace(/"[^"\n]*"/g, '""')
+    .replace(/`[^`]*`/g, '``');
+  // Keep only text at brace-depth <= 1 (the descriptor's own level); blank
+  // deeper nesting so a nested `state: true` cannot count.
+  let depth = 0;
+  let shallow = '';
+  for (const c of code) {
+    if (c === '{') { depth++; if (depth <= 1) shallow += c; continue; }
+    if (c === '}') { if (depth <= 1) shallow += c; if (depth > 0) depth--; continue; }
+    if (depth <= 1) shallow += c;
+  }
+  return /\bstate\s*:\s*true\b/.test(shallow);
+}
+
 /**
  * Yield the trimmed VALUE text of each top-level `key: value` entry in a
  * properties object body, splitting on depth-0 commas and respecting
@@ -710,7 +843,7 @@ export async function computeElidableComponents(components, moduleGraph, readFil
  * @param {import('./module-graph.js').ModuleGraph} moduleGraph
  * @param {(file: string) => Promise<string>} readFileFn
  * @param {string} [appDir]
- * @returns {Promise<{ elidableComponents: Set<string>, inertRouteModules: Set<string> }>}
+ * @returns {Promise<{ elidableComponents: Set<string>, inertRouteModules: Set<string>, importOnlyRouteModules: Map<string, string[]>, shippedRouteModules: Map<string, { blocker: string|null, reason: string }> }>}
  */
 export async function analyzeElision(components, routeModules, moduleGraph, readFileFn, appDir) {
   /** @type {Set<string>} */
@@ -743,6 +876,8 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
 
   /** @type {Set<string>} */
   const allFiles = new Set(componentFiles);
+  /** @type {Set<string>} page/layout modules: never hydrate, so template content is SSR output. */
+  const routeModuleSet = new Set(routeModules);
   for (const f of routeModules) allFiles.add(f);
   for (const [k, vs] of moduleGraph) {
     if (!appDir || k.startsWith(appDir)) allFiles.add(k);
@@ -770,11 +905,22 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
     // them on the comment-masked source just additionally drops comment prose.)
     const masked = maskComments(src);
     fileTags.set(file, extractRenderedTags(masked));
-    if (importsReactivePrimitive(masked)) reactiveFiles.add(file);
-    if (importsClientRouter(masked)) clientRouterFiles.add(file);
-    if (EVENT_BINDING_RE.test(masked) || EVENT_PROP_RE.test(masked) ||
-        importsSideEffectNonCorePackage(masked) || CLIENT_GLOBAL_RE.test(masked) ||
-        hasModuleScopeSideEffect(masked)) {
+    const { redacted, literals } = redactToPlaceholders(src);
+    if (importsReactivePrimitive(redacted, literals)) reactiveFiles.add(file);
+    if (importsClientRouter(redacted, literals)) clientRouterFiles.add(file);
+    // A page/layout NEVER hydrates (#605), so its `html` TEMPLATE content is
+    // SSR output, not module client work: an inline `<script>`'s browser
+    // globals run from the rendered HTML, and a page-template `@event` is
+    // dropped at SSR. For a route module, scan those two template-borne signals
+    // on the template-redacted source so they do not pin the module, while a
+    // genuine module-scope `document.x` OUTSIDE any template still flags (#623).
+    // The import-based checks stay on `redacted`: a real `import 'pkg'` side
+    // effect DOES run when a page/layout module loads in the browser, and
+    // `importsSideEffectNonCorePackage` itself skips local `#`-alias imports.
+    const templateScan = routeModuleSet.has(file) ? redacted : masked;
+    if (EVENT_BINDING_RE.test(templateScan) || EVENT_PROP_RE.test(templateScan) ||
+        importsSideEffectNonCorePackage(redacted, appDir, literals) || CLIENT_GLOBAL_RE.test(templateScan) ||
+        hasModuleScopeSideEffect(redacted, literals)) {
       clientGlobalOrBareFiles.add(file);
     }
     if (componentFiles.has(file) && analyzeComponentSource(masked).interactive) {
@@ -923,22 +1069,77 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
     clientRouterFiles.has(file) ||
     clientGlobalOrBareFiles.has(file);
 
-  // Route modules: inert iff neither the module nor its effective client
-  // closure (skipping elided components and server stubs, which never load)
-  // is client-effecting.
+  // A human reason for WHY a file does client work, for the advisory that
+  // names why a page/layout ships (#646). Mirrors the isClientEffecting
+  // branches, most specific first.
+  const clientEffectReason = (file) => {
+    if (componentFiles.has(file) && mustShip.has(file)) return 'is an interactive component';
+    if (clientRouterFiles.has(file)) return 'imports the client router';
+    if (reactiveFiles.has(file)) return 'imports a reactive primitive (signal / computed / watch)';
+    if (clientGlobalOrBareFiles.has(file)) return 'references a browser global at module scope, runs code at module scope, or has a bare side-effect import';
+    return 'does client work';
+  };
+
+  // Route modules fall into three classes by their effective client closure
+  // (skipping elided components and server stubs, which never load on the
+  // client):
+  //   - INERT: neither the module nor its closure does any client work. Dropped
+  //     from the boot script entirely (#179).
+  //   - IMPORT-ONLY (#605): the module itself does no client work, and the ONLY
+  //     client work its closure reaches is SHIPPING COMPONENTS. Such a page /
+  //     layout module is just the import-graph carrier for its components; the
+  //     boot can emit those component modules directly and drop the module. The
+  //     condition is a positive subset test (every client-effecting closure
+  //     member is a component), NOT a hand-listed block list: any client-
+  //     effecting NON-component in the closure (a self-executing helper, a
+  //     client-router import, a reactive helper) keeps the whole module, since
+  //     dropping it would lose that side effect.
+  //   - SHIP: anything else (the module itself is client-effecting, or its
+  //     closure reaches a client-effecting non-component). Unchanged behaviour.
   /** @type {Set<string>} */
   const skip = new Set([...elidableComponents, ...serverFiles]);
   /** @type {Set<string>} */
   const inertRouteModules = new Set();
+  /** @type {Map<string, string[]>} route file -> component files to emit in its place */
+  const importOnlyRouteModules = new Map();
+  // Advisory (#646): for each route module that SHIPS WHOLE (neither inert nor
+  // import-only), record the first client-effecting blocker so a tool can name
+  // why it ships. blocker is null when the module's OWN code is the cause.
+  /** @type {Map<string, { blocker: string|null, reason: string }>} */
+  const shippedRouteModules = new Map();
   for (const file of routeModules) {
-    if (!fileTags.has(file)) continue; // unreadable / not analysed: ship (omit from inert set)
-    if (isClientEffecting(file)) continue;
+    if (!fileTags.has(file)) continue; // unreadable / not analysed: ship (omit from both sets)
+    if (isClientEffecting(file)) {
+      // The module itself ships whole; its own signal is the blocker.
+      shippedRouteModules.set(file, { blocker: null, reason: clientEffectReason(file) });
+      continue;
+    }
     const closure = appDir ? transitiveDeps(moduleGraph, [file], appDir, skip) : [];
-    if (closure.some(isClientEffecting)) continue;
-    inertRouteModules.add(file);
+    const effecting = closure.filter(isClientEffecting);
+    if (effecting.length === 0) { inertRouteModules.add(file); continue; }
+    // Import-only iff EVERY client-effecting closure member is a (shipping)
+    // component. isClientEffecting for a component already implies mustShip, so
+    // `effecting` is exactly the shipping components reachable from this module:
+    // re-emit that STATIC set (what loading the module would have registered, so
+    // a component imported but only conditionally rendered still registers).
+    //
+    // A `static lazy` component is NOT special-cased here: it only appears in
+    // this STATIC closure when the route statically imports it, and in that case
+    // loading the module already eager-loaded it before elision, so emitting it
+    // directly preserves that exact behaviour. A normally-used lazy component is
+    // tag-referenced (never statically imported), so it is absent from this
+    // closure and still loads via the IntersectionObserver `observeLazy` path.
+    if (effecting.every((f) => componentFiles.has(f))) {
+      importOnlyRouteModules.set(file, effecting);
+    } else {
+      // A client-effecting non-component is reachable; ship the whole module.
+      // Name the FIRST such non-component as the blocker for the advisory.
+      const blocker = effecting.find((f) => !componentFiles.has(f));
+      shippedRouteModules.set(file, { blocker, reason: clientEffectReason(blocker) });
+    }
   }
 
-  return { elidableComponents, inertRouteModules };
+  return { elidableComponents, inertRouteModules, importOnlyRouteModules, shippedRouteModules };
 }
 
 /** Match a whole-line side-effect import: `import './x.js';` (no bindings). */

package/src/component-scanner.js

@@ -22,6 +22,7 @@ import { readFile, stat } from 'node:fs/promises';
 import { sep } from 'node:path';
 import { walk } from './fs-walk.js';
 import { primeModuleUrl } from '@webjsdev/core';
+import { redactToPlaceholders } from './js-scan.js';
 
 /**
  * mtime-keyed cache of extracted components per file, so a rebuild re-reads
@@ -50,22 +51,26 @@ export function _scanCacheHas(file) { return SCAN_CACHE.has(file); }
 export function extractComponents(src) {
   /** @type {Array<{ className: string, tag: string }>} */
   const results = [];
-  // Pattern A: Class.register('tag')
-  const registerRe = /\b([A-Z][A-Za-z0-9_$]*)\.register\s*\(\s*['"]([^'"\n]+)['"]\s*\)/g;
+  const { redacted, literals } = redactToPlaceholders(src);
+
+  // Pattern A: Class.register('tag') -> matches Class.register('__STR_idx__')
+  const registerRe = /\b([A-Z][A-Za-z0-9_$]*)\.register\s*\(\s*['"`]__STR_(\d+)__['"`]\s*\)/g;
   let m;
-  while ((m = registerRe.exec(src)) !== null) {
+  while ((m = registerRe.exec(redacted)) !== null) {
     const className = m[1];
-    const tag = m[2];
-    if (tag.includes('-')) {
+    const idx = parseInt(m[2], 10);
+    const tag = literals[idx];
+    if (tag && tag.includes('-')) {
       results.push({ className, tag });
     }
   }
-  // Pattern B: customElements.define('tag', Class)
-  const defineRe = /\bcustomElements\.define\s*\(\s*['"]([^'"\n]+)['"]\s*,\s*([A-Z][A-Za-z0-9_$]*)\b/g;
-  while ((m = defineRe.exec(src)) !== null) {
-    const tag = m[1];
+  // Pattern B: customElements.define('tag', Class) -> matches customElements.define('__STR_idx__', Class)
+  const defineRe = /\bcustomElements\.define\s*\(\s*['"`]__STR_(\d+)__['"`]\s*,\s*([A-Z][A-Za-z0-9_$]*)\b/g;
+  while ((m = defineRe.exec(redacted)) !== null) {
+    const idx = parseInt(m[1], 10);
+    const tag = literals[idx];
     const className = m[2];
-    if (tag.includes('-')) {
+    if (tag && tag.includes('-')) {
       results.push({ className, tag });
     }
   }