@webjsdev/server 0.8.75 → 0.8.77

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.75",
+  "version": "0.8.77",
   "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/component-elision.js

@@ -1519,3 +1519,154 @@ 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;
+}
+
+/** `import <bindings> from 'x'` (the bindings part is captured). */
+const BINDING_IMPORT_RE = /\bimport\s+(type\s+)?([\w$*{}\s,]+?)\s+from\s+(['"])([^'"]+)\3/g;
+/** `export { a } from 'x'` / `export * from 'x'` (a re-export needs the module too). */
+const REEXPORT_RE = /\bexport\s+(type\s+)?(?:\*|\{[^}]*\}|\*\s+as\s+[\w$]+)\s+from\s+(['"])([^'"]+)\2/g;
+
+/**
+ * Is this import clause types only (`import type { A }`, or every named
+ * specifier marked `type`)? Those are erased before the browser sees them.
+ *
+ * @param {string | undefined} typeKw
+ * @param {string} clause
+ */
+function typeOnlyClause(typeKw, clause) {
+  if (typeKw) return true;
+  const m = clause.trim().match(/^\{([\s\S]*)\}$/);
+  if (!m) return false;
+  const names = m[1].split(',').map((s) => s.trim()).filter(Boolean);
+  return names.length > 0 && names.every((n) => /^type\s/.test(n));
+}
+
+/**
+ * The lazy component files some module imports WITH bindings (#1524). A
+ * binding import loads the module eagerly whatever the class says, because the
+ * importer needs the value when it runs. Such a file is not lazy in practice,
+ * so the caller drops it from the lazy set: otherwise the preload walks would
+ * skip a module the browser still fetches up front, which only makes it slower.
+ *
+ * Only importers whose graph edges reach a lazy file are read. A server file is
+ * never served, so its imports do not count.
+ *
+ * @param {Map<string, string[]>} lazyFiles
+ * @param {import('./module-graph.js').ModuleGraph | undefined} moduleGraph
+ * @param {(file: string) => Promise<string>} readFileFn
+ * @param {(spec: string, fromFile: string, appDir: string) => (string|null)} resolveImport
+ * @param {string} appDir
+ * @returns {Promise<Set<string>>}
+ */
+export async function bindingImportedLazyFiles(lazyFiles, moduleGraph, readFileFn, resolveImport, appDir) {
+  /** @type {Set<string>} */
+  const out = new Set();
+  if (!lazyFiles.size || !moduleGraph) return out;
+  for (const [importer, deps] of moduleGraph) {
+    if (SERVER_FILE_RE.test(importer)) continue;
+    let reaches = false;
+    for (const d of deps) if (lazyFiles.has(d) && !out.has(d)) { reaches = true; break; }
+    if (!reaches) continue;
+    let src;
+    try { src = await readFileFn(importer); } catch { continue; }
+    const code = redactStringsAndTemplates(maskComments(src));
+    for (const m of code.matchAll(BINDING_IMPORT_RE)) {
+      if (typeOnlyClause(m[1], m[2])) continue;
+      const abs = resolveImport(m[4], importer, appDir);
+      if (abs && lazyFiles.has(abs)) out.add(abs);
+    }
+    for (const m of code.matchAll(REEXPORT_RE)) {
+      if (m[1]) continue;
+      const abs = resolveImport(m[3], importer, appDir);
+      if (abs && lazyFiles.has(abs)) out.add(abs);
+    }
+  }
+  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

@@ -31,9 +31,9 @@ import { mintNonce, buildCspHeader, cspHeaderName } from '../csp.js';
 import { propagateTrustedRemoteIp } from '../rate-limit.js';
 import { reachedBareImports, resolveVendorImports, clearVendorCache, hasVendorPin, readPinFile, prunePinToReachable } from '../vendor.js';
 import { browserEntryFiles } from '../browser-entries.js';
-import { buildModuleGraph, seenFilesFor, appImportsMap, reachableFromEntries } from '../module-graph.js';
+import { buildModuleGraph, seenFilesFor, appImportsMap, reachableFromEntries, resolveImport } from '../module-graph.js';
 import { primeComponentRegistry, findOrphanComponents, scanComponents } from '../component-scanner.js';
-import { analyzeElision } from '../component-elision.js';
+import { analyzeElision, lazyComponentFiles, bindingImportedLazyFiles } 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,11 @@ export async function createRequestHandler(opts) {
             state.elidableComponents = r.elidableComponents;
             state.inertRouteModules = r.inertRouteModules;
             state.importOnlyRouteModules = r.importOnlyRouteModules;
+            state.lazyComponentFiles = lazyComponentFiles(components, state.elidableComponents);
+            // A lazy component some module imports WITH bindings loads eagerly
+            // anyway, so it keeps its preload hint and its imports as written.
+            for (const f of await bindingImportedLazyFiles(state.lazyComponentFiles, state.moduleGraph,
+              (f) => readFile(f, 'utf8'), resolveImport, appDir)) state.lazyComponentFiles.delete(f);
             // 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 +656,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,
       ),
     );