@webjsdev/server 0.8.74 → 0.8.76

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.74",
+  "version": "0.8.76",
   "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",

package/src/auth.js

@@ -13,6 +13,8 @@ import { readTextBounded, readFormDataBounded, payloadTooLarge, DEFAULT_MAX_BODY
 
 const enc = new TextEncoder();
 const dec = new TextDecoder();
+// Base names. In production each is sent with the `__Host-` prefix
+// (cookieName below); development over http keeps the plain name.
 const AUTH_COOKIE = 'webjs.auth';
 const STATE_COOKIE = 'webjs.auth.state';
 // Carries the post-sign-in target across the OAuth round trip (#1495). Signed
@@ -104,14 +106,33 @@ function parseCookies(header) {
   return out;
 }
 
+/**
+ * The name a cookie is sent under. In production it carries the `__Host-`
+ * prefix (#1538): a browser stores a `__Host-` cookie only when it is
+ * `Secure`, has `Path=/` and has NO `Domain` attribute, so an app on a sibling
+ * subdomain (two apps on `a.example.app` and `b.example.app`, with
+ * `example.app` not on the Public Suffix List) can no longer plant its own
+ * `webjs.auth` with `Domain=.example.app` and sign a visitor in to the wrong
+ * account (cookie tossing, session fixation). Production never reads the
+ * unprefixed name: a fallback would reopen exactly that hole.
+ * Development over http keeps the plain name, since `__Host-` needs `Secure`.
+ *
+ * @param {string} base @param {boolean} secure
+ */
+export function cookieName(base, secure) {
+  return secure ? `__Host-${base}` : base;
+}
+
 function setCookie(name, value, maxAge, secure) {
   let s = `${name}=${encodeURIComponent(value)}; Max-Age=${Math.floor(maxAge / 1000)}; Path=/; HttpOnly; SameSite=Lax`;
   if (secure) s += '; Secure';
   return s;
 }
 
-function clearCookie(name) {
-  return `${name}=; Max-Age=0; Path=/; HttpOnly; SameSite=Lax`;
+// A `__Host-` cookie is cleared only by a Set-Cookie that also says Secure;
+// a browser ignores one without it, and the cookie would stay.
+function clearCookie(name, secure = false) {
+  return `${name}=; Max-Age=0; Path=/; HttpOnly; SameSite=Lax${secure ? '; Secure' : ''}`;
 }
 
 // -- JWT --------------------------------------------------------------------
@@ -260,7 +281,7 @@ export function createAuth(config) {
     // page cacheable so a logged-in body could be served to the next visitor.
     markDynamicAccess();
     const cookies = parseCookies(req.headers.get('cookie') || '');
-    const raw = cookies[AUTH_COOKIE];
+    const raw = cookies[cookieName(AUTH_COOKIE, secure())];
     if (!raw) return null;
 
     if (strategy === 'jwt') {
@@ -284,11 +305,11 @@ export function createAuth(config) {
     if (strategy === 'jwt') {
       let token = { sub: user.id, name: user.name, email: user.email, image: user.image, role: user.role, iat: Math.floor(Date.now() / 1000), exp: Math.floor(Date.now() / 1000) + maxAge };
       if (cb.jwt) token = await cb.jwt({ token, user });
-      return setCookie(AUTH_COOKIE, await encodeJwt(token, secret), maxAgeMs, secure());
+      return setCookie(cookieName(AUTH_COOKIE, secure()), await encodeJwt(token, secret), maxAgeMs, secure());
     }
     const sid = randomId();
     await dbStore.save(sid, user, maxAgeMs);
-    return setCookie(AUTH_COOKIE, await sign(sid, secret), maxAgeMs, secure());
+    return setCookie(cookieName(AUTH_COOKIE, secure()), await sign(sid, secret), maxAgeMs, secure());
   }
 
   // -- auth() ---------------------------------------------------------------
@@ -333,12 +354,12 @@ export function createAuth(config) {
   async function signOutFn(opts = {}) {
     const hdrs = new Headers();
     hdrs.set('location', opts.redirectTo || pages.signOut || '/');
-    hdrs.append('set-cookie', clearCookie(AUTH_COOKIE));
+    hdrs.append('set-cookie', clearCookie(cookieName(AUTH_COOKIE, secure()), secure()));
 
     if (strategy === 'database' && dbStore) {
       const r = opts.req || getRequest();
       if (r) {
-        const raw = parseCookies(r.headers.get('cookie') || '')[AUTH_COOKIE];
+        const raw = parseCookies(r.headers.get('cookie') || '')[cookieName(AUTH_COOKIE, secure())];
         if (raw) { const sid = await unsign(raw, secret); if (sid) await dbStore.destroy(sid); }
       }
     }
@@ -361,14 +382,14 @@ export function createAuth(config) {
 
     const hdrs = new Headers();
     hdrs.set('location', url.toString());
-    hdrs.append('set-cookie', setCookie(STATE_COOKIE, await sign(state, secret), 600_000, secure()));
+    hdrs.append('set-cookie', setCookie(cookieName(STATE_COOKIE, secure()), await sign(state, secret), 600_000, secure()));
     // The post-sign-in target rides in its own signed cookie (#1495). With no
     // valid target, any leftover cookie from an abandoned earlier attempt is
     // cleared so it cannot steer this sign-in somewhere stale.
     const target = safeRedirectPath(opts.redirectTo);
     hdrs.append('set-cookie', target
-      ? setCookie(REDIRECT_COOKIE, await sign(target, secret), 600_000, secure())
-      : clearCookie(REDIRECT_COOKIE));
+      ? setCookie(cookieName(REDIRECT_COOKIE, secure()), await sign(target, secret), 600_000, secure())
+      : clearCookie(cookieName(REDIRECT_COOKIE, secure()), secure()));
     return new Response(null, { status: 302, headers: hdrs });
   }
 
@@ -381,7 +402,7 @@ export function createAuth(config) {
    * @returns {Promise<string | null>}
    */
   async function readRedirectCookie(req) {
-    const raw = parseCookies(req.headers.get('cookie') || '')[REDIRECT_COOKIE];
+    const raw = parseCookies(req.headers.get('cookie') || '')[cookieName(REDIRECT_COOKIE, secure())];
     if (!raw) return null;
     return safeRedirectPath(await unsign(raw, secret));
   }
@@ -392,7 +413,7 @@ export function createAuth(config) {
     const state = url.searchParams.get('state');
     if (!code || !state) return new Response('Missing code or state', { status: 400 });
 
-    const rawState = parseCookies(req.headers.get('cookie') || '')[STATE_COOKIE];
+    const rawState = parseCookies(req.headers.get('cookie') || '')[cookieName(STATE_COOKIE, secure())];
     if (!rawState) return new Response('Missing state cookie', { status: 403 });
     const verified = await unsign(rawState, secret);
     if (!verified || verified !== state) return new Response('Invalid state', { status: 403 });
@@ -430,8 +451,8 @@ export function createAuth(config) {
       if (ok === false) {
         const denied = new Headers();
         denied.set('location', pages.error || '/?error=AccessDenied');
-        denied.append('set-cookie', clearCookie(STATE_COOKIE));
-        denied.append('set-cookie', clearCookie(REDIRECT_COOKIE));
+        denied.append('set-cookie', clearCookie(cookieName(STATE_COOKIE, secure()), secure()));
+        denied.append('set-cookie', clearCookie(cookieName(REDIRECT_COOKIE, secure()), secure()));
         return new Response(null, { status: 302, headers: denied });
       }
     }
@@ -439,8 +460,8 @@ export function createAuth(config) {
     const hdrs = new Headers();
     hdrs.set('location', (await readRedirectCookie(req)) || '/');
     hdrs.append('set-cookie', await writeSession(user));
-    hdrs.append('set-cookie', clearCookie(STATE_COOKIE));
-    hdrs.append('set-cookie', clearCookie(REDIRECT_COOKIE));
+    hdrs.append('set-cookie', clearCookie(cookieName(STATE_COOKIE, secure()), secure()));
+    hdrs.append('set-cookie', clearCookie(cookieName(REDIRECT_COOKIE, secure()), secure()));
     return new Response(null, { status: 302, headers: hdrs });
   }
 

package/src/component-elision.js

@@ -1519,3 +1519,91 @@ export function elideImportsFromSource(source, importerAbs, moduleGraph, elidabl
   out += source.slice(last);
   return out;
 }
+
+/**
+ * Defer side-effect imports of `static lazy` components (#1524). A lazy
+ * component that a shipping module imports for registration used to load
+ * eagerly as part of that module's static graph, which defeated `static lazy`
+ * whenever the class had to be imported at all (and SSR needs the import: the
+ * server only knows the tag is lazy once the class registered). The SERVER
+ * keeps the real import; this rewrites only the BROWSER copy, replacing the
+ * import line in place (same line, so positions stay stable) with a
+ * registration on the lazy loader:
+ *
+ *     import('@webjsdev/core/lazy-loader').then((m) => m.observeLazy({"x-tag":"/url"}));
+ *
+ * The loader then imports the module the first time an element with one of
+ * its tags is in (or near) the viewport: a hidden tab panel when it first
+ * shows, a closed dialog's content when it opens, a below-the-fold element
+ * when it scrolls near. Its MutationObserver also catches a tag rendered
+ * later on the client, so an imported-but-not-yet-rendered component still
+ * registers when it appears.
+ *
+ * Same contract as {@link elideImportsFromSource}: only a side-effect import
+ * is rewritten (a binding import needs its value now, so it stays eager), the
+ * match runs over a redacted copy so an import-looking line inside a string,
+ * template, or comment is never touched, and an importer with no lazy
+ * dependency in the graph returns untouched with no regex work. Run it AFTER
+ * the elision strip: an elided import is already a comment by then.
+ *
+ * @param {string} source             module source (already type-stripped if TS)
+ * @param {string} importerAbs        absolute path of the importing module
+ * @param {import('./module-graph.js').ModuleGraph | undefined} moduleGraph
+ * @param {Map<string, string[]> | undefined} lazyFiles  lazy component file -> the tags it registers
+ * @param {(spec: string, fromFile: string, appDir: string) => (string|null)} resolveImport
+ * @param {string} appDir
+ * @param {(abs: string) => string} urlFor  the browser URL the loader imports (base path + content hash applied)
+ * @returns {string}
+ */
+export function deferLazyImportsFromSource(source, importerAbs, moduleGraph, lazyFiles, resolveImport, appDir, urlFor) {
+  if (!lazyFiles || lazyFiles.size === 0) return source;
+  const deps = moduleGraph && moduleGraph.get(importerAbs);
+  if (!deps) return source;
+  let hasLazyDep = false;
+  for (const d of deps) {
+    if (lazyFiles.has(d)) { hasLazyDep = true; break; }
+  }
+  if (!hasLazyDep) return source;
+
+  const redacted = redactStringsAndTemplates(source);
+  let out = '';
+  let last = 0;
+  for (const m of redacted.matchAll(SIDE_EFFECT_IMPORT_RE)) {
+    const start = /** @type {number} */ (m.index);
+    const end = start + m[0].length;
+    const resolved = resolveImport(m[3], importerAbs, appDir);
+    const tags = resolved ? lazyFiles.get(resolved) : undefined;
+    out += source.slice(last, start);
+    if (tags && tags.length) {
+      const url = urlFor(/** @type {string} */ (resolved));
+      const entries = Object.fromEntries(tags.map((t) => [t, url]));
+      out += `${m[1]}import('@webjsdev/core/lazy-loader').then((m) => m.observeLazy(${JSON.stringify(entries)}));`;
+    } else {
+      out += source.slice(start, end);
+    }
+    last = end;
+  }
+  out += source.slice(last);
+  return out;
+}
+
+/**
+ * The lazy component files of an app (#1524): every scanned component file
+ * that declares `static lazy = true`, mapped to the tags it registers. An
+ * elided (display-only) file is left out: its import is stripped outright,
+ * which beats deferring it.
+ *
+ * @param {Array<{ tag: string, file: string, lazy?: boolean }>} components
+ * @param {Set<string>} [elidable]
+ * @returns {Map<string, string[]>}
+ */
+export function lazyComponentFiles(components, elidable) {
+  /** @type {Map<string, string[]>} */
+  const out = new Map();
+  for (const c of components) {
+    if (!c.lazy || (elidable && elidable.has(c.file))) continue;
+    const tags = out.get(c.file);
+    if (tags) { if (!tags.includes(c.tag)) tags.push(c.tag); } else out.set(c.file, [c.tag]);
+  }
+  return out;
+}

package/src/component-scanner.js

@@ -28,7 +28,7 @@ import { redactToPlaceholders } from './js-scan.js';
  * after a single `stat`). Makes the component scan incremental for large apps.
  * Keyed by mtime AND size (a same-tick length-changing edit is caught even on
  * coarse-mtime filesystems).
- * @type {Map<string, { mtimeMs: number, size: number, comps: Array<{ tag: string, className: string }> }>}
+ * @type {Map<string, { mtimeMs: number, size: number, comps: Array<{ tag: string, className: string }>, lazy: boolean }>}
  */
 const SCAN_CACHE = new Map();
 
@@ -75,16 +75,34 @@ export function extractComponents(src) {
   return results;
 }
 
+/**
+ * Does this component module declare `static lazy = true` (#1524)? Matched on
+ * the comment- and string-redacted source, so the phrase inside a comment or a
+ * string literal does not count. The answer is per FILE: a lazy module is
+ * loaded whole, so every tag it registers is deferred together (one component
+ * per file is the convention anyway).
+ *
+ * @param {string} src
+ * @returns {boolean}
+ */
+export function declaresLazy(src) {
+  if (!src.includes('lazy')) return false;
+  const { redacted } = redactToPlaceholders(src);
+  return /\bstatic\s+(?:override\s+|readonly\s+)*lazy\s*(?::\s*boolean\s*)?=\s*true\b/.test(redacted);
+}
+
 /**
  * Walk an app directory, return every discovered component with its
  * browser-visible URL (rooted at `/`, matching how the dev server
  * serves module files).
  *
  * @param {string} appDir
- * @returns {Promise<Array<{ tag: string, className: string, moduleUrl: string, file: string }>>}
+ * `lazy` is true when the file declares `static lazy = true` (#1524).
+ *
+ * @returns {Promise<Array<{ tag: string, className: string, moduleUrl: string, file: string, lazy: boolean }>>}
  */
 export async function scanComponents(appDir) {
-  /** @type {Array<{ tag: string, className: string, moduleUrl: string, file: string }>} */
+  /** @type {Array<{ tag: string, className: string, moduleUrl: string, file: string, lazy: boolean }>} */
   const components = [];
   /** @type {Set<string>} live component files this scan, for cache eviction */
   const seen = new Set();
@@ -97,20 +115,22 @@ export async function scanComponents(appDir) {
     let mtimeMs, size;
     try { const st = await stat(file); mtimeMs = st.mtimeMs; size = st.size; } catch { continue; }
     seen.add(file); // mark live (hit and miss) for cache eviction
-    let comps;
+    let comps, lazy;
     const cached = SCAN_CACHE.get(file);
     if (cached && cached.mtimeMs === mtimeMs && cached.size === size) {
       comps = cached.comps;
+      lazy = cached.lazy;
     } else {
       let src;
       try { src = await readFile(file, 'utf8'); } catch { continue; }
       comps = extractComponents(src);
-      SCAN_CACHE.set(file, { mtimeMs, size, comps });
+      lazy = comps.length > 0 && declaresLazy(src);
+      SCAN_CACHE.set(file, { mtimeMs, size, comps, lazy });
     }
     if (!comps.length) continue;
     const moduleUrl = toUrlPath(file, appDir);
     for (const c of comps) {
-      components.push({ ...c, moduleUrl, file });
+      components.push({ ...c, moduleUrl, file, lazy });
     }
   }
   // Evict scan-cache entries for files no longer walked (renamed/deleted),

package/src/dev/handler.js

@@ -33,7 +33,7 @@ import { reachedBareImports, resolveVendorImports, clearVendorCache, hasVendorPi
 import { browserEntryFiles } from '../browser-entries.js';
 import { buildModuleGraph, seenFilesFor, appImportsMap, reachableFromEntries } from '../module-graph.js';
 import { primeComponentRegistry, findOrphanComponents, scanComponents } from '../component-scanner.js';
-import { analyzeElision } from '../component-elision.js';
+import { analyzeElision, lazyComponentFiles } from '../component-elision.js';
 
 import { setVendorEntries, setCoreInstall, publishBuildId, setAppSourceId, setBasePath, basePath, setImportAliasEntries, importAliasBrowserEntries } from '../importmap.js';
 import { stripBasePath, withBasePath } from '../base-path.js';
@@ -442,6 +442,10 @@ export async function createRequestHandler(opts) {
     elidableComponents: new Set(),
     inertRouteModules: new Set(),
     importOnlyRouteModules: new Map(),
+    // `static lazy` component files -> their tags (#1524): a side-effect import
+    // of one is served as a lazy-loader registration, and the preload walks
+    // skip it. Independent of the elision switch.
+    lazyComponentFiles: new Map(),
     // The browser-bound ENTRY files (pages / layouts / boundaries / components),
     // kept alongside the expanded gate set because the vendor scan roots at the
     // entries rather than at the closure.
@@ -609,6 +613,7 @@ export async function createRequestHandler(opts) {
             state.elidableComponents = r.elidableComponents;
             state.inertRouteModules = r.inertRouteModules;
             state.importOnlyRouteModules = r.importOnlyRouteModules;
+            state.lazyComponentFiles = lazyComponentFiles(components, state.elidableComponents);
             // Dev live-reload classification (#1398): derive the three sets the
             // watch-event classifier reads. `browserBoundFiles` above is the
             // AUTHORIZATION gate (it walks from every entry, elided ones
@@ -647,7 +652,10 @@ export async function createRequestHandler(opts) {
                 // component imports), so a flip in / out of that class must bust
                 // the importer's `?v` too.
                 ...state.importOnlyRouteModules.keys(),
-              ].map(rel).sort();
+                // A file flipping to or from `static lazy` changes how every
+                // importer serves its import of it (#1524).
+                ...[...state.lazyComponentFiles.keys()].map((f) => `lazy:${f}`),
+              ].map((p) => (p.startsWith('lazy:') ? `lazy:${rel(p.slice(5))}` : rel(p))).sort();
               setElisionFingerprint(elidedPaths.length ? elidedPaths.join('\n') : '');
             }
             // App-source fingerprint for the HTML cache key (#318): a

package/src/dev/serve.js

@@ -27,11 +27,12 @@ import { maybeRegenerate } from '../dev-regenerate.js';
 import { stripTypeScript } from '../ts-strip.js';
 import { serveDownloadedBundle } from '../vendor.js';
 import { resolveImport } from '../module-graph.js';
-import { elideImportsFromSource } from '../component-elision.js';
+import { elideImportsFromSource, deferLazyImportsFromSource } from '../component-elision.js';
 import { annotateSourceLocations, isSourceLocationCandidate, sourceLocationFile } from '../dev-source-locations.js';
 import { basePath } from '../importmap.js';
 import { withBasePath } from '../base-path.js';
-import { versionModuleImports } from '../asset-hash.js';
+import { versionModuleImports, withAssetHash } from '../asset-hash.js';
+import { toUrlPath } from '../ssr/preloads.js';
 import { BUFFERED_MARKER } from '../conditional-get.js';
 import { MIME, TS_CACHE_MAX, exists, reloadClientJs, reloadWorkerJs } from './helpers.js';
 
@@ -322,6 +323,10 @@ export async function handleCore(req, ctx) {
       const elideOpts = {
         moduleGraph: state.moduleGraph,
         elidableComponents: state.elidableComponents,
+        // A browser test imports the component it tests and expects it defined
+        // when the import resolves, so the test handler serves every import as
+        // written (#1524).
+        lazyComponentFiles: state.testMode ? undefined : state.lazyComponentFiles,
         appDir,
         // Dev source locations (#1499): annotate the served module's `html`
         // templates exactly as the SSR load hook annotates the server's copy.
@@ -416,6 +421,7 @@ export async function handleCore(req, ctx) {
         dev, appDir, moduleGraph: state.moduleGraph,
         serverFiles: state.actionIndex.fileToHash,
         elidableComponents: state.elidableComponents,
+        lazyComponentFiles: state.lazyComponentFiles,
         inertRouteModules: state.inertRouteModules,
         importOnlyRouteModules: state.importOnlyRouteModules,
         notFoundFile: state.routeTable.notFound,
@@ -686,7 +692,7 @@ export async function fileResponse(abs, opts) {
  *
  * @param {string} abs
  * @param {boolean} dev
- * @param {{ moduleGraph: any, elidableComponents: Set<string>|undefined, appDir: string }} elideOpts
+ * @param {{ moduleGraph: any, elidableComponents: Set<string>|undefined, lazyComponentFiles?: Map<string, string[]>, appDir: string }} elideOpts
  * @param {boolean} [immutable]  true for a `?v=<hash>` content-addressed request (#243):
  *   serve `immutable` (1 year) instead of the 1h fallback. Dev stays `no-cache`.
  */
@@ -697,6 +703,7 @@ export async function jsModuleResponse(abs, dev, elideOpts, immutable) {
   let code = elideImportsFromSource(
     annotateServedModule(source, abs, elideOpts), abs, elideOpts.moduleGraph, elideOpts.elidableComponents, resolveImport, elideOpts.appDir,
   );
+  code = deferLazyImports(code, abs, elideOpts);
   // Version same-origin relative import specifiers so the URL the browser
   // fetches matches the `?v=`-versioned modulepreload + boot specifier (#369).
   // A no-op in dev (fingerprinting disabled).
@@ -711,6 +718,26 @@ export async function jsModuleResponse(abs, dev, elideOpts, immutable) {
   return new Response(code, { status: 200, headers });
 }
 
+/**
+ * Serve a side-effect import of a `static lazy` component as a lazy-loader
+ * registration (#1524). The URL the loader imports is the one the boot script
+ * would use: base-path-prefixed, then content-hashed (`?v=`, a no-op in dev),
+ * the same composition as `wrapHead`'s lazy map in `ssr/head.js`. It is
+ * computed here because `versionModuleImports` (which runs next) deliberately
+ * leaves string literals alone.
+ *
+ * @param {string} code
+ * @param {string} abs
+ * @param {{ moduleGraph: any, lazyComponentFiles?: Map<string, string[]>, appDir: string }} opts
+ * @returns {string}
+ */
+function deferLazyImports(code, abs, opts) {
+  if (!opts.lazyComponentFiles || opts.lazyComponentFiles.size === 0) return code;
+  const bp = basePath();
+  const urlFor = (file) => withAssetHash(withBasePath(toUrlPath(file, opts.appDir), bp), bp);
+  return deferLazyImportsFromSource(code, abs, opts.moduleGraph, opts.lazyComponentFiles, resolveImport, opts.appDir, urlFor);
+}
+
 /**
  * Dev source locations (#1499): stamp `data-webjs-src` on the element opening
  * tags of a served app module's `html` templates, the same transform the SSR
@@ -767,7 +794,7 @@ export async function stripTs(source, _abs) {
  *
  * @param {string} abs
  * @param {boolean} dev
- * @param {{ moduleGraph: any, elidableComponents: Set<string>|undefined, appDir: string }} [elideOpts]
+ * @param {{ moduleGraph: any, elidableComponents: Set<string>|undefined, lazyComponentFiles?: Map<string, string[]>, appDir: string }} [elideOpts]
  * @param {Map<string, { mtimeMs: number, code: string, map: string | null }>} cache the handler's `state.tsCache`
  * @param {boolean} [immutable]  true for a `?v=<hash>` content-addressed request (#243):
  *   serve `immutable` (1 year) instead of the 1h fallback. The cached BODY is
@@ -841,6 +868,7 @@ export async function tsResponse(abs, dev, elideOpts, cache, immutable, reportDe
     code = elideImportsFromSource(
       code, abs, elideOpts.moduleGraph, elideOpts.elidableComponents, resolveImport, elideOpts.appDir,
     );
+    code = deferLazyImports(code, abs, elideOpts);
   }
   // Version same-origin relative import specifiers so the URL the browser
   // fetches matches the `?v=`-versioned modulepreload + boot specifier (#369).

package/src/ssr/preloads.js

@@ -35,12 +35,17 @@ export function toUrlPath(file, appDir) {
  * are stripped from the served source, so preloading their module would
  * fetch JS the browser never executes.
  *
+ * A tag counts as lazy when its class says so at runtime (`isLazy`) OR its
+ * file declares `static lazy = true` in source (`lazyFiles`, #1524), the same
+ * per-file verdict the served-source rewrite uses, so the two never disagree.
+ *
  * @param {Set<string>} usedTags
  * @param {string} appDir
  * @param {Set<string>} [elidable]  absolute paths of elidable component files
+ * @param {Map<string, string[]>} [lazyFiles]  lazy component file -> its tags
  * @returns {{ eager: string[], lazy: Record<string, string> }}
  */
-export function componentPreloads(usedTags, appDir, elidable) {
+export function componentPreloads(usedTags, appDir, elidable, lazyFiles) {
   const eager = [];
   /** @type {Record<string, string>} */
   const lazy = {};
@@ -52,7 +57,7 @@ export function componentPreloads(usedTags, appDir, elidable) {
       if (!abs.startsWith(appDir)) continue;
       if (elidable && elidable.has(abs)) continue;
       const url = toUrlPath(abs, appDir);
-      if (isLazy(tag)) {
+      if (isLazy(tag) || (lazyFiles && lazyFiles.has(abs))) {
         lazy[tag] = url;
       } else {
         eager.push(url);

package/src/ssr/render.js

@@ -1105,13 +1105,23 @@ export async function ssrPage(route, params, url, opts) {
     // registers; one nested behind an emitted component is absent here and
     // loads via its importer's own imports. Dedup so a component shared
     // across the page and a layout (or two layouts) is emitted once.
+    //
+    // A `static lazy` component in that frontier (#1524) is registered with the
+    // lazy loader instead of imported, exactly as a shipping module's served
+    // source defers its side-effect import of one, so the boot never fetches
+    // it up front and a tag revealed later still loads on first sight.
     const inert = opts.inertRouteModules;
     const importOnly = opts.importOnlyRouteModules;
+    const lazyFiles = opts.lazyComponentFiles;
     const moduleUrls = [];
+    /** @type {Record<string, string>} */
+    const frontierLazy = {};
     {
       const seen = new Set();
       const push = (abs) => {
         const u = toUrlPath(abs, opts.appDir);
+        const tags = lazyFiles && lazyFiles.get(abs);
+        if (tags) { for (const t of tags) frontierLazy[t] = u; return; }
         if (!seen.has(u)) { seen.add(u); moduleUrls.push(u); }
       };
       for (const f of [route.file, ...route.layouts]) {
@@ -1137,8 +1147,15 @@ export async function ssrPage(route, params, url, opts) {
     // the same preload twice. Lazy components are excluded from
     // preloads and instead loaded via IntersectionObserver when they
     // enter the viewport.
-    const { eager: eagerComponents, lazy: lazyComponents } =
-      componentPreloads(suspenseCtx.usedComponents, opts.appDir, opts.elidableComponents);
+    const { eager: eagerComponents, lazy: renderedLazy } =
+      componentPreloads(suspenseCtx.usedComponents, opts.appDir, opts.elidableComponents, lazyFiles);
+    const lazyComponents = { ...frontierLazy, ...renderedLazy };
+    // The preload walks skip a lazy component and the subtree reachable only
+    // through it (#1524), the same way they skip an elided one: the browser
+    // does not fetch it until the loader asks.
+    const preloadSkip = lazyFiles && lazyFiles.size
+      ? new Set([...(opts.elidableComponents || []), ...lazyFiles.keys()])
+      : opts.elidableComponents;
     // The walk roots for BOTH preload passes are the BOOT's actually-shipped
     // module set (`moduleUrls`, which already drops inert page/layout modules and
     // substitutes an import-only page with its components), NOT the raw route
@@ -1155,7 +1172,7 @@ export async function ssrPage(route, params, url, opts) {
       shippedRoots,
       opts.appDir,
       opts.serverFiles,
-      opts.elidableComponents,
+      preloadSkip,
     );
     // Vendor modulepreload (#754): flatten the npm CDN waterfall by hinting the
     // vendor URLs the page's SHIPPED modules actually import, fetched in parallel
@@ -1169,7 +1186,7 @@ export async function ssrPage(route, params, url, opts) {
         shippedRoots,
         eagerComponents,
         opts.appDir,
-        opts.elidableComponents,
+        preloadSkip,
         opts.serverFiles,
       ),
     );