@webjsdev/server 0.8.54 → 0.8.56

package/package.json

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

package/src/check.js

@@ -119,6 +119,11 @@ export const RULES = [
     description:
       'Flags genuinely browser-only APIs used in a WebComponent constructor, willUpdate, or render() method. The SSR pipeline instantiates the component, runs willUpdate plus controllers\' hostUpdate, reflects properties, and calls render() to produce HTML, on a server element shim that backs the attribute methods but has no real DOM. So a browser global (document, window, localStorage, sessionStorage, navigator, location, matchMedia, screen, history) or an unshimmed HTMLElement member on `this` (attachShadow, shadowRoot, classList, querySelector, querySelectorAll, getBoundingClientRect, focus, blur, scrollIntoView) touched there throws at SSR time (the isomorphic footgun). The attribute methods (getAttribute/setAttribute/hasAttribute/removeAttribute/toggleAttribute), the event methods (addEventListener/removeEventListener/dispatchEvent), and attachInternals are shim-backed and run server-side, so they are NOT flagged. The flagged APIs belong in connectedCallback() or a lifecycle hook (firstUpdated/updated), which SSR never calls; seed first-paint defaults in the constructor (or derive them in willUpdate) only from server-known inputs (attributes, props). Conservative: only the constructor, willUpdate, and render bodies are scanned, and only direct references, so helper indirection is not flagged (the runtime SSR error covers that case).',
   },
+  {
+    name: 'no-shadowed-native-member',
+    description:
+      'Flags a WebComponent class method whose name collides with a native DOM mutation method that WebJs relies on and INSTRUMENTS on every light-DOM host for the slot API (#1021): append, prepend, before, after, replaceWith, replaceChildren, remove, appendChild, insertBefore, removeChild, replaceChild. A method of the same name is SHADOWED at runtime (the instrumented native method wins), so the component method silently never runs, while TypeScript stays green because a zero/one-arg override is assignable to the native signature. Found dogfooding the stream demo (#248): a component named its button handler `append()`, so clicking Append called the slot-append no-op instead of the handler. Rename the handler to a non-native name (appendRow / prependRow / removeItem). The `render` / lifecycle hooks are MEANT to be overridden and are not flagged; only the native DOM mutation members are.',
+  },
   {
     name: 'no-server-import-in-browser-module',
     description:
@@ -659,6 +664,74 @@ export async function checkConventions(appDir) {
     }
   }
 
+  // --- Rule: no-shadowed-native-member ---
+  // A WebComponent method named after a native DOM mutation method WebJs
+  // instruments on every light-DOM host for the slot API (#1021) is SHADOWED at
+  // runtime (the native/instrumented method wins), so the component method never
+  // runs, while TypeScript stays green (a shorter override is assignable). Rename
+  // the handler. The lifecycle hooks are meant to be overridden, so only the DOM
+  // mutation members are reserved.
+  {
+    const NATIVE_MEMBERS = [
+      'append', 'prepend', 'before', 'after', 'replaceWith', 'replaceChildren', 'remove',
+      'appendChild', 'insertBefore', 'removeChild', 'replaceChild',
+    ];
+    for (const { rel, scan } of files) {
+      if (!/class\s+\w+\s+extends\s+WebComponent/.test(scan)) continue;
+      for (const { body } of extractWebComponentClassBodies(scan)) {
+        // The slot interception installs only on LIGHT-DOM hosts (the shadow
+        // branch keeps the true native methods), so a shadow component's method
+        // is never shadowed. Skip the whole class.
+        if (/static\s+shadow\s*=\s*true/.test(body)) continue;
+        // Brace-depth map over the (already string/comment-masked) class body,
+        // so only TOP-LEVEL class members flag: a same-named object-literal
+        // shorthand or function expression nested inside a method body is a
+        // different object's property and shadows nothing.
+        const depth = new Int32Array(body.length);
+        {
+          let d = 0;
+          for (let i = 0; i < body.length; i++) {
+            if (body[i] === '{') { depth[i] = d; d++; }
+            else if (body[i] === '}') { d--; depth[i] = d; }
+            else depth[i] = d;
+          }
+        }
+        for (const name of NATIVE_MEMBERS) {
+          // Two shadowed-definition shapes, both instance-level: the method /
+          // accessor form (`remove() {`, `get remove() {`), and the class-field
+          // FUNCTION form (`remove = () => {}` / `= function () {}`), which the
+          // connect-time interception install overwrites just the same. A
+          // `static` member lives on the constructor and shadows nothing.
+          const methodRe = new RegExp(
+            `(?:^|[\\s;}])((?:static\\s+)?)(?:async\\s+)?(?:get\\s+|set\\s+)?(${name})\\s*\\([^)]*\\)\\s*(?::[^{]*)?\\{`,
+            'g',
+          );
+          const fieldRe = new RegExp(
+            `(?:^|[\\s;}])((?:static\\s+)?)(${name})\\s*=\\s*(?:async\\s*)?(?:function\\b|\\([^)]*\\)\\s*(?::[^=]*)?=>|[\\w$]+\\s*=>)`,
+            'g',
+          );
+          let flagged = false;
+          for (const re of [methodRe, fieldRe]) {
+            let m;
+            while (!flagged && (m = re.exec(body)) !== null) {
+              if (m[1]) continue;                       // static: not shadowed
+              const nameIdx = m.index + m[0].indexOf(m[2]);
+              if (depth[nameIdx] !== 0) continue;       // nested: another object's property
+              flagged = true;
+              violations.push({
+                rule: 'no-shadowed-native-member',
+                file: rel,
+                message: `Component member \`${name}\` shadows the native DOM method WebJs instruments for the slot API, so it silently never runs (the native method wins) and TypeScript does not catch it.`,
+                fix: `Rename the member to a non-native name (e.g. \`${name}Row()\` / \`${name}Item()\`) and update its call sites.`,
+              });
+            }
+            if (flagged) break;
+          }
+        }
+      }
+    }
+  }
+
   // --- Rule: no-redirect-in-api-route ---
   // `redirect()` from `@webjsdev/core` throws a control-flow signal designed
   // for the SSR page renderer. In a `route.ts` API handler it goes uncaught

package/src/component-elision.js

@@ -118,16 +118,14 @@ export const CLIENT_LIFECYCLE_HOOKS = [
 ];
 
 /**
- * Method calls that only make sense on the client. `addController`
- * registers a ReactiveController (client lifecycle). `requestUpdate`
- * schedules a re-render. `setSlotContent` pushes dynamic slot values
- * (#1015) and `hasSlot` conditions a render on the slot record, both of
- * which need the client slot runtime to apply. Any of these implies the
- * component is not inert.
+ * Method calls that only make sense on the client. `addController` registers a
+ * ReactiveController (client lifecycle); `requestUpdate` schedules a re-render.
+ * Any of these implies the component is not inert. (The dynamic slot read
+ * surface lives in `SLOT_DYNAMIC_RE`, not here.)
  *
  * @type {readonly string[]}
  */
-export const CLIENT_METHOD_CALLS = ['addController', 'removeController', 'requestUpdate', 'setSlotContent', 'hasSlot'];
+export const CLIENT_METHOD_CALLS = ['addController', 'removeController', 'requestUpdate'];
 
 /**
  * Static class fields whose declaration (to a non-`false` value) marks a
@@ -215,17 +213,21 @@ const EVENT_BINDING_RE = new RegExp(
 const EVENT_PROP_RE = /\.on[a-z]+\s*=\s*\$\{/;
 
 /**
- * Narrow dynamic-slot signals (#1015). The old blanket rule shipped ANY
- * component that merely RENDERS a `<slot>`, but under children-as-values the
- * SSR output already carries the placed children, so a display-only slotted
- * wrapper is byte-identical with or without its JS and is elidable. What
- * genuinely needs the client slot runtime is the DYNAMIC surface: a
- * `slotchange` listener, the assignedNodes/assignedElements/assignedSlot
- * reads, a `this.slots` record read, or the setSlotContent/hasSlot calls
- * (those two are also covered as CLIENT_METHOD_CALLS inside class bodies;
- * this regex catches external callers too).
+ * Narrow dynamic-slot signals (#1015, retained under #1021's native-parity
+ * record model). The old blanket rule shipped ANY component that merely
+ * RENDERS a `<slot>`, but the SSR output already carries the placed children,
+ * so a display-only slotted wrapper is byte-identical with or without its JS
+ * and is elidable. What genuinely needs the client slot runtime is the
+ * DYNAMIC READ surface: a `slotchange` listener or an `assignedNodes` /
+ * `assignedElements` / `assignedSlot` read. Native WRITE liveness
+ * (appendChild, slot= flips) is consumer-driven and usually forces the ship
+ * through the consumer's own signals (a shipping component that renders the
+ * tag, or an observation form); the remaining carve-out, a shipped script
+ * reaching an elided host only via document.querySelector, is inert by
+ * design with the `static interactive = true` escape hatch (see the
+ * slot.js banner).
  */
-const SLOT_DYNAMIC_RE = /\bslotchange\b|\bassignedNodes\s*\(|\bassignedElements\s*\(|\bassignedSlot\b|\.slots\b|\bsetSlotContent\s*\(|\bhasSlot\s*\(/;
+const SLOT_DYNAMIC_RE = /\bslotchange\b|\bassignedNodes\s*\(|\bassignedElements\s*\(|\bassignedSlot\b/;
 
 /** A `.server.{js,ts,mjs,mts}` file: a stub on the client, inert there. */
 const SERVER_FILE_RE = /\.server\.m?[jt]s$/;
@@ -544,10 +546,9 @@ export function analyzeComponentSource(src) {
   // ships: the SSR output carries the placed children, and with no
   // observers in the runtime a display-only slotted wrapper is
   // byte-identical with or without its JS. Only the dynamic slot surface
-  // (slotchange, the assigned* reads, the slots record, setSlotContent /
-  // hasSlot) needs the client runtime.
+  // (slotchange, the assigned* reads) needs the client runtime.
   if (SLOT_DYNAMIC_RE.test(src)) {
-    return { interactive: true, reason: 'uses the dynamic slot API (slotchange / assignedNodes / slots record)' };
+    return { interactive: true, reason: 'reads the dynamic slot surface (slotchange / assignedNodes / assignedElements / assignedSlot)' };
   }
 
   // Top-level client work the render/lifecycle checks would miss: a

package/src/ssr.js

@@ -1124,18 +1124,27 @@ function wrapInDocument(body, opts) {
  */
 function collectHoistedHeadTags(bodyHtml) {
   const tags = [];
-  // <script>…</script> and <style>…</style> are paired; <link …> is void.
-  // A plain HTML comment (<!-- … -->) is consumed but NOT hoisted, so a
-  // comment interleaved with head-bound tags (e.g. "<!-- Self-hosted fonts -->"
+  // <script>…</script> and <style>…</style> are paired; <link …> and <meta …>
+  // are void. A plain HTML comment (<!-- … -->) is consumed but NOT hoisted, so
+  // a comment interleaved with head-bound tags (e.g. "<!-- Self-hosted fonts -->"
   // between a favicon <link> and the stylesheet <link>) does not terminate
   // the leading run and strand the stylesheet in <body>, which caused FOUC
   // because a <link rel="stylesheet"> in <body> is not reliably
-  // render-blocking (#406). The `(?!/?wj:)` guard exempts client-router
-  // markers (<!--wj:children:…-->, <!--/wj:children-->) so a layout that
-  // renders children directly after its head tags still terminates the run
-  // there rather than swallowing the nesting marker.
+  // render-blocking (#406). A <meta …> is treated the same way for the same
+  // reason: a <meta name="color-scheme"> between the theme <script> and the
+  // stylesheet <link> would otherwise terminate the run and strand the
+  // stylesheet AND a <link rel="icon"> in <body> (a favicon in <body> is
+  // ignored by browsers, so the icon silently never renders). The `(?!/?wj:)`
+  // guard exempts client-router markers (<!--wj:children:…-->,
+  // <!--/wj:children-->) so a layout that renders children directly after its
+  // head tags still terminates the run there rather than swallowing the marker.
+  // The void-tag matchers are QUOTE-AWARE ((?:[^>"']|"[^"]*"|'[^']*')*): a `>`
+  // inside a quoted attribute value (a description meta like
+  // content="Guides > API") must not terminate the tag early, which would hoist
+  // a truncated tag, leak the remainder as visible body text, and strand the
+  // stylesheet (the #406 FOUC this hoist exists to prevent).
   const re =
-    /^\s*(<!--(?!\/?wj:)[\s\S]*?-->|<script[\s>][\s\S]*?<\/script>|<style[\s>][\s\S]*?<\/style>|<link\b[^>]*>)/i;
+    /^\s*(<!--(?!\/?wj:)[\s\S]*?-->|<script[\s>][\s\S]*?<\/script>|<style[\s>][\s\S]*?<\/style>|<link\b(?:[^>"']|"[^"]*"|'[^']*')*>|<meta\b(?:[^>"']|"[^"]*"|'[^']*')*>)/i;
   let remaining = bodyHtml;
   // `body` only advances to just-past the LAST hoisted head tag. Comments
   // are scanned through (so they don't terminate the run) but a comment that