@webjsdev/server 0.8.21 → 0.8.22

package/package.json

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

package/src/component-elision.js

@@ -111,6 +111,9 @@ export const CLIENT_LIFECYCLE_HOOKS = [
   'firstUpdated',
   'getUpdateComplete',
   'renderError',
+  // The async-render re-fetch loading UI (#469): defining it means the
+  // component suspends and re-renders on the client, so it must ship.
+  'renderFallback',
 ];
 
 /**
@@ -122,6 +125,24 @@ export const CLIENT_LIFECYCLE_HOOKS = [
  */
 export const CLIENT_METHOD_CALLS = ['addController', 'removeController', 'requestUpdate'];
 
+/**
+ * A bare `async render()` is NOT a standalone ship signal (#474). Its SSR
+ * pass bakes the resolved data into the first paint, so a light-DOM async
+ * component with no OTHER client signal renders identical HTML with or
+ * without its JS and is elidable like any display-only component, saving a
+ * module download plus a redundant on-hydration re-fetch. It ships only when
+ * it ALSO carries an independent signal: an `@event`, a non-`state` reactive
+ * prop, a reactive import, a lifecycle hook (`renderFallback()` included, via
+ * CLIENT_LIFECYCLE_HOOKS), a `<slot>`, `static shadow = true`, `static refresh
+ * = true`, cross-module observation, or a transitively-reachable interactive
+ * dep / child (the fixpoint's import + render rules). The two genuinely new
+ * carve-outs, both handled per-class below, are `static shadow` (Declarative
+ * Shadow DOM only attaches during HTML parsing, so a streamed / soft-navigated
+ * shadow component needs its module to re-run `attachShadow`) and the explicit
+ * `static refresh = true` opt-in (keeps the stale-while-revalidate on-load
+ * re-fetch that eliding would drop).
+ */
+
 /** Match a `@event=${...}` binding inside a template (unquoted per invariant 4). */
 const EVENT_BINDING_RE = /@[A-Za-z][\w-]*\s*=\s*\$\{/;
 
@@ -396,6 +417,23 @@ export function analyzeComponentSource(src) {
   }
 
   for (const body of bodies) {
+    // Shadow DOM always ships (#474). Declarative Shadow DOM attaches ONLY
+    // during HTML parsing; an elided component that arrives via a client DOM
+    // insertion (a soft-nav swap, a streamed <webjs-suspense> boundary's
+    // replaceWith) would never re-attach its shadow root, because eliding
+    // drops the module that runs `attachShadow`. The analyser is context-free
+    // (it cannot tell whether a given component will be streamed or
+    // navigated to), so any shadow component is shipped.
+    if (declaresStaticTrue(body, 'shadow')) {
+      return { interactive: true, reason: 'declares static shadow (DSD must re-attach on a client swap)' };
+    }
+    // `static refresh = true` is the explicit opt-in to ship a bare async
+    // component so its stale-while-revalidate refresh runs ~after SSR; eliding
+    // a bare async component drops that on-load re-fetch (moot for request-
+    // stable data, the default), so an author who wants fresh-on-load opts in.
+    if (declaresStaticTrue(body, 'refresh')) {
+      return { interactive: true, reason: 'declares static refresh = true (keeps the on-load re-fetch)' };
+    }
     for (const hook of CLIENT_LIFECYCLE_HOOKS) {
       // A client lifecycle hook as a method (`hook(`) OR as an arrow class
       // field (`hook = () =>`), which shadows the prototype method and still
@@ -420,6 +458,29 @@ export function analyzeComponentSource(src) {
   return { interactive: false, reason: null };
 }
 
+/**
+ * True if a class body declares a `static <name>` whose value is not the
+ * literal `false`. Backs the `static shadow` (DSD-on-client-swap) and
+ * `static refresh = true` (ship-the-async-refetch opt-in) ship signals (#474).
+ *
+ * Conservative on anything it cannot evaluate: a getter form
+ * (`static get <name>()`) ships, and a non-`false` value of any shape
+ * (`true`, a variable, an expression) ships. Only an absent declaration or a
+ * literal `= false` is cleared as inert, matching the light-DOM /
+ * no-refresh defaults.
+ *
+ * @param {string} classBody  redacted class body
+ * @param {string} name       the static field name (`shadow` / `refresh`)
+ * @returns {boolean}
+ */
+function declaresStaticTrue(classBody, name) {
+  // A getter cannot be evaluated statically; ship.
+  if (new RegExp(`\\bstatic\\s+get\\s+${name}\\b`).test(classBody)) return true;
+  const m = new RegExp(`\\bstatic\\s+${name}\\b\\s*=\\s*([^;\\n]*)`).exec(classBody);
+  if (!m) return false; // not declared: the default (light DOM / no refresh)
+  return !/^false\b/.test(m[1].trim()); // `= false` is inert; anything else ships
+}
+
 /**
  * @param {string} src
  * @returns {string | null} the offending imported name, or null

package/src/ssr.js

@@ -1481,7 +1481,14 @@ function streamingHtmlResponse(prefix, bodyHtml, closer, ctx, status, req, url,
 
   const stream = new ReadableStream({
     async start(controller) {
-      controller.enqueue(encoder.encode(prefix + bodyHtml));
+      // Flush the shell (prefix + body with fallbacks) immediately, followed by
+      // a shell-ready sentinel comment IN THE SAME chunk. The resolved boundary
+      // templates and the `</body></html>` closer are emitted LATER (after the
+      // slow data settles), so without this sentinel a streaming soft-nav client
+      // could not tell "shell complete, awaiting the slow boundary" from "shell
+      // still arriving" and would block its progressive swap until the slow
+      // boundary (#473). The comment is inert for the native initial-load parse.
+      controller.enqueue(encoder.encode(prefix + bodyHtml + '<!--wj-stream-shell-->'));
       try {
         // Loop: resolve all currently-pending promises in parallel; nested
         // Suspense inside resolved content adds more pending entries.