@webjsdev/server 0.8.21 → 0.8.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.21",
+  "version": "0.8.23",
   "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

@@ -82,7 +82,7 @@ export async function ssrPage(route, params, url, opts) {
   const metadata = await collectMetadata(route, ctx, opts.dev);
 
   try {
-    const suspenseCtx = { pending: [], nextId: 1, usedComponents: new Set() };
+    const suspenseCtx = { pending: [], nextId: 1, usedComponents: new Set(), dev: opts.dev };
     // Parse the partial-nav "have" header from the client. The header
     // lists comma-separated marker paths the client already has rendered
     // in its DOM. The server walks the target route's layout chain
@@ -183,6 +183,7 @@ export async function ssrPage(route, params, url, opts) {
       url,
       metadata,
       nonce,
+      opts.dev,
     );
     // Server HTML cache write (#241). The page opted in via `revalidate`, so
     // FLAG this candidate for the response funnel rather than writing here: the
@@ -233,7 +234,7 @@ export async function ssrPage(route, params, url, opts) {
         const mod = await loadModule(route.errors[i], opts.dev);
         if (!mod.default) continue;
         const tree = await mod.default({ ...ctx, error: err });
-        const body = await renderToString(tree);
+        const body = await renderToString(tree, { ssr: true, dev: opts.dev });
         const moduleUrls = [route.file, ...route.layouts].map((f) => toUrlPath(f, opts.appDir));
         const html = wrapInDocument(body, { metadata, moduleUrls, dev: opts.dev, nonce: errNonce });
         return htmlResponse(html, 500, opts.req, url);
@@ -333,7 +334,7 @@ async function ssrNotFoundHtml(notFoundFile, opts) {
   if (notFoundFile) {
     try {
       const mod = await loadModule(notFoundFile, opts.dev);
-      if (mod.default) body = await renderToString(await mod.default({}));
+      if (mod.default) body = await renderToString(await mod.default({}), { ssr: true, dev: opts.dev });
     } catch (e) {
       body = `<h1>404: Not found</h1><pre>${escapeHtml(String(e))}</pre>`;
     }
@@ -430,7 +431,7 @@ async function loadingTemplates(route, ctx, dev) {
       const mod = await loadModule(file, dev);
       if (!mod.default) continue;
       const tree = await mod.default(ctx);
-      const html = await renderToString(tree, { ssr: true });
+      const html = await renderToString(tree, { ssr: true, dev });
       const segmentPath = loadingSegmentPath(file);
       parts.push(`<template id="wj-loading:${segmentPath}">${html}</template>`);
     } catch { /* skip broken loading file */ }
@@ -1444,15 +1445,18 @@ function deduplicatedPreloads(componentUrls, moduleUrls, graph, entryFiles, appD
  * Build a streaming Response. Degrades to a single-flush response when
  * there are no pending Suspense boundaries.
  *
- * @param {string} headHtml
+ * @param {string} prefix
  * @param {string} bodyHtml
+ * @param {string} closer
  * @param {{ pending: {id: string, promise: Promise<unknown>}[], nextId: number }} ctx
  * @param {number} status
  * @param {Request | undefined} req
  * @param {URL | undefined} url
  * @param {Record<string, any>} [metadata]
+ * @param {string} [nonce]
+ * @param {boolean} [dev]  dev surfaces a streamed-boundary error message; prod stays silent
  */
-function streamingHtmlResponse(prefix, bodyHtml, closer, ctx, status, req, url, metadata, nonce) {
+function streamingHtmlResponse(prefix, bodyHtml, closer, ctx, status, req, url, metadata, nonce, dev) {
   const encoder = new TextEncoder();
   const headers = new Headers({ 'content-type': 'text/html; charset=utf-8' });
   // Default: no caching. Pages are dynamic by default: the developer
@@ -1481,7 +1485,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.
@@ -1492,14 +1503,19 @@ function streamingHtmlResponse(prefix, bodyHtml, closer, ctx, status, req, url,
             batch.map(async (p) => {
               try {
                 const resolved = await p.promise;
-                const sub = { pending: [], nextId: ctx.nextId };
+                const sub = { pending: [], nextId: ctx.nextId, dev: ctx.dev };
                 const html = await renderToString(resolved, { ssr: true, suspenseCtx: sub });
                 ctx.nextId = sub.nextId;
                 for (const n of sub.pending) ctx.pending.push(n);
                 return { id: p.id, html };
               } catch (e) {
+                // Match the SSR error-isolation policy (render-server.js's
+                // defaultSSRErrorTemplate): dev surfaces the message so the
+                // failure is obvious, prod stays SILENT so no internal detail
+                // (a DB error, a stack-derived path) leaks to the client (#478).
                 const msg = e instanceof Error ? e.message : String(e);
-                return { id: p.id, html: `<p>error: ${escapeHtml(msg)}</p>` };
+                const html = dev ? `<p>error: ${escapeHtml(msg)}</p>` : '';
+                return { id: p.id, html };
               }
             })
           );