@webjsdev/server 0.8.6 → 0.8.7

package/package.json

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

package/src/auth.js

@@ -86,7 +86,7 @@ function clearCookie(name) {
 // -- JWT --------------------------------------------------------------------
 
 /** @param {Record<string,unknown>} payload @param {string} secret */
-async function encodeJwt(payload, secret) {
+export async function encodeJwt(payload, secret) {
   const h = b64url(enc.encode(JSON.stringify({ alg: 'HS256', typ: 'JWT' })));
   const p = b64url(enc.encode(JSON.stringify(payload)));
   const unsigned = `${h}.${p}`;
@@ -95,7 +95,7 @@ async function encodeJwt(payload, secret) {
 }
 
 /** @param {string} token @param {string} secret @returns {Promise<Record<string,unknown>|null>} */
-async function decodeJwt(token, secret) {
+export async function decodeJwt(token, secret) {
   const parts = token.split('.');
   if (parts.length !== 3) return null;
   // `unb64url` → `atob` throws InvalidCharacterError on non-base64 input.

package/src/check.js

@@ -114,6 +114,11 @@ export const RULES = [
     description:
       'Verifies the `.gitignore` exception for `.webjs/vendor/` is structurally correct via `git check-ignore`. The intended pattern is `.webjs/*` (NOT `.webjs/`) plus `!.webjs/vendor/` plus `!.webjs/vendor/**`. The common-looking pattern `.webjs/` excludes the directory itself, after which git cannot re-include children (gitignore semantics: a parent exclusion blocks child negations). Without this rule, an AI agent or human editor would silently break `webjs vendor pin` by simplifying the pattern; the failure is invisible until production. Rule fires when the working directory is a git repo and a `.gitignore` exists; skipped when neither is true.',
   },
+  {
+    name: 'no-browser-globals-in-render',
+    description:
+      'Flags browser-only APIs used in a WebComponent constructor or render() method. The SSR pipeline instantiates the component (running the constructor) and calls render() to produce HTML, on a bare server-side class with no DOM. So a browser global (document, window, localStorage, sessionStorage, navigator, location, matchMedia, screen, history) or an HTMLElement instance member on `this` (attachShadow, shadowRoot, setAttribute, getAttribute, removeAttribute, dispatchEvent, classList, querySelector, querySelectorAll, getBoundingClientRect, focus, blur, scrollIntoView) touched there throws at SSR time (the isomorphic footgun). These belong in connectedCallback() or a lifecycle hook (firstUpdated/updated), which SSR never calls; seed first-paint defaults in the constructor only from server-known inputs (attributes, props). Conservative: only the constructor and render bodies are scanned (the methods SSR actually runs), and only direct references, so helper indirection is not flagged (the runtime SSR error covers that case).',
+  },
 ];
 
 /** Set of all known rule names for fast lookup. */
@@ -389,6 +394,72 @@ function findFieldInitializers(classBody, props) {
   return out;
 }
 
+// Browser-only globals that are undefined during SSR (the server-side
+// WebComponent base is a bare class with no DOM). High-confidence names only
+// (unlikely to be ordinary local variables), so the rule stays low-noise.
+const BROWSER_GLOBALS = [
+  'document', 'window', 'localStorage', 'sessionStorage', 'navigator',
+  'matchMedia', 'requestAnimationFrame', 'getComputedStyle',
+  'IntersectionObserver', 'MutationObserver', 'ResizeObserver',
+];
+// HTMLElement instance members that do not exist on the bare server class, so
+// `this.<member>` throws (a method call) or is `undefined` (a property) at SSR.
+const HTMLELEMENT_MEMBERS = [
+  'attachShadow', 'shadowRoot', 'setAttribute', 'getAttribute',
+  'removeAttribute', 'hasAttribute', 'dispatchEvent', 'classList',
+  'querySelector', 'querySelectorAll', 'getBoundingClientRect',
+  'focus', 'blur', 'scrollIntoView',
+];
+
+/**
+ * Extract the body text of a named method from a (redacted) class body, or
+ * '' if absent. Handles `async`, a TS return-type annotation, and params.
+ * @param {string} classBody
+ * @param {string} name
+ */
+function methodBodyOf(classBody, name) {
+  const re = new RegExp(`(?:^|[\\s;}])(?:async\\s+)?${name}\\s*\\([^)]*\\)\\s*(?::[^{]*)?\\{`, 'g');
+  const m = re.exec(classBody);
+  if (!m) return '';
+  const open = classBody.indexOf('{', m.index + m[0].length - 1);
+  if (open === -1) return '';
+  const close = matchClosingBrace(classBody, open + 1);
+  return close === -1 ? '' : classBody.slice(open + 1, close);
+}
+
+/**
+ * Find browser-only globals and HTMLElement `this.<member>` accesses in a
+ * (redacted) method body. Returns one entry per distinct member.
+ * @param {string} code
+ * @returns {{ member: string, kind: string }[]}
+ */
+function findBrowserMemberUses(code) {
+  // The class body arrives template-redacted, but `redactStringsAndTemplates`
+  // keeps single/double-quoted string CONTENT (real specifiers ride strings).
+  // Blank that too so a browser word inside a string literal (e.g. a label
+  // `'open the document'`) is not mistaken for a real global access.
+  code = code
+    .replace(/'(?:[^'\\]|\\.)*'/g, (s) => `'${' '.repeat(Math.max(0, s.length - 2))}'`)
+    .replace(/"(?:[^"\\]|\\.)*"/g, (s) => `"${' '.repeat(Math.max(0, s.length - 2))}"`);
+  const out = [];
+  const seen = new Set();
+  const gRe = new RegExp(`(?<![.\\w$])(${BROWSER_GLOBALS.join('|')})\\b`, 'g');
+  let m;
+  while ((m = gRe.exec(code)) !== null) {
+    if (seen.has(m[1])) continue;
+    seen.add(m[1]);
+    out.push({ member: m[1], kind: 'a browser global' });
+  }
+  const hRe = new RegExp(`\\bthis\\.(${HTMLELEMENT_MEMBERS.join('|')})\\b`, 'g');
+  while ((m = hRe.exec(code)) !== null) {
+    const key = `this.${m[1]}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push({ member: key, kind: 'an HTMLElement member' });
+  }
+  return out;
+}
+
 /**
  * Scan a webjs app directory and report convention violations.
  *
@@ -557,6 +628,31 @@ export async function checkConventions(appDir, opts) {
     }
   }
 
+  // --- Rule: no-browser-globals-in-render ---
+  // The SSR pipeline runs the constructor (`new Cls()`) and calls `render()`
+  // on a bare server-side class with no DOM. A browser global or an
+  // HTMLElement member on `this` touched there throws at SSR time. Those
+  // belong in connectedCallback / lifecycle hooks, which SSR never calls.
+  if (isRuleEnabled('no-browser-globals-in-render', overrides)) {
+    for (const { rel, scan } of files) {
+      if (!/class\s+\w+\s+extends\s+WebComponent/.test(scan)) continue;
+      for (const body of extractWebComponentClassBodies(scan)) {
+        for (const method of ['constructor', 'render']) {
+          const code = methodBodyOf(body, method);
+          if (!code) continue;
+          for (const { member, kind } of findBrowserMemberUses(code)) {
+            violations.push({
+              rule: 'no-browser-globals-in-render',
+              file: rel,
+              message: `\`${member}\` (${kind}) is used in ${method}(), which runs during SSR where it is not available, so it throws and the component fails to server-render.`,
+              fix: `Move browser-only work to connectedCallback() or a lifecycle hook (firstUpdated/updated), which SSR never calls. Seed first-paint defaults in the constructor only from server-known inputs (attributes / props), then refine in connectedCallback by writing to a signal.`,
+            });
+          }
+        }
+      }
+    }
+  }
+
   // --- Rule: no-server-env-in-components ---
   // Catches `process.env.X` reads in component files where X is not a
   // WEBJS_PUBLIC_* var and not NODE_ENV. The SSR shim only exposes those

package/src/component-elision.js

@@ -41,6 +41,7 @@ import {
   extractWebComponentClassBodies,
   matchClosingBrace,
   redactStringsAndTemplates,
+  maskComments,
 } from './js-scan.js';
 import { transitiveDeps } from './module-graph.js';
 
@@ -553,9 +554,13 @@ function topLevelPropertyValues(obj) {
 export function extractRenderedTags(src) {
   /** @type {Set<string>} */
   const tags = new Set();
+  // Mask comments first so a `<some-tag>` written in a doc comment is not read
+  // as a rendered tag (#179). String and template content is kept, so real tags
+  // inside `html` templates are still found.
+  const masked = maskComments(src);
   const re = /<([a-z][a-z0-9]*-[a-z0-9-]*)\b/g;
   let m;
-  while ((m = re.exec(src)) !== null) tags.add(m[1]);
+  while ((m = re.exec(masked)) !== null) tags.add(m[1]);
   return tags;
 }
 
@@ -656,15 +661,24 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
       continue;
     }
     if (typeof src !== 'string') continue;
-    fileTags.set(file, extractRenderedTags(src));
-    if (importsReactivePrimitive(src)) reactiveFiles.add(file);
-    if (importsClientRouter(src)) clientRouterFiles.add(file);
-    if (EVENT_BINDING_RE.test(src) || EVENT_PROP_RE.test(src) ||
-        importsSideEffectNonCorePackage(src) || CLIENT_GLOBAL_RE.test(src) ||
-        hasModuleScopeSideEffect(src)) {
+    // Mask comments once for every signal scan below (#179): a `<tag>`, an
+    // `@event`, a browser global, an `import`, or a `whenDefined` written in a
+    // comment must not register as a real signal. String and template content
+    // is kept, so a real rendered tag, a real `@click=${}` in an html template,
+    // and a real `whenDefined('tag')` (the tag rides a string) still match.
+    // (`importsSideEffectNonCorePackage` / `hasModuleScopeSideEffect` /
+    // `analyzeComponentSource` also redact strings/templates internally; running
+    // 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)) {
       clientGlobalOrBareFiles.add(file);
     }
-    if (componentFiles.has(file) && analyzeComponentSource(src).interactive) {
+    if (componentFiles.has(file) && analyzeComponentSource(masked).interactive) {
       mustShip.add(file);
     }
     // Cross-module registration observation (#169): if THIS module observes
@@ -673,13 +687,13 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
     // 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)) {
+    for (const m of masked.matchAll(WHEN_DEFINED_RE)) {
       const f = tagToFile.get(m[1]); if (f) observedComponentFiles.add(f);
     }
-    for (const m of src.matchAll(TAG_DEFINED_RE)) {
+    for (const m of masked.matchAll(TAG_DEFINED_RE)) {
       const f = tagToFile.get(m[1]); if (f) observedComponentFiles.add(f);
     }
-    for (const m of src.matchAll(INSTANCEOF_RE)) {
+    for (const m of masked.matchAll(INSTANCEOF_RE)) {
       const f = classToFile.get(m[1]); if (f) observedComponentFiles.add(f);
     }
   }

package/src/dev.js

@@ -105,10 +105,13 @@ const MIME = {
  * lint rules catch these at edit time. webjs is buildless end-to-end:
  * there is no bundler fallback.
  *
- * @type {Map<string, { mtimeMs: number, code: string, map: string | null }>}
+ * The transformed bytes are cached per request handler in `state.tsCache`
+ * (a `Map<string, { mtimeMs, code, map }>`), bounded to `TS_CACHE_MAX`
+ * entries. The cache is per-handler rather than module-global because the
+ * cached code bakes in that handler's elision verdict, so two handlers for
+ * the same app with different elision settings must not share it.
  */
 const TS_CACHE_MAX = 500;
-const TS_CACHE = new Map();
 
 /**
  * Auto-load `<appDir>/.env` into `process.env` once at boot. Mirrors
@@ -148,16 +151,40 @@ function loadAppEnv(appDir) {
 }
 
 /**
- * Read the project-level elision switch from `package.json`.
- * `{ "webjs": { "elide": false } }` disables display-only and inert-route
- * elision app-wide (everything ships, like before the feature existed).
- * Any other value, or an absent key, leaves elision enabled (the default).
- * Re-read on every rebuild so toggling the switch takes effect without a
- * server restart.
+ * Read the `WEBJS_ELIDE` environment override, if set.
+ * `0` / `false` / `off` / `no` (case-insensitive) force elision OFF;
+ * `1` / `true` / `on` / `yes` force it ON. Any other value, or an unset
+ * variable, returns `undefined` so the caller falls through to the
+ * `package.json` switch. The env override is the deploy-time / ops escape
+ * hatch: force-disable elision to rule it out while debugging a wrong-strip
+ * without editing committed code, or force-enable it regardless of an
+ * app's `package.json`. It is also the seam the differential elision test
+ * uses to render the same app on and off in one process.
+ * @returns {boolean | undefined}
+ */
+function elideEnvOverride() {
+  const raw = process.env.WEBJS_ELIDE;
+  if (raw == null || raw === '') return undefined;
+  const v = String(raw).trim().toLowerCase();
+  if (v === '0' || v === 'false' || v === 'off' || v === 'no') return false;
+  if (v === '1' || v === 'true' || v === 'on' || v === 'yes') return true;
+  return undefined;
+}
+
+/**
+ * Read the project-level elision switch.
+ * Precedence: the `WEBJS_ELIDE` env override wins when set, otherwise the
+ * `package.json` `{ "webjs": { "elide": false } }` switch disables
+ * display-only and inert-route elision app-wide (everything ships, like
+ * before the feature existed). Any other value, or an absent key, leaves
+ * elision enabled (the default). Re-read on every rebuild so toggling
+ * either control takes effect without a server restart.
  * @param {string} appDir
  * @returns {Promise<boolean>}
  */
-async function readElideEnabled(appDir) {
+export async function readElideEnabled(appDir) {
+  const override = elideEnvOverride();
+  if (override !== undefined) return override;
   try {
     const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
     if (pkg && pkg.webjs && pkg.webjs.elide === false) return false;
@@ -267,6 +294,12 @@ export async function createRequestHandler(opts) {
     elidableComponents: new Set(),
     inertRouteModules: new Set(),
     browserBoundFiles: null,
+    // Transformed-source cache (stripped TS + applied elision). Per-handler,
+    // NOT module-global: the cached bytes bake in THIS handler's elision
+    // verdict, so two handlers for the same app with different elision
+    // settings (a multi-tenant embedder, or the differential elision test)
+    // must not share it, or the second would serve the first's elided source.
+    tsCache: new Map(),
   };
 
   // All whole-app analysis is built lazily on the first request, memoized so
@@ -500,12 +533,12 @@ export async function createRequestHandler(opts) {
     // it so routing reflects added/removed route files immediately.
     state.routeTable = await buildRouteTable(appDir);
     clearVendorCache();
-    TS_CACHE.clear();
+    state.tsCache.clear();
     // Invalidate the lazy analysis; the next request rebuilds the graph,
     // component scan, gate, action index, middleware, elision, and vendor map.
     // Wait out any in-flight build first so it cannot commit stale results
     // after the reset. A dependency edit can flip an elision verdict without
-    // changing an importer's mtime, hence the TS_CACHE.clear above.
+    // changing an importer's mtime, hence the state.tsCache.clear above.
     if (readyInFlight) { try { await readyInFlight; } catch {} }
     // Bump the vendor generation so a vendor resolve still in flight from the
     // previous build cannot flip vendorResolved against the fresh state.
@@ -1028,7 +1061,7 @@ async function handleCore(req, ctx) {
         appDir,
       };
       if (/\.m?ts$/.test(abs)) {
-        return tsResponse(abs, dev, elideOpts);
+        return tsResponse(abs, dev, elideOpts, state.tsCache);
       }
       if (/\.m?js$/.test(abs)) {
         return jsModuleResponse(abs, dev, elideOpts);
@@ -1412,17 +1445,21 @@ async function stripTs(source, _abs) {
 
 /**
  * Serve a `.ts` / `.mts` source file as JavaScript via {@link stripTs}.
- * Result is cached by mtime so subsequent requests are instant; a
- * file edit invalidates naturally. `elideOpts` additionally strips
- * side-effect imports of display-only components from the served code.
+ * Result is cached by mtime in the handler's own `cache` so subsequent
+ * requests are instant; a file edit invalidates naturally. `elideOpts`
+ * additionally strips side-effect imports of display-only components from
+ * the served code, which is exactly why `cache` is the per-handler
+ * `state.tsCache` and not a module-global: the cached bytes bake in this
+ * handler's elision verdict.
  *
  * @param {string} abs
  * @param {boolean} dev
  * @param {{ moduleGraph: any, elidableComponents: Set<string>|undefined, appDir: string }} [elideOpts]
+ * @param {Map<string, { mtimeMs: number, code: string, map: string | null }>} cache the handler's `state.tsCache`
  */
-async function tsResponse(abs, dev, elideOpts) {
+async function tsResponse(abs, dev, elideOpts, cache) {
   const st = await stat(abs);
-  const cached = TS_CACHE.get(abs);
+  const cached = cache.get(abs);
   if (cached && cached.mtimeMs === st.mtimeMs) {
     return new Response(cached.code, {
       headers: {
@@ -1475,11 +1512,11 @@ async function tsResponse(abs, dev, elideOpts) {
     );
   }
   // Evict oldest entry if cache is full (simple FIFO: Map preserves insertion order).
-  if (TS_CACHE.size >= TS_CACHE_MAX) {
-    const oldest = TS_CACHE.keys().next().value;
-    TS_CACHE.delete(oldest);
+  if (cache.size >= TS_CACHE_MAX) {
+    const oldest = cache.keys().next().value;
+    cache.delete(oldest);
   }
-  TS_CACHE.set(abs, { mtimeMs: st.mtimeMs, code, map: null });
+  cache.set(abs, { mtimeMs: st.mtimeMs, code, map: null });
   return new Response(code, {
     headers: {
       'content-type': 'application/javascript; charset=utf-8',

package/src/js-scan.js

@@ -221,6 +221,111 @@ export function redactStringsAndTemplates(src) {
   return out;
 }
 
+/**
+ * Blank ONLY comments, keeping string AND template-literal content verbatim
+ * (position-preserving: same length, newlines kept). The sibling
+ * `redactStringsAndTemplates` blanks templates too, which is wrong for callers
+ * that need to read inside `html` templates (the elision render-tag scanner) or
+ * inside string arguments (`whenDefined('tag')`). This keeps both and removes
+ * only comment text, so prose in a comment cannot be read as a real signal
+ * (issue #179). It reuses the same regex-versus-division and tagged-template
+ * disambiguation so a `//` inside a string/template/regex is never mistaken for
+ * a comment.
+ *
+ * @param {string} src
+ * @returns {string} src with comment bodies blanked, everything else verbatim
+ */
+export function maskComments(src) {
+  const n = src.length;
+  let out = '';
+  let i = 0;
+  let lastSig = '';
+  let lastWord = '';
+  let lastWordIsProp = false;
+  let lastWasIncDec = false;
+  const markValue = () => { lastSig = 'x'; lastWord = ''; lastWordIsProp = false; lastWasIncDec = false; };
+  const isRegex = () => {
+    if (lastSig === '') return true;
+    if (lastSig === ')' || lastSig === ']') return false;
+    if (lastSig === "'" || lastSig === '"' || lastSig === '`') return false;
+    if (lastWasIncDec) return false;
+    if (/[\w$]/.test(lastSig)) return !lastWordIsProp && REGEX_PRECEDING_KEYWORDS.has(lastWord);
+    return true;
+  };
+  // Comments: blank the body (keep the `//` / `/* */` delimiters and newlines).
+  const scanLineComment = () => { out += '//'; i += 2; while (i < n && src[i] !== '\n') { out += ' '; i++; } };
+  const scanBlockComment = () => {
+    out += '/*'; i += 2;
+    while (i < n) {
+      if (src[i] === '*' && src[i + 1] === '/') { out += '*/'; i += 2; return; }
+      out += src[i] === '\n' ? '\n' : ' '; i++;
+    }
+  };
+  // String / template / regex: copy verbatim, but lex correctly so a `//` or
+  // `/*` inside them is not treated as a comment.
+  const scanString = (q) => {
+    out += q; i++;
+    while (i < n) {
+      if (src[i] === '\\' && i + 1 < n) { out += src[i] + src[i + 1]; i += 2; continue; }
+      if (src[i] === q) { out += q; i++; break; }
+      if (src[i] === '\n') { out += '\n'; i++; break; }
+      out += src[i]; i++;
+    }
+    markValue();
+  };
+  const scanRegex = () => {
+    out += '/'; i++;
+    let inClass = false;
+    while (i < n) {
+      const d = src[i];
+      if (d === '\\' && i + 1 < n) { out += d + src[i + 1]; i += 2; continue; }
+      if (d === '\n') break;
+      if (d === '[') inClass = true;
+      else if (d === ']') inClass = false;
+      else if (d === '/' && !inClass) { out += '/'; i++; break; }
+      out += d; i++;
+    }
+    markValue();
+  };
+  const scanTemplate = () => {
+    out += '`'; i++;
+    while (i < n) {
+      const c = src[i];
+      if (c === '\\' && i + 1 < n) { out += c + src[i + 1]; i += 2; continue; }
+      if (c === '`') { out += '`'; i++; break; }
+      if (c === '$' && src[i + 1] === '{') { out += '${'; i += 2; scanCode(true); if (i < n && src[i] === '}') { out += '}'; i++; } continue; }
+      out += c; i++;
+    }
+    markValue();
+  };
+  function scanCode(stopHole) {
+    let brace = 0;
+    while (i < n) {
+      const c = src[i], next = src[i + 1];
+      if (stopHole && c === '}' && brace === 0) return;
+      if (c === '/' && next === '/') { scanLineComment(); continue; }
+      if (c === '/' && next === '*') { scanBlockComment(); continue; }
+      if (c === '/' && isRegex()) { scanRegex(); continue; }
+      if (c === "'" || c === '"') { scanString(c); continue; }
+      if (c === '`') { scanTemplate(); continue; }
+      if (c === '{') { brace++; lastSig = '{'; lastWord = ''; lastWasIncDec = false; out += c; i++; continue; }
+      if (c === '}') { brace--; lastSig = '}'; lastWord = ''; lastWasIncDec = false; out += c; i++; continue; }
+      if (/[A-Za-z_$]/.test(c)) {
+        const prop = lastSig === '.';
+        let w = '';
+        while (i < n && /[\w$]/.test(src[i])) { w += src[i]; out += src[i]; i++; }
+        lastWord = w; lastSig = w[w.length - 1]; lastWordIsProp = prop; lastWasIncDec = false;
+        continue;
+      }
+      if (/\s/.test(c)) { out += c; i++; continue; }
+      lastWasIncDec = (c === '+' || c === '-') && c === lastSig;
+      lastSig = c; lastWord = ''; out += c; i++;
+    }
+  }
+  scanCode(false);
+  return out;
+}
+
 /**
  * Extract the body of every `class … extends WebComponent { … }` block.
  * Brace-counts to handle nested template literals, methods, and arrow