@webjsdev/server 0.8.3 → 0.8.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "type": "module",
   "description": "webjs dev/prod server: SSR, router, API, server actions, live reload",
   "main": "index.js",

package/src/component-elision.js

@@ -132,6 +132,21 @@ const CLIENT_ROUTER_IMPORTS = ['navigate', 'enableClientRouter', 'disableClientR
 
 /** Identifiers that only exist in a browser; their presence means client work. */
 const CLIENT_GLOBAL_RE = /\b(?:window|document|navigator|localStorage|sessionStorage|customElements|matchMedia|addEventListener)\b/;
+
+/**
+ * Cross-module observation of a component's registration. A module that
+ * observes another component's tag forces that component to register on the
+ * client, so the observed component cannot be elided even when its own render
+ * is display-only (eliding it drops its `customElements.define`, after which
+ * the observation silently fails). These scan for the three statically visible
+ * forms; the captured group is the observed tag (or class) name.
+ * - `customElements.whenDefined('my-tag')` / `whenDefined("my-tag")`
+ * - a CSS `my-tag:defined { … }` selector
+ * - `x instanceof MyClass` (mapped back to a tag via the component's className)
+ */
+const WHEN_DEFINED_RE = /\bwhenDefined\s*\(\s*['"`]([a-z][a-z0-9]*-[a-z0-9-]*)['"`]/g;
+const TAG_DEFINED_RE = /\b([a-z][a-z0-9]*-[a-z0-9-]*):defined\b/g;
+const INSTANCEOF_RE = /\binstanceof\s+([A-Z][A-Za-z0-9_$]*)/g;
 /** Same, for component source, minus `customElements` (the registration call
  * `customElements.define(...)` legitimately uses it and must not force ship). */
 const COMPONENT_CLIENT_GLOBAL_RE = /\b(?:window|document|navigator|localStorage|sessionStorage|matchMedia|addEventListener)\b/;
@@ -598,9 +613,12 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
   const componentFiles = new Set();
   /** @type {Map<string, string>} */
   const tagToFile = new Map();
+  /** @type {Map<string, string>} className -> file, for instanceof observation */
+  const classToFile = new Map();
   for (const c of components) {
     componentFiles.add(c.file);
     tagToFile.set(c.tag, c.file);
+    if (c.className) classToFile.set(c.className, c.file);
   }
 
   /** @type {Set<string>} */
@@ -615,6 +633,9 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
   const clientGlobalOrBareFiles = new Set();
   /** @type {Set<string>} */
   const serverFiles = new Set();
+  /** @type {Set<string>} component files forced to ship because some module
+   * observes their registration (whenDefined / :defined / instanceof). */
+  const observedComponentFiles = new Set();
 
   /** @type {Set<string>} */
   const allFiles = new Set(componentFiles);
@@ -646,8 +667,29 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
     if (componentFiles.has(file) && analyzeComponentSource(src).interactive) {
       mustShip.add(file);
     }
+    // Cross-module registration observation (#169): if THIS module observes
+    // another component's tag, that component must register client-side, so
+    // it cannot be elided. Map each observed tag/class back to its component
+    // file. Resolution against tagToFile / classToFile happens after the loop
+    // (all components are known up front, but we collect here while we hold
+    // each source). Verdict-safe: only ever forces MORE components to ship.
+    for (const m of src.matchAll(WHEN_DEFINED_RE)) {
+      const f = tagToFile.get(m[1]); if (f) observedComponentFiles.add(f);
+    }
+    for (const m of src.matchAll(TAG_DEFINED_RE)) {
+      const f = tagToFile.get(m[1]); if (f) observedComponentFiles.add(f);
+    }
+    for (const m of src.matchAll(INSTANCEOF_RE)) {
+      const f = classToFile.get(m[1]); if (f) observedComponentFiles.add(f);
+    }
   }
 
+  // Force every observed component to ship before the fixpoint runs, so the
+  // render/import rules propagate from it too. Dynamic tag strings and external
+  // (non graph-reachable) stylesheets remain an author-facing caveat, since
+  // static analysis cannot see them.
+  for (const f of observedComponentFiles) mustShip.add(f);
+
   // Reverse import edges (who imports each file), built once from the graph.
   // Drives both the closure-client-work reachability below and the fixpoint's
   // import rule, each in O(N+E) rather than a per-component closure walk.

package/src/dev.js

@@ -549,6 +549,16 @@ export async function createRequestHandler(opts) {
         }
         return Response.json({ status: 'ok' }, { headers: noStore });
       }
+      // Framework-internal static assets (the @webjsdev/core runtime, the dev
+      // reload client, downloaded vendor bundles) depend on neither the analysis
+      // nor the vendor importmap, so serve them BEFORE ensureReady(). Otherwise a
+      // cold instance blocks them behind the first vendor resolve (issue #190),
+      // and the core bundle is on every page's boot path, so that stalled first
+      // interactivity site-wide. Matched on the decoded path, like handleCore.
+      let assetPath = probePath;
+      try { assetPath = decodeURIComponent(probePath); } catch { /* keep raw on malformed escape */ }
+      const staticResp = await tryServeFrameworkStatic(assetPath, req.method.toUpperCase(), { coreDir, appDir, dev });
+      if (staticResp) return staticResp;
       // Build all whole-app analysis on the first request (memoized), before
       // any SSR, module serve, gate check, action dispatch, or middleware runs.
       await ensureReady();
@@ -775,23 +785,29 @@ export async function startServer(opts) {
  * @param {Request} req
  * @param {{state: any, appDir: string, coreDir: string, dev: boolean}} ctx
  */
-async function handleCore(req, ctx) {
-  const { state, appDir, coreDir, dev } = ctx;
-  const url = new URL(req.url);
-  // Decode percent-encoded characters so filesystem lookups match real
-  // filenames. Dynamic route segments like `[slug]` and route groups like
-  // `(marketing)` contain chars that browsers percent-encode in URLs
-  // (`%5B`, `%5D`, `%28`, `%29`). Without decoding, the server joins the
-  // encoded path with the app directory → file not found → 404 → no JS
-  // loads → no interactivity.
-  let path;
-  try { path = decodeURIComponent(url.pathname); } catch { path = url.pathname; }
-  const method = req.method.toUpperCase();
-
-  // Health / readiness probes (`/__webjs/health`, `/__webjs/ready`) are handled
-  // in `handle()` BEFORE ensureReady, so they are not repeated here.
+/**
+ * Serve framework-internal static assets that depend on NEITHER the whole-app
+ * analysis NOR the vendor importmap: the `@webjsdev/core` runtime files, the
+ * dev reload client, and (in `--download` pin mode) the committed vendor
+ * bundles. `handle()` calls this BEFORE `ensureReady()`, so a cold instance
+ * returns them immediately instead of blocking on the first vendor resolve
+ * (issue #190). The core bundle is on every page's boot path, so coupling it
+ * to the jspm resolve stalled first interactivity site-wide on a cold instance.
+ *
+ * Like the health / readiness probes (also answered pre-`ensureReady`), these
+ * bypass app middleware. That is correct: they are framework infrastructure the
+ * app needs to function, not app routes, and `state.middleware` is not even
+ * loaded until `ensureReady()` completes.
+ *
+ * @param {string} path decoded pathname
+ * @param {string} method upper-cased HTTP method
+ * @param {{ coreDir: string, appDir: string, dev: boolean }} ctx
+ * @returns {Promise<Response|null>} a Response, or null when path is not one of these assets
+ */
+async function tryServeFrameworkStatic(path, method, ctx) {
+  const { coreDir, appDir, dev } = ctx;
 
-  // Dev live-reload client
+  // Dev live-reload client.
   if (path === '/__webjs/reload.js') {
     if (!dev) return new Response('Not found', { status: 404 });
     return new Response(RELOAD_CLIENT_JS, {
@@ -802,35 +818,38 @@ async function handleCore(req, ctx) {
   // Core module: /__webjs/core/*
   //
   // ETag + ~1h max-age, NOT immutable. The URL path is un-versioned
-  // (`/__webjs/core/src/render-client.js` etc.), so bumping
-  // `@webjsdev/core` ships different bytes at the same URL. An
-  // `immutable` cache-control directive at an edge CDN (Cloudflare,
-  // Vercel, Fly) keeps the prior bytes pinned for up to a year, which
-  // silently bricks the next deploy: browsers load the old client
-  // renderer against a server emitting the new SSR shape, and any
-  // exports added in the bump (e.g., the slot.js entry points landed
+  // (`/__webjs/core/src/render-client.js` etc.), so bumping `@webjsdev/core`
+  // ships different bytes at the same URL. An `immutable` cache-control
+  // directive at an edge CDN (Cloudflare, Vercel, Fly) keeps the prior bytes
+  // pinned for up to a year, which silently bricks the next deploy: browsers
+  // load the old client renderer against a server emitting the new SSR shape,
+  // and any exports added in the bump (e.g., the slot.js entry points landed
   // for 0.6.0) resolve to undefined in the cached file.
   // Regression: 2026-05-20, ui.webjs.dev tier-2 components after
   // @webjsdev/core 0.5.0 -> 0.6.0 republish.
   if (path.startsWith('/__webjs/core/')) {
     const rel = path.slice('/__webjs/core/'.length);
     const abs = resolve(coreDir, rel);
-    if (!abs.startsWith(coreDir)) return new Response('forbidden', { status: 403 });
+    // Trailing-separator boundary check, not a raw string prefix: a raw
+    // `startsWith(coreDir)` would admit a sibling like `@webjsdev/core-evil`,
+    // reachable via an encoded slash (`..%2f`, which survives URL normalization
+    // and then decodes to `../`). Match the public-root branch's guard.
+    if (abs !== coreDir && !abs.startsWith(coreDir + sep)) {
+      return new Response('forbidden', { status: 403 });
+    }
     return fileResponse(abs, { dev, immutable: false });
   }
 
-  // Vendor URL handler for `webjs vendor pin --download` mode only.
-  // In default pin mode (or no-pin mode) the importmap routes bare
-  // imports straight to ga.jspm.io URLs and the browser bypasses this
-  // server entirely. When the user ran `webjs vendor pin --download`,
-  // the importmap has local `/__webjs/vendor/<file>.js` URLs and this
-  // handler serves the committed bundle files from `.webjs/vendor/`.
+  // Vendor URL handler for `webjs vendor pin --download` mode only. In default
+  // pin mode (or no-pin mode) the importmap routes bare imports straight to
+  // ga.jspm.io URLs and the browser bypasses this server entirely. When the
+  // user ran `webjs vendor pin --download`, the importmap has local
+  // `/__webjs/vendor/<file>.js` URLs and this serves the committed bundle files
+  // from `.webjs/vendor/`. These are read-only static content: allow GET/HEAD
+  // for the normal fetch, OPTIONS for any cross-origin preflight (204 with the
+  // same Allow header rather than 405, which some intermediaries treat as a
+  // hard failure even for a CORS probe), and 405 everything else.
   if (path.startsWith('/__webjs/vendor/') && path.endsWith('.js')) {
-    // Vendor bundles are read-only static content. Allow GET/HEAD for
-    // the normal fetch, OPTIONS for any cross-origin preflight (we
-    // return 204 with the same Allow header rather than 405, which
-    // some intermediaries treat as a hard failure even for a CORS
-    // probe), and 405 everything else.
     if (method === 'OPTIONS') {
       return new Response(null, { status: 204, headers: { allow: 'GET, HEAD, OPTIONS' } });
     }
@@ -846,6 +865,31 @@ async function handleCore(req, ctx) {
     return resp;
   }
 
+  return null;
+}
+
+async function handleCore(req, ctx) {
+  const { state, appDir, coreDir, dev } = ctx;
+  const url = new URL(req.url);
+  // Decode percent-encoded characters so filesystem lookups match real
+  // filenames. Dynamic route segments like `[slug]` and route groups like
+  // `(marketing)` contain chars that browsers percent-encode in URLs
+  // (`%5B`, `%5D`, `%28`, `%29`). Without decoding, the server joins the
+  // encoded path with the app directory → file not found → 404 → no JS
+  // loads → no interactivity.
+  let path;
+  try { path = decodeURIComponent(url.pathname); } catch { path = url.pathname; }
+  const method = req.method.toUpperCase();
+
+  // Health / readiness probes (`/__webjs/health`, `/__webjs/ready`) and the
+  // framework-internal static assets (`/__webjs/core/*`, `/__webjs/reload.js`,
+  // downloaded `/__webjs/vendor/*`) are served in `handle()` BEFORE ensureReady,
+  // so they are not repeated here. This fallback covers the (currently
+  // unreachable) case of handleCore being entered for one of those assets, so
+  // the routing stays correct if a future caller bypasses the early path.
+  const frameworkStatic = await tryServeFrameworkStatic(path, method, { coreDir, appDir, dev });
+  if (frameworkStatic) return frameworkStatic;
+
   // Internal server-action RPC endpoint
   const actMatch = /^\/__webjs\/action\/([a-f0-9]+)\/([A-Za-z0-9_$]+)$/.exec(path);
   if (actMatch) {