@webjsdev/server 0.8.31 → 0.8.33

package/src/js-scan.js

@@ -81,9 +81,38 @@ const REGEX_PRECEDING_KEYWORDS = new Set([
  * @returns {string}
  */
 export function redactStringsAndTemplates(src, blankStrings = false) {
+  return scanLiterals(src, { placeholder: false, blankStrings }).out;
+}
+
+/**
+ * Core string / template / comment lexer shared by `redactStringsAndTemplates`
+ * (#179) and `redactToPlaceholders` (#634). ONE walker owns the
+ * regex-versus-division, tagged-template, and `${...}`-nesting disambiguation,
+ * so the two output modes can never drift apart.
+ *
+ * Two output modes, selected by `placeholder`:
+ *  - MASK (placeholder=false): position-preserving mask (same length, newlines
+ *    kept). Comment and regex bodies blank to spaces; template bodies blank,
+ *    recursing `${...}` holes as blanked code; plain-string bodies stay VERBATIM
+ *    so a caller can read `register('tag')`, UNLESS `blankStrings` is set (then
+ *    string bodies blank too and the verbatim-template fast path is disabled).
+ *    `literals` is empty.
+ *  - PLACEHOLDER (placeholder=true): each string / template-text body is
+ *    replaced by a `__STR_<idx>__` token (delimiters kept) and pushed to
+ *    `literals`, while `${...}` holes are scanned as REAL code. Lets a caller
+ *    tell a real top-level `register(...)` / `import` from one shown inside a
+ *    code-sample literal (resolve the token via `literals[idx]`). In this mode
+ *    code is never blanked, so the mask emit-formulas below reduce to verbatim.
+ *
+ * @param {string} src
+ * @param {{ placeholder?: boolean, blankStrings?: boolean }} [opts]
+ * @returns {{ out: string, literals: string[] }}
+ */
+function scanLiterals(src, { placeholder = false, blankStrings = false } = {}) {
   const n = src.length;
   let out = '';
   let i = 0;
+  const literals = [];
   // Previous significant token in code position, tracked as we walk (more
   // robust than scanning `out`, whose tail is blanked spaces inside a hole).
   // `lastSig` is the last non-whitespace source char; `lastWord` is the last
@@ -112,7 +141,7 @@ export function redactStringsAndTemplates(src, blankStrings = false) {
     if (/[\w$]/.test(lastSig)) return !lastWordIsProp && REGEX_PRECEDING_KEYWORDS.has(lastWord);
     return true;
   };
-  // A template is tagged when the previous token is a value.
+  // A template is tagged when the previous token is a value (mask mode only).
   const isTagged = () => /[\w$)\]'"`]/.test(lastSig);
 
   const scanLineComment = () => {
@@ -140,9 +169,25 @@ export function redactStringsAndTemplates(src, blankStrings = false) {
     }
     markValue();
   };
-  // Strings: KEEP the body verbatim at top level (so tag-name-has-hyphen can
+  // Strings. PLACEHOLDER: collect the body into `literals` and emit
+  // `q__STR_idx__q`. MASK: KEEP the body verbatim (so tag-name-has-hyphen can
   // read register('foo')); blank it when inside an already-blanked hole.
   const scanString = (q, blank) => {
+    if (placeholder) {
+      i++;
+      let body = '';
+      while (i < n) {
+        if (src[i] === '\\' && i + 1 < n) { body += src[i] + src[i + 1]; i += 2; continue; }
+        if (src[i] === q) { i++; break; }
+        if (src[i] === '\n') { i++; break; }
+        body += src[i]; i++;
+      }
+      const idx = literals.length;
+      literals.push(body);
+      out += q + `__STR_${idx}__` + q;
+      markValue();
+      return;
+    }
     out += q; i++;
     while (i < n) {
       if (src[i] === '\\' && i + 1 < n) { out += blank ? '  ' : src[i] + src[i + 1]; i += 2; continue; }
@@ -152,9 +197,47 @@ export function redactStringsAndTemplates(src, blankStrings = false) {
     }
     markValue();
   };
-  // Template literal. `forceBlank` is set when already inside a blanked hole
-  // (everything nested blanks regardless of tag/shape).
+  // Template literal. PLACEHOLDER: each text segment becomes a `__STR_idx__`
+  // token (collected) and each `${...}` hole is scanned as REAL code. MASK:
+  // verbatim fast path for a simple closed single-line untagged literal, else
+  // blank the text and recurse holes as blanked code (`forceBlank` is set when
+  // already inside a blanked hole, so everything nested blanks regardless).
   const scanTemplate = (forceBlank) => {
+    if (placeholder) {
+      out += '`'; i++;
+      while (i < n) {
+        const c = src[i];
+        if (c === '\\' && i + 1 < n) {
+          let body = '\\' + src[i + 1];
+          i += 2;
+          while (i < n && src[i] !== '`' && !(src[i] === '$' && src[i + 1] === '{')) {
+            if (src[i] === '\\' && i + 1 < n) { body += src[i] + src[i + 1]; i += 2; continue; }
+            body += src[i]; i++;
+          }
+          const idx = literals.length;
+          literals.push(body);
+          out += `__STR_${idx}__`;
+          continue;
+        }
+        if (c === '`') { out += '`'; i++; break; }
+        if (c === '$' && src[i + 1] === '{') {
+          out += '${'; i += 2;
+          scanCode(true, false);
+          if (i < n && src[i] === '}') { out += '}'; i++; }
+          continue;
+        }
+        let body = '';
+        while (i < n && src[i] !== '`' && !(src[i] === '$' && src[i + 1] === '{')) {
+          if (src[i] === '\\' && i + 1 < n) { body += src[i] + src[i + 1]; i += 2; continue; }
+          body += src[i]; i++;
+        }
+        const idx = literals.length;
+        literals.push(body);
+        out += `__STR_${idx}__`;
+      }
+      markValue();
+      return;
+    }
     const tagged = isTagged();
     let hasInterp = false, hasNewline = false, closed = false, depth = 0, k = i + 1;
     while (k < n) {
@@ -198,7 +281,9 @@ export function redactStringsAndTemplates(src, blankStrings = false) {
 
   // Scan code. `stopHole`: return at the `}` that closes the enclosing template
   // hole (the caller emits it). `blank`: emit spaces for code (inside a blanked
-  // hole). Literals are always lexed so braces/quotes inside them never count.
+  // hole; mask mode only, never set in placeholder mode so the formulas below
+  // reduce to verbatim). Literals are always lexed so braces/quotes inside them
+  // never count.
   function scanCode(stopHole, blank) {
     let brace = 0;
     while (i < n) {
@@ -228,7 +313,7 @@ export function redactStringsAndTemplates(src, blankStrings = false) {
   }
 
   scanCode(false, false);
-  return out;
+  return { out, literals };
 }
 
 /**
@@ -347,16 +432,194 @@ export function maskComments(src) {
  */
 export function extractWebComponentClassBodies(content) {
   const bodies = [];
-  const re = /class\s+\w+\s+extends\s+WebComponent\s*\{/g;
+  const re = /class\s+\w+\s+extends\s+WebComponent/g;
   let m;
   while ((m = re.exec(content)) !== null) {
-    const bodyStart = m.index + m[0].length;
-    const end = matchClosingBrace(content, bodyStart);
-    if (end !== -1) bodies.push(content.slice(bodyStart, end));
+    let i = m.index + m[0].length;
+    while (i < content.length && /\s/.test(content[i])) i++;
+    if (i >= content.length) continue;
+    
+    let factoryArg = '';
+    const factoryProps = new Set();
+    if (content[i] === '(') {
+      const closeParen = matchClosingParenthesis(content, i + 1);
+      if (closeParen === -1) continue;
+      factoryArg = content.slice(i + 1, closeParen);
+      
+      const objStart = factoryArg.indexOf('{');
+      if (objStart !== -1) {
+        const objEnd = matchClosingBrace(factoryArg, objStart + 1);
+        if (objEnd !== -1) {
+          const objContent = factoryArg.slice(objStart + 1, objEnd);
+          parsePropsFromObjectLiteral(objContent, factoryProps);
+        }
+      }
+      i = closeParen + 1;
+      while (i < content.length && /\s/.test(content[i])) i++;
+    }
+    if (content[i] === '{') {
+      const bodyStart = i + 1;
+      const end = matchClosingBrace(content, bodyStart);
+      if (end !== -1) {
+        bodies.push({
+          body: content.slice(bodyStart, end),
+          factoryProps,
+          factoryArg
+        });
+      }
+    }
   }
   return bodies;
 }
 
+/**
+ * Extract properties from an object literal block.
+ *
+ * @param {string} obj
+ * @param {Set<string>} names
+ */
+export function parsePropsFromObjectLiteral(obj, names) {
+  let i = 0;
+  while (i < obj.length) {
+    while (i < obj.length && /[\s,]/.test(obj[i])) i++;
+    if (i >= obj.length) break;
+    let key = '';
+    if (obj[i] === '"' || obj[i] === "'") {
+      const quote = obj[i++];
+      while (i < obj.length && obj[i] !== quote) { key += obj[i++]; }
+      i++; // closing quote
+    } else {
+      while (i < obj.length && /[A-Za-z0-9_$]/.test(obj[i])) key += obj[i++];
+    }
+    while (i < obj.length && /\s/.test(obj[i])) i++;
+    if (obj[i] !== ':') break;
+    i++;
+    while (i < obj.length && /\s/.test(obj[i])) i++;
+    if (obj[i] === '{') {
+      const valEnd = matchClosingBrace(obj, i + 1);
+      if (valEnd === -1) break;
+      i = valEnd + 1;
+    } else {
+      while (i < obj.length && obj[i] !== ',' && obj[i] !== '}') i++;
+    }
+    if (key) names.add(key);
+  }
+}
+
+/**
+ * Like {@link parsePropsFromObjectLiteral} but captures each entry's raw
+ * VALUE text alongside its key, so a rule can inspect the declaration
+ * (`prop<CommentFormatted[]>(Object)`) rather than just the name.
+ *
+ * The value is read with balanced depth across `()`, `{}`, `[]`, `<>`,
+ * and string/template literals, so an entry is split only on a
+ * TOP-LEVEL comma. That keeps a value's own commas intact, whether they
+ * sit inside an options object (`prop(Object, { default: () => [] })`),
+ * an array literal, or a nested generic (`prop<Map<string, number>>(…)`).
+ * Angle-bracket depth is decremented only when already open, so a stray
+ * `=>` arrow or `>=` does not unbalance a value with no generic.
+ *
+ * @param {string} obj object-literal body (no enclosing braces)
+ * @returns {{ key: string, value: string }[]}
+ */
+export function parsePropEntries(obj) {
+  /** @type {{ key: string, value: string }[]} */
+  const entries = [];
+  const n = obj.length;
+  let i = 0;
+  while (i < n) {
+    while (i < n && /[\s,]/.test(obj[i])) i++;
+    if (i >= n) break;
+    let key = '';
+    if (obj[i] === '"' || obj[i] === "'") {
+      const quote = obj[i++];
+      while (i < n && obj[i] !== quote) { key += obj[i++]; }
+      i++; // closing quote
+    } else {
+      while (i < n && /[A-Za-z0-9_$]/.test(obj[i])) key += obj[i++];
+    }
+    while (i < n && /\s/.test(obj[i])) i++;
+    if (obj[i] !== ':') break;
+    i++;
+    while (i < n && /\s/.test(obj[i])) i++;
+    let round = 0, curly = 0, square = 0, angle = 0;
+    let value = '';
+    while (i < n) {
+      const c = obj[i];
+      if (c === '"' || c === "'" || c === '`') {
+        const quote = c;
+        value += c; i++;
+        while (i < n && obj[i] !== quote) {
+          if (obj[i] === '\\') { value += obj[i] + (obj[i + 1] || ''); i += 2; continue; }
+          value += obj[i++];
+        }
+        if (i < n) value += obj[i++];
+        continue;
+      }
+      if (c === ',' && round === 0 && curly === 0 && square === 0 && angle === 0) break;
+      if (c === '}' && curly === 0) break; // end of the enclosing object literal
+      if (c === '(') round++;
+      else if (c === ')') { if (round > 0) round--; }
+      else if (c === '{') curly++;
+      else if (c === '}') curly--;
+      else if (c === '[') square++;
+      else if (c === ']') { if (square > 0) square--; }
+      else if (c === '<') angle++;
+      else if (c === '>') { if (angle > 0) angle--; }
+      value += obj[i++];
+    }
+    if (key) entries.push({ key, value: value.trim() });
+  }
+  return entries;
+}
+
+
+/**
+ * Walk forward from `start` (just after an opening `(`) and return the
+ * index of the matching `)`. Tracks string/template-literal state so
+ * `)` inside strings or templates does not decrement depth.
+ * Returns -1 if no balanced parenthesis is found.
+ *
+ * @param {string} s
+ * @param {number} start
+ */
+export function matchClosingParenthesis(s, start) {
+  let depth = 1;
+  let i = start;
+  let str = ''; // '', "'", '"', or backtick
+  while (i < s.length) {
+    const c = s[i];
+    if (str) {
+      if (c === '\\') { i += 2; continue; }
+      if (c === str) str = '';
+      else if (str === '`' && c === '$' && s[i + 1] === '{') {
+        const closeBrace = matchClosingBrace(s, i + 2);
+        if (closeBrace === -1) return -1;
+        i = closeBrace + 1;
+        continue;
+      }
+      i++;
+      continue;
+    }
+    if (c === "'" || c === '"' || c === '`') { str = c; i++; continue; }
+    if (c === '/' && s[i + 1] === '/') { // line comment
+      while (i < s.length && s[i] !== '\n') i++;
+      continue;
+    }
+    if (c === '/' && s[i + 1] === '*') { // block comment
+      i += 2;
+      while (i < s.length && !(s[i] === '*' && s[i + 1] === '/')) i++;
+      i += 2;
+      continue;
+    }
+    if (c === '(') depth++;
+    else if (c === ')') { depth--; if (depth === 0) return i; }
+    i++;
+  }
+  return -1;
+}
+
+
 /**
  * Walk forward from `start` (just after an opening `{`) and return the
  * index of the matching `}`. Tracks string/template-literal state so
@@ -401,3 +664,22 @@ export function matchClosingBrace(s, start) {
   }
   return -1;
 }
+
+/**
+ * Return `src` with the BODY of every comment replaced by spaces, and the
+ * body of single-quoted, double-quoted, and template-literal segments
+ * replaced by placeholders like `__STR_index__`. Quote delimiters and template
+ * backticks are preserved so code structure is unchanged. Template holes
+ * `${...}` are left intact (and scanned recursively as code).
+ *
+ * Returns `{ redacted: string, literals: string[] }` where `literals` holds
+ * the original unquoted literal contents.
+ *
+ * @param {string} src
+ * @returns {{ redacted: string, literals: string[] }}
+ */
+export function redactToPlaceholders(src) {
+  const { out, literals } = scanLiterals(src, { placeholder: true });
+  return { redacted: out, literals };
+}
+

package/src/ssr.js

@@ -148,10 +148,31 @@ export async function ssrPage(route, params, url, opts) {
     // zero application JS. The analysis is conservative (anything that
     // touches the client router, a signal, an event, an npm import, or a
     // shipping component keeps shipping).
+    //
+    // Import-only route modules (#605) go one step further: a page / layout
+    // whose only client relevance is importing shipping components is itself
+    // dead weight on the client (it never hydrates), so it is dropped and its
+    // component modules are emitted directly in its place. The component set is
+    // the STATIC closure the analyser computed (what loading the module would
+    // have registered), so a component imported but only conditionally rendered
+    // still registers. Dedup so a component shared across the page and a layout
+    // (or two layouts) is emitted once.
     const inert = opts.inertRouteModules;
-    const moduleUrls = [route.file, ...route.layouts]
-      .filter((f) => !(inert && inert.has(f)))
-      .map((f) => toUrlPath(f, opts.appDir));
+    const importOnly = opts.importOnlyRouteModules;
+    const moduleUrls = [];
+    {
+      const seen = new Set();
+      const push = (abs) => {
+        const u = toUrlPath(abs, opts.appDir);
+        if (!seen.has(u)) { seen.add(u); moduleUrls.push(u); }
+      };
+      for (const f of [route.file, ...route.layouts]) {
+        if (inert && inert.has(f)) continue;
+        const emit = importOnly && importOnly.get(f);
+        if (emit) emit.forEach(push);
+        else push(f);
+      }
+    }
     // Emit <link rel="modulepreload"> for every custom element that
     // actually rendered PLUS their transitive dependencies (from the
     // module graph). URLs are deduplicated so the browser never sees
@@ -847,6 +868,19 @@ export function publicEnvShim(opts) {
     + `</script>`;
 }
 
+// Client-router opt-out (#629). Default ON (the framework's automatic-nav
+// thesis): the router auto-enables in the browser when `@webjsdev/core` loads.
+// `webjs.clientRouter: false` flips this off app-wide; `dev.js` reads the
+// config at boot / each rebuild and calls `setClientRouterEnabled`, and
+// `wrapHead` then emits a `window.__WEBJS_CLIENT_ROUTER__=false` flag BEFORE
+// the deferred boot module so the bundle's module-end auto-enable skips. A
+// module-level switch (mirrors setBasePath / setElisionFingerprint) so no opt
+// has to thread through every render path; default true keeps every existing
+// app and test byte-identical.
+let _clientRouterEnabled = true;
+export function setClientRouterEnabled(enabled) { _clientRouterEnabled = enabled !== false; }
+function clientRouterEnabled() { return _clientRouterEnabled; }
+
 function wrapHead(opts) {
   // CSP nonce: if provided, all inline <script> tags get nonce="…" so they
   // pass strict Content-Security-Policy headers. The nonce is extracted from
@@ -1355,7 +1389,7 @@ function wrapHead(opts) {
 ${opts.nonce ? `<meta name="csp-nonce" content="${escapeAttr(opts.nonce)}">` : ''}
 ${metaTags.join('\n')}
 <title>${escapeHtml(title)}</title>
-${publicEnvShim({ dev: opts.dev, nonce: opts.nonce })}
+${publicEnvShim({ dev: opts.dev, nonce: opts.nonce })}${clientRouterEnabled() ? '' : `\n<script${n}>window.__WEBJS_CLIENT_ROUTER__=false;</script>`}
 ${importMapTag({ nonce: opts.nonce })}
 ${linkTags.join('\n')}
 ${scriptTags.length ? scriptTags.join('\n') + '\n' : ''}${boot}

package/src/vendor.js

@@ -100,12 +100,15 @@ export async function scanBareImports(dir, skipFiles) {
  * `'@tanstack/query'`   → `'@tanstack/query'`
  * `'@tanstack/query/x'` → `'@tanstack/query'`
  * `'./foo'`, `'../bar'`, `'/baz'` → `null` (relative/absolute)
+ * `'#components/x.ts'`, `'#lib/db'` → `null` (`#` path alias, #555: resolves to
+ *   a LOCAL file via `package.json` "imports", never an npm package, so it must
+ *   not be sent to the vendor resolver, #623)
  *
  * @param {string} spec
  * @returns {string | null}
  */
 export function extractPackageName(spec) {
-  if (!spec || spec.startsWith('.') || spec.startsWith('/') || spec.startsWith('__')) return null;
+  if (!spec || spec.startsWith('.') || spec.startsWith('/') || spec.startsWith('__') || spec.startsWith('#')) return null;
   if (/^[a-z]+:/.test(spec)) return null;
   if (spec.startsWith('@')) {
     const parts = spec.split('/');

package/webjs-config.schema.json

@@ -17,6 +17,11 @@
       "type": "boolean",
       "default": true
     },
+    "clientRouter": {
+      "description": "Client-router switch (#629). Default true: the client router auto-enables in the browser whenever @webjsdev/core loads, so any page with a component gets SPA-style navigation with no import. Set to false to opt the whole app out (pure MPA, full-page navigation). Read by readClientRouterEnabled in dev.js.",
+      "type": "boolean",
+      "default": true
+    },
     "headers": {
       "description": "Per-path response-header rules, shaped like Next's. Each rule pairs a URLPattern source against header directives. Read by compileHeaderRules in headers.js.",
       "type": "array",