@webjsdev/server 0.8.20 → 0.8.22

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/module-graph.js

@@ -262,13 +262,22 @@ async function parseFile(file, appDir, graph, seen) {
   // Mask of `src` with all string / template-literal / comment / regex
   // CONTENT blanked to spaces (positions preserved). Used to reject an
   // `import '…'` / `export … from '…'` that appears as TEXT inside a
-  // template literal (e.g. example code shown in a `<pre>` inside an
-  // `html\`\`` template, as the docs site does) rather than as a real
-  // statement. We still read the specifier from the RAW `src` (the
-  // specifier is itself a string, blanked in the mask), and only consult
-  // the mask to confirm the `import` / `export` KEYWORD survived
-  // redaction, i.e. sits in code position and not inside a literal.
-  const masked = redactStringsAndTemplates(src);
+  // literal (e.g. example code shown in a `<pre>` inside an `html\`\``
+  // template, as the docs site does, OR a code-example written as a plain
+  // quoted string) rather than as a real statement. We still read the
+  // specifier from the RAW `src` (the specifier is itself a string,
+  // blanked in the mask), and only consult the mask to confirm the
+  // `import` / `export` KEYWORD survived redaction, i.e. sits in code
+  // position and not inside a literal.
+  //
+  // `blankStrings: true` is load-bearing: the default mask keeps PLAIN
+  // string + verbatim-template bodies verbatim (so `register('tag')` stays
+  // readable for other scanners), which would leave an `import` written
+  // inside a plain string looking like a real keyword and create a phantom
+  // graph edge to whatever path that string names. Since this caller only
+  // checks keyword-in-code-position, blank every literal body so a
+  // code-example `import` string never becomes an edge.
+  const masked = redactStringsAndTemplates(src, true);
   const deps = new Set();
   for (const re of [IMPORT_RE, EXPORT_FROM_RE]) {
     for (const m of src.matchAll(re)) {

package/src/page-action.js

@@ -196,9 +196,11 @@ export async function runPageAction(route, params, url, loaded, req, ssrOpts) {
   } catch (err) {
     if (isRedirect(err)) {
       const e = /** @type any */ (err);
-      // A thrown redirect from an action is honored as the page render does.
-      // Use the action's chosen status (307/308) so an explicit redirect()
-      // keeps its semantics; PRG (303) is the SUCCESS-result path below.
+      // A thrown redirect from an action (a POST) defaults to 307 Temporary
+      // Redirect, which is method-preserving so the action's intent survives
+      // the bounce; an explicit `redirect(url, status)` overrides it. This is
+      // deliberately NOT the GET gate's 302 default (see ssr.js). PRG (303) is
+      // the SUCCESS-result path below.
       return new Response(null, { status: e.status || 307, headers: { location: e.url } });
     }
     if (isNotFound(err)) {

package/src/ssr.js

@@ -198,7 +198,12 @@ export async function ssrPage(route, params, url, opts) {
   } catch (err) {
     if (isRedirect(err)) {
       const e = /** @type any */ (err);
-      return new Response(null, { status: e.status || 307, headers: { location: e.url } });
+      // A redirect thrown during a GET page/layout render is a GET-to-GET
+      // navigation (an auth bounce, a gate). 302 Found is the conventional
+      // code there, so it is the default when the caller did not pick one. An
+      // explicit `redirect(url, status)` overrides it. (Action redirects, a
+      // POST, default to 307 in page-action.js so the method is preserved.)
+      return new Response(null, { status: e.status || 302, headers: { location: e.url } });
     }
     if (isNotFound(err)) {
       const html = await ssrNotFoundHtml(null, opts);
@@ -1476,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.