@webjsdev/server 0.8.31 → 0.8.33

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
@@ -416,7 +504,7 @@ export function analyzeComponentSource(src) {
     return { interactive: true, reason: 'no parseable WebComponent class body' };
   }
 
-  for (const body of bodies) {
+  for (const { body, factoryArg } of bodies) {
     // Shadow DOM always ships (#474). Declarative Shadow DOM attaches ONLY
     // during HTML parsing; an elided component that arrives via a client DOM
     // insertion (a soft-nav swap, a streamed <webjs-suspense> boundary's
@@ -447,7 +535,7 @@ export function analyzeComponentSource(src) {
         return { interactive: true, reason: `calls '${call}'` };
       }
     }
-    if (hasNonStateReactiveProperty(body)) {
+    if (hasNonStateReactiveProperty(body) || hasNonStateFactoryProperty(factoryArg)) {
       return {
         interactive: true,
         reason: 'declares a reactive property that is not { state: true }',
@@ -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;
@@ -571,6 +667,73 @@ function hasNonStateReactiveProperty(classBody) {
   return false;
 }
 
+/**
+ * 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}
+ */
+function hasNonStateFactoryProperty(factoryArg) {
+  if (!factoryArg) return false;
+  const objStart = factoryArg.indexOf('{');
+  if (objStart === -1) return false;
+  // 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: cannot prove all entries state
+  for (const entry of topLevelPropertyValues(obj)) {
+    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
@@ -680,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[]> }>}
  */
 export async function analyzeElision(components, routeModules, moduleGraph, readFileFn, appDir) {
   /** @type {Set<string>} */
@@ -713,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);
@@ -740,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) {
@@ -893,22 +1069,53 @@ 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.
+  // 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();
   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)) continue; // the module itself ships whole
     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.
   }
 
-  return { elidableComponents, inertRouteModules };
+  return { elidableComponents, inertRouteModules, importOnlyRouteModules };
 }
 
 /** 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 });
     }
   }

package/src/dev.js

@@ -13,7 +13,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { buildRouteTable, matchPage, matchApi } from './router.js';
 import { generateRouteTypes } from './route-types.js';
-import { ssrPage, ssrNotFound } from './ssr.js';
+import { ssrPage, ssrNotFound, setClientRouterEnabled } from './ssr.js';
 import { loadPageAction, runPageAction } from './page-action.js';
 import { handleApi } from './api.js';
 import {
@@ -267,6 +267,28 @@ export async function readSeedEnabled(appDir) {
   return true;
 }
 
+/**
+ * Read the client-router switch (`webjs.clientRouter`) from the app's
+ * package.json (#629). Default `true`: the client router auto-enables in the
+ * browser whenever `@webjsdev/core` loads (the automatic-navigation thesis).
+ * `{ "webjs": { "clientRouter": false } }` opts the WHOLE app out (pure MPA,
+ * full-page navigation), which the render path signals to the browser so the
+ * core bundle's module-end auto-enable is skipped. Any other value, or an
+ * absent key, keeps the router on. Re-read on every rebuild (alongside elide)
+ * so toggling it takes effect without a server restart.
+ * @param {string} appDir
+ * @returns {Promise<boolean>}
+ */
+export async function readClientRouterEnabled(appDir) {
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    if (pkg && pkg.webjs && pkg.webjs.clientRouter === false) return false;
+  } catch {
+    // No package.json, malformed JSON, or unreadable. Keep the default.
+  }
+  return true;
+}
+
 /**
  * Read the per-path response-header config (`webjs.headers`) from the
  * app's package.json and compile it to URLPattern rules. A missing,
@@ -473,6 +495,12 @@ export async function createRequestHandler(opts) {
   const basePathValue = await readBasePathFromApp(appDir);
   await setBasePath(basePathValue);
 
+  // Client-router opt-out (#629): bind it eagerly at handler construction (the
+  // same timing as setBasePath above), so a handler's module-global is set
+  // before any render even if a request arrives before the first warm. The
+  // analysis pass re-reads it each rebuild so a dev toggle takes effect live.
+  setClientRouterEnabled(await readClientRouterEnabled(appDir));
+
   const coreDir = locateCoreDir(appDir);
   // Switch the importmap between dist/ bundles and src/ per-file
   // URLs depending on whether the resolved @webjsdev/core install
@@ -638,6 +666,7 @@ export async function createRequestHandler(opts) {
     moduleGraph: null,
     elidableComponents: new Set(),
     inertRouteModules: new Set(),
+    importOnlyRouteModules: new Map(),
     browserBoundFiles: null,
     // Transformed-source cache (stripped TS + applied elision). Per-handler,
     // NOT module-global: the cached bytes bake in THIS handler's elision
@@ -742,12 +771,16 @@ export async function createRequestHandler(opts) {
             t.actions = now() - m; m = now();
             state.middleware = await loadMiddleware(appDir, dev, logger);
             t.middleware = now() - m; m = now();
+            // 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))
               ? await analyzeElision(components, collectRouteModules(state.routeTable),
                   state.moduleGraph, (f) => readFile(f, 'utf8'), appDir)
-              : { elidableComponents: new Set(), inertRouteModules: new Set() };
+              : { elidableComponents: new Set(), inertRouteModules: new Set(), importOnlyRouteModules: new Map() };
             state.elidableComponents = r.elidableComponents;
             state.inertRouteModules = r.inertRouteModules;
+            state.importOnlyRouteModules = r.importOnlyRouteModules;
             // Fold the elision verdict into app-module content hashes (#243): an
             // app module's served body is elision-transformed, so a verdict flip
             // must bust its `?v` even when its source is byte-identical. A stable
@@ -764,6 +797,10 @@ export async function createRequestHandler(opts) {
               const elidedPaths = [
                 ...state.elidableComponents,
                 ...state.inertRouteModules,
+                // An import-only module is dropped from the boot (replaced by its
+                // component imports), so a flip in / out of that class must bust
+                // the importer's `?v` too.
+                ...state.importOnlyRouteModules.keys(),
               ].map(rel).sort();
               setElisionFingerprint(elidedPaths.length ? elidedPaths.join('\n') : '');
             }
@@ -871,7 +908,7 @@ export async function createRequestHandler(opts) {
     if (vendorResolveInFlight) return vendorResolveInFlight;
     vendorResolveInFlight = (async () => {
       try {
-        const scan = () => scanBareImports(appDir, new Set([...state.elidableComponents, ...state.inertRouteModules]));
+        const scan = () => scanBareImports(appDir, new Set([...state.elidableComponents, ...state.inertRouteModules, ...state.importOnlyRouteModules.keys()]));
         const v = await resolveVendorImports(appDir, scan);
         let { imports, integrity } = v;
         if (bootVendorPinned) {
@@ -1303,7 +1340,21 @@ export async function createRequestHandler(opts) {
     if (matchPathname === null) return null;
     const page = matchPage(state.routeTable, matchPathname);
     if (!page) return null;
-    const moduleUrls = [page.route.file, ...page.route.layouts].map((f) => {
+    // Mirror ssr.js's boot assembly EXACTLY: drop inert route modules, and
+    // splice an import-only module's component imports in place of the module
+    // (#605). Otherwise the 103 Early Hints would preload the page / layout
+    // modules the body no longer imports (a wasted hint) and miss the component
+    // modules it actually fetches (a double-fetch on the real module).
+    const inert = state.inertRouteModules;
+    const importOnly = state.importOnlyRouteModules;
+    const files = [];
+    const seenFiles = new Set();
+    for (const f of [page.route.file, ...page.route.layouts]) {
+      if (inert && inert.has(f)) continue;
+      const emit = importOnly && importOnly.get(f);
+      for (const t of emit || [f]) if (!seenFiles.has(t)) { seenFiles.add(t); files.push(t); }
+    }
+    const moduleUrls = files.map((f) => {
       let rel = f.startsWith(appDir) ? f.slice(appDir.length) : f;
       const url = rel.split('\\').join('/').replace(/^\/?/, '/');
       // Mirror ssr.js's emit (basePath THEN `?v`) so the 103 Early Hints preload
@@ -1880,6 +1931,7 @@ async function handleCore(req, ctx) {
         serverFiles: state.actionIndex.fileToHash,
         elidableComponents: state.elidableComponents,
         inertRouteModules: state.inertRouteModules,
+        importOnlyRouteModules: state.importOnlyRouteModules,
         notFoundFile: state.routeTable.notFound,
         // Server HTML cache (#241): a CSP-enabled page emits a fresh
         // per-request nonce into its body, so its bytes vary per request and