@webjsdev/core 0.7.15 → 0.7.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/core",
-  "version": "0.7.15",
+  "version": "0.7.16",
   "type": "module",
   "description": "webjs core runtime - html/css tags, WebComponent base, isomorphic renderers",
   "types": "./index.d.ts",

package/src/component.d.ts

@@ -113,6 +113,13 @@ export abstract class WebComponent extends HTMLElement {
   firstUpdated?(changedProperties: Map<string, unknown>): void;
   /** Optional render-error boundary inside the component. */
   renderError?(error: Error): TemplateResult | void;
+  /**
+   * Optional loading UI for an async `render()` (#469), shown ONLY during a
+   * client re-fetch (a prop / dependency change re-runs `async render()`),
+   * NEVER on the first paint. The default re-fetch behaviour is
+   * stale-while-revalidate; define this to override it with a loading state.
+   */
+  renderFallback?(): TemplateResult | void;
 
   // Concrete on the base (component.js implements all three), so a subclass
   // override can call `super.connectedCallback()` etc. without a

package/src/component.js

@@ -990,6 +990,9 @@ export class WebComponent extends Base {
     // --- 1. Mark we're inside an update cycle ---
     this._isUpdating = true;
     let didCommit = false;
+    // Set when render() was async: the DOM commit lands when this settles,
+    // so the post-commit half of the cycle defers until then (#469).
+    let pendingCommit = null;
 
     // --- 2-6. Update phase. Lifecycle-hook throws are logged and
     // swallowed so the component is not left in a deadlocked state
@@ -1005,24 +1008,27 @@ export class WebComponent extends Base {
         }
 
         // --- 5. update + DOM commit (with render-error boundary) ---
+        // Stamp a fresh render token for THIS commit, sync or async. A later
+        // cycle that reaches here bumps it, so an in-flight async render whose
+        // token no longer matches drops its now-stale resolution. Stamping
+        // here (not inside _commitAsync) is what guards the async-superseded-
+        // by-sync case (#469); a shouldUpdate=false cycle never reaches here,
+        // so it does not invalidate an in-flight async render.
+        this.__renderToken = (this.__renderToken || 0) + 1;
         try {
-          this.update(changedProperties);
+          const r = this.update(changedProperties);
+          if (r && typeof r.then === 'function') pendingCommit = r;
         } catch (error) {
-          console.error(`[webjs] render error in <${tagOf(/** @type any */ (this.constructor)) || this.tagName?.toLowerCase()}>:`, error);
-          try {
-            const fallback = this.renderError(/** @type {Error} */ (error));
-            if (fallback !== undefined) clientRender(fallback, this._renderRoot);
-          } catch (fallbackError) {
-            console.error(`[webjs] renderError() also threw:`, fallbackError);
-          }
+          this._handleRenderError(/** @type {Error} */ (error));
         }
 
-        // --- 6. controllers' hostUpdated ---
-        for (const c of this.__controllers) {
-          if (c.hostUpdated) c.hostUpdated();
+        if (!pendingCommit) {
+          // --- 6. controllers' hostUpdated (sync commit) ---
+          for (const c of this.__controllers) {
+            if (c.hostUpdated) c.hostUpdated();
+          }
+          didCommit = true;
         }
-
-        didCommit = true;
       }
       // shouldUpdate=false: preserve _changedProperties so the next
       // requestUpdate keeps accumulating on top of the entries that
@@ -1031,28 +1037,46 @@ export class WebComponent extends Base {
       console.error(`[webjs] lifecycle hook threw during update phase:`, preCommitError);
     } finally {
       this._isUpdating = false;
-      if (didCommit) {
+      // The snapshot is consumed once the commit is DISPATCHED. For an async
+      // render it resets here too, so a property change during the in-flight
+      // fetch starts a fresh cycle (whose render token supersedes this one).
+      if (didCommit || pendingCommit) {
         this._changedProperties = new Map();
       }
     }
 
-    // --- 7-8. Post-commit hooks. Errors here are also caught so the
+    // --- Async render: finish the cycle when the pending commit settles. ---
+    if (pendingCommit) {
+      const token = this.__renderToken;
+      // Count this in-flight async commit so a non-committing cycle
+      // (shouldUpdate=false) running during the fetch does NOT resolve
+      // updateComplete early: the pending commit owns the resolution.
+      this.__pendingAsyncCommits = (this.__pendingAsyncCommits || 0) + 1;
+      pendingCommit.then(() => {
+        // Always decrement first, even when superseded, so the in-flight
+        // count never leaks (a superseded cycle returns below without
+        // committing, but it is no longer pending).
+        this.__pendingAsyncCommits--;
+        // A newer render superseded this one; let the newer cycle finish.
+        if (token !== this.__renderToken) return;
+        // --- 6. controllers' hostUpdated (after the async commit) ---
+        for (const c of this.__controllers) {
+          if (c.hostUpdated) c.hostUpdated();
+        }
+        // --- 7-8 + updateComplete ---
+        this._postCommit(changedProperties);
+      });
+      return;
+    }
+
+    // --- 7-8. Post-commit hooks (sync path). Errors are caught so the
     // updateComplete promise always resolves.
     if (didCommit) {
-      try {
-        // --- 7. firstUpdated (once) ---
-        if (!this.__firstRendered) {
-          this.__firstRendered = true;
-          this.firstUpdated(changedProperties);
-        }
-        // --- 8. updated (every render) ---
-        this.updated(changedProperties);
-      } catch (postCommitError) {
-        console.error(`[webjs] lifecycle hook threw during post-commit phase:`, postCommitError);
-      } finally {
-        this._resolveUpdate();
-      }
-    } else {
+      this._postCommit(changedProperties);
+    } else if (!this.__pendingAsyncCommits) {
+      // A non-committing cycle resolves updateComplete only when no async
+      // commit is in flight; otherwise the pending commit resolves it once it
+      // lands, so `await el.updateComplete` never returns before that DOM.
       this._resolveUpdate();
     }
   }
@@ -1203,7 +1227,110 @@ export class WebComponent extends Base {
     }
     let tpl;
     this.__signalWatcher.observe(() => { tpl = this.render(); });
+    // Bare-await async render (#469): render() returned a promise. Use
+    // stale-while-revalidate: keep the current DOM (the SSR first paint on
+    // hydration, or the prior content on a re-fetch) visible until the new
+    // template resolves, then commit it. Returns the pending promise so
+    // _performRender defers the post-commit half of the cycle (hostUpdated,
+    // firstUpdated/updated, updateComplete) until the real commit lands.
+    // (Note: only signal reads BEFORE the first `await` are tracked; reads
+    // after a suspension point do not establish reactive dependencies.)
+    if (tpl && typeof (/** @type any */ (tpl).then) === 'function') {
+      return this._commitAsync(/** @type {Promise<unknown>} */ (tpl));
+    }
     clientRender(tpl, this._renderRoot);
+    return undefined;
+  }
+
+  /**
+   * Commit a promise-returning render() with stale-while-revalidate
+   * semantics (#469). The current DOM stays untouched until the template
+   * resolves; on a client RE-FETCH an author-defined renderFallback()
+   * optionally swaps in a loading state first. The cycle's render token
+   * (stamped by _performRender before update() ran) drops a superseded
+   * resolution so an out-of-order fetch never commits stale DOM, INCLUDING
+   * when the superseding render is synchronous (a later cycle re-stamps the
+   * token whether or not it is async). A rejection routes to the
+   * renderError() boundary, isolated to this component. Returns a promise
+   * that settles once the commit (or its error / fallback) has been applied.
+   *
+   * @param {Promise<unknown>} pending
+   * @returns {Promise<void>}
+   * @private
+   */
+  _commitAsync(pending) {
+    const token = this.__renderToken;
+    // First paint (hydration): keep the SSR DOM, never a fallback, so
+    // first-paint data stays visible with no skeleton flash. Re-fetch: an
+    // author-defined renderFallback() overrides the stale-while-revalidate
+    // default with an explicit loading state.
+    if (this.__firstRendered && this._overridesRenderFallback()) {
+      try {
+        const fb = this.renderFallback();
+        if (fb !== undefined) clientRender(fb, this._renderRoot);
+      } catch (e) {
+        console.error(`[webjs] renderFallback() threw:`, e);
+      }
+    }
+    return Promise.resolve(pending).then(
+      (tpl) => {
+        if (token !== this.__renderToken) return; // superseded by a newer render
+        clientRender(tpl, this._renderRoot);
+      },
+      (error) => {
+        if (token !== this.__renderToken) return;
+        this._handleRenderError(error instanceof Error ? error : new Error(String(error)));
+      },
+    );
+  }
+
+  /**
+   * Whether the subclass overrides renderFallback() (vs the inert default).
+   * @returns {boolean}
+   * @private
+   */
+  _overridesRenderFallback() {
+    return this.renderFallback !== WebComponent.prototype.renderFallback;
+  }
+
+  /**
+   * Client-side render-error boundary, shared by the sync and async commit
+   * paths. Logs, then commits renderError()'s output (if any) so one broken
+   * component does not crash the page.
+   * @param {Error} error
+   * @private
+   */
+  _handleRenderError(error) {
+    console.error(
+      `[webjs] render error in <${tagOf(/** @type any */ (this.constructor)) || this.tagName?.toLowerCase()}>:`,
+      error,
+    );
+    try {
+      const fallback = this.renderError(error);
+      if (fallback !== undefined) clientRender(fallback, this._renderRoot);
+    } catch (fallbackError) {
+      console.error(`[webjs] renderError() also threw:`, fallbackError);
+    }
+  }
+
+  /**
+   * Post-commit half of the update cycle (steps 7-8 + updateComplete),
+   * shared by the sync path and the async (post-resolution) path.
+   * @param {Map<string, unknown>} changedProperties
+   * @private
+   */
+  _postCommit(changedProperties) {
+    try {
+      if (!this.__firstRendered) {
+        this.__firstRendered = true;
+        this.firstUpdated(changedProperties);
+      }
+      this.updated(changedProperties);
+    } catch (postCommitError) {
+      console.error(`[webjs] lifecycle hook threw during post-commit phase:`, postCommitError);
+    } finally {
+      this._resolveUpdate();
+    }
   }
 
   /**
@@ -1374,6 +1501,35 @@ export class WebComponent extends Base {
   renderError(error) {
     return undefined;
   }
+
+  /**
+   * Optional loading UI for an async render() (#469), shown ONLY during a
+   * client RE-FETCH (a prop / dependency change re-runs `async render()`),
+   * NEVER on the first paint.
+   *
+   * **When to override (AI hint):** the client re-fetch default is
+   * stale-while-revalidate (the component keeps showing its current content
+   * until the new render resolves). Override `renderFallback()` only when you
+   * want a loading state (skeleton / spinner) shown during the re-fetch
+   * instead of the stale content, e.g. when stale data would mislead.
+   *
+   * **What it does NOT do:** it does not affect the first paint (SSR always
+   * blocks and bakes real data in), and it does NOT create a server-streaming
+   * boundary. To show a first-paint fallback for slow data, wrap the component
+   * in `<webjs-suspense .fallback=${...}>` instead. It is a prop-aware method,
+   * not a static field, so it can branch on the component's current state.
+   *
+   * ```js
+   * renderFallback() { return html`<div class="skeleton h-24"></div>`; }
+   * async render() { const u = await getUser(this.id); return html`<h3>${u.name}</h3>`; }
+   * ```
+   *
+   * @returns {unknown} A TemplateResult loading state, or undefined to keep
+   *   the stale-while-revalidate default.
+   */
+  renderFallback() {
+    return undefined;
+  }
 }
 
 /** @param {string} s */

package/src/render-server.js

@@ -1,10 +1,10 @@
-import { isTemplate } from './html.js';
+import { html, isTemplate } from './html.js';
 import { escapeText, escapeAttr } from './escape.js';
 import { lookup, lookupModuleUrl, allTags } from './registry.js';
 import { stylesToString, isCSS } from './css.js';
 import { isRepeat } from './repeat.js';
 import { isSuspense } from './suspense.js';
-import { isUnsafeHTML, isLive, isKeyed, isGuard, isTemplateContent, isRef, isCache, isUntil, isAsyncAppend, isAsyncReplace, isWatch } from './directives.js';
+import { unsafeHTML, isUnsafeHTML, isLive, isKeyed, isGuard, isTemplateContent, isRef, isCache, isUntil, isAsyncAppend, isAsyncReplace, isWatch } from './directives.js';
 import { stringify, parse } from './serialize.js';
 import { cspNonce } from './csp-nonce.js';
 
@@ -267,6 +267,19 @@ async function renderTemplate(tr, ctx) {
           // page-level `.prop` on a native element could have set the
           // property to begin with.
           out = out.slice(0, attrStart);
+          // `<webjs-suspense .fallback=${html`...`}>` (#471). A TemplateResult
+          // is not serializer-safe (the normal data-webjs-prop-* path would
+          // drop it) and a normal custom-element prop applies only at
+          // hydration, too late for the streaming placeholder. So render the
+          // fallback to HTML now and carry it as data-webjs-fallback, which the
+          // injectDSD streaming pre-pass reads as the boundary placeholder.
+          if (currentTag === 'webjs-suspense' && name === 'fallback') {
+            const fbHtml = await render(val, ctx);
+            out += `data-webjs-fallback="${escapeAttr(fbHtml)}"`;
+            state = 'in-tag';
+            attrName = '';
+            continue;
+          }
           if (!currentTag.includes('-')) {
             state = 'in-tag';
             attrName = '';
@@ -353,6 +366,30 @@ function browserMemberHint(e) {
   return null;
 }
 
+/** True in a production build (no dev error surfacing). */
+function isProd() {
+  return typeof process !== 'undefined' && process.env && process.env.NODE_ENV === 'production';
+}
+
+/**
+ * Default component-scoped error state for an async/sync render that threw
+ * during SSR, used when the component does not define renderError() (#469).
+ * Dev surfaces the tag + message loudly so the failure is obvious; prod
+ * renders an empty (silent, isolated) element so no internal detail leaks.
+ *
+ * @param {string} tag
+ * @param {Error} err
+ * @returns {unknown} a TemplateResult (dev) or '' (prod)
+ */
+function defaultSSRErrorTemplate(tag, err) {
+  if (isProd()) return '';
+  const msg = err && err.message ? err.message : String(err);
+  return html`<div data-webjs-error="${tag}" style="border:1px solid #f5c2c7;background:#f8d7da;color:#842029;padding:8px 12px;border-radius:6px;font:13px/1.4 system-ui,sans-serif">
+    <strong>&lt;${tag}&gt; failed to render</strong>
+    <div style="margin-top:4px;white-space:pre-wrap">${msg}</div>
+  </div>`;
+}
+
 /**
  * Scan an HTML string for registered custom elements and inject
  * Declarative Shadow DOM (`<template shadowrootmode="open">`).
@@ -363,6 +400,12 @@ function browserMemberHint(e) {
  * @returns {Promise<string>}
  */
 async function injectDSD(html, ctx, ancestors = []) {
+  // Resolve <webjs-suspense> boundaries first (#471): in a streaming context
+  // each becomes a fallback placeholder now, with its children pushed for
+  // out-of-order streaming; without a streaming context the children render
+  // inline (blocking). Run before the custom-element walk so a streamed
+  // boundary's children leave the main flow and are not double-processed.
+  html = await processSuspenseElements(html, ctx, ancestors);
   const tags = allTags();
   if (!tags.length) return html;
   // Sort longest tag name first so the regex alternation tries the most
@@ -388,9 +431,12 @@ async function injectDSD(html, ctx, ancestors = []) {
     // `<link rel="modulepreload">` hints for their module URLs.
     if (ctx && ctx.usedComponents) ctx.usedComponents.add(tag);
     let opening = selfClose ? `<${tag}${attrs}>` : match;
+    // Hoisted so the per-component error boundary (#469) can ask the failed
+    // instance for its renderError() output.
+    let instance = null;
     try {
       const isShadow = /** @type any */ (Cls).shadow === true;
-      const instance = new /** @type any */ (Cls)();
+      instance = new /** @type any */ (Cls)();
       // Thread the ancestor chain (the enclosing custom-element instances)
       // so the server element shim's closest() can resolve a parent at SSR.
       // Set before performServerUpdate so a willUpdate() that reads a parent
@@ -521,6 +567,60 @@ async function injectDSD(html, ctx, ancestors = []) {
       } else {
         console.error(`[webjs] SSR failed for <${tag}>:`, e);
       }
+      // Per-component error isolation (#469). A render that throws (most
+      // commonly a rejected `await getData()` in an async render, but any
+      // render throw) is caught HERE, per component: the loop continues so
+      // siblings render normally, and this element renders a component-scoped
+      // error state instead of bubbling to the route error.js or leaving its
+      // raw, unprocessed children in the output. renderError() customizes the
+      // error UI; the default surfaces the message in dev and renders an empty
+      // (silent, isolated) element in prod so no internal detail leaks.
+      const err = e instanceof Error ? e : new Error(String(e));
+      let errorInner = '';
+      try {
+        let errTpl;
+        if (instance && typeof instance.renderError === 'function') {
+          errTpl = instance.renderError(err);
+        }
+        if (errTpl === undefined) errTpl = defaultSSRErrorTemplate(tag, err);
+        errorInner = await render(errTpl, ctx);
+        if (errorInner.trim()) {
+          errorInner = await injectDSD(errorInner, ctx, instance ? [...ancestors, instance] : ancestors);
+        }
+      } catch (renderErrorThrew) {
+        console.error(`[webjs] renderError() for <${tag}> also threw:`, renderErrorThrew);
+        errorInner = '';
+      }
+      // Replace the element (opening tag through its matching close) with the
+      // error state plus a hydration marker, so the client error boundary
+      // (component.js renderError) can take over on hydration.
+      let closeEnd = m.index + match.length;
+      if (!selfClose) {
+        const innerStart = m.index + match.length;
+        const closeIdx = findClosingTagInString(html, innerStart, tag);
+        if (closeIdx !== -1) {
+          const closeRe = new RegExp(`</${escapeRegex(tag)}\\s*>`, 'i');
+          const cm = closeRe.exec(html.slice(closeIdx));
+          closeEnd = closeIdx + (cm ? cm[0].length : `</${tag}>`.length);
+        } else {
+          closeEnd = html.length;
+        }
+      }
+      // A shadow component renders into a shadow root on the client, so its
+      // SSR error state must ride a DSD template too (matching the success
+      // path), not land in light DOM. Otherwise the client renders the error
+      // into the shadow root while the light error box lingers underneath.
+      const isShadowErr = /** @type any */ (Cls).shadow === true;
+      let text;
+      if (isShadowErr) {
+        const rawStyles = /** @type any */ (Cls).styles;
+        const styleList = Array.isArray(rawStyles) ? rawStyles : rawStyles && isCSS(rawStyles) ? [rawStyles] : [];
+        const styleStr = stylesToString(styleList);
+        text = `${opening}<template shadowrootmode="open">${styleStr}${errorInner}</template>`;
+      } else {
+        text = `${opening}<!--webjs-hydrate-->${errorInner}</${tag}>`;
+      }
+      edits.push({ start: m.index, end: closeEnd, text });
     }
   }
   if (!edits.length) return html;
@@ -571,10 +671,79 @@ function isVoidElement(tag) {
 }
 
 /**
- * Find the position of the matching closing tag for `tagName` starting
- * from `fromIndex` in `html`. Handles nested same-tag elements via depth
- * tracking. Returns the index of the `<` of `</tagName>`, or -1 if
- * unclosed.
+ * Resolve `<webjs-suspense>` boundaries in an HTML string (#471). For each
+ * top-level boundary (nested ones are handled by the recursive injectDSD that
+ * processes a boundary's streamed children):
+ *
+ * - Streaming (a SuspenseCtx is present): emit the boundary as
+ *   `<webjs-suspense id="sN">FALLBACK</webjs-suspense>` and push the raw inner
+ *   children to `ctx.pending` (wrapped in `unsafeHTML` so the streaming pass
+ *   renders them as HTML, not escaped text, then runs injectDSD over them).
+ *   `streamSuspenseBoundaries` later streams the resolved children as a
+ *   `<template data-webjs-resolve="sN">` plus the swap script. Multiple
+ *   boundaries resolve via `Promise.all`, so their data fetches run
+ *   concurrently. The placeholder is the boundary's `.fallback`
+ *   (carried as `data-webjs-fallback`); a boundary without one shows empty.
+ * - Blocking (no ctx): render the children inline now and drop the fallback,
+ *   so a non-streaming `renderToString` returns the real content. The
+ *   `<webjs-suspense>` wrapper stays as an inert inline element.
+ *
+ * @param {string} html
+ * @param {SuspenseCtx} [ctx]
+ * @param {any[]} [ancestors]
+ * @returns {Promise<string>}
+ */
+async function processSuspenseElements(html, ctx, ancestors = []) {
+  if (html.indexOf('<webjs-suspense') === -1) return html;
+  const OPEN = /<webjs-suspense((?:"[^"]*"|'[^']*'|[^>])*?)>/i;
+  let result = '';
+  let rest = html;
+  // Bounded loop: each iteration consumes at least the opening tag.
+  for (let guard = 0; guard < 10000; guard++) {
+    const m = OPEN.exec(rest);
+    if (!m) {
+      result += rest;
+      break;
+    }
+    const openStart = m.index;
+    const openEnd = m.index + m[0].length;
+    result += rest.slice(0, openStart);
+    const attrs = m[1] || '';
+    const fbMatch = /data-webjs-fallback="([^"]*)"/i.exec(attrs);
+    const fallbackHtml = fbMatch ? unescapeAttr(fbMatch[1]) : '';
+
+    const closeIdx = findClosingTagInString(rest, openEnd, 'webjs-suspense');
+    let inner;
+    let afterClose;
+    if (closeIdx === -1) {
+      inner = rest.slice(openEnd);
+      afterClose = '';
+    } else {
+      inner = rest.slice(openEnd, closeIdx);
+      const cm = /<\/webjs-suspense\s*>/i.exec(rest.slice(closeIdx));
+      afterClose = rest.slice(closeIdx + (cm ? cm[0].length : '</webjs-suspense>'.length));
+    }
+
+    if (ctx) {
+      const id = `s${ctx.nextId++}`;
+      // Raw children stream in later. unsafeHTML so the streaming pass emits
+      // the markup verbatim (then injectDSD runs over it, resolving the async
+      // components and any nested boundaries).
+      ctx.pending.push({ id, promise: Promise.resolve(unsafeHTML(inner)) });
+      result += `<webjs-suspense id="${id}">${fallbackHtml}</webjs-suspense>`;
+    } else {
+      const innerProcessed = await injectDSD(inner, ctx, ancestors);
+      result += `<webjs-suspense>${innerProcessed}</webjs-suspense>`;
+    }
+    rest = afterClose;
+  }
+  return result;
+}
+
+/**
+ * Find the position of the matching closing tag for `tagName` starting from
+ * `fromIndex` in `html`. Handles nested same-tag elements via depth tracking.
+ * Returns the index of the `<` of `</tagName>`, or -1 if unclosed.
  *
  * @param {string} html
  * @param {number} fromIndex
@@ -1259,13 +1428,34 @@ async function streamSuspenseBoundaries(ctx, controller) {
             `(function(){` +
             `var t=document.currentScript.previousElementSibling;` +
             `var b=document.getElementById("${id}");` +
-            `if(b&&t){b.innerHTML=t.innerHTML;t.remove()}` +
+            `if(b&&t){b.replaceWith(t.content.cloneNode(true));t.remove()}` +
             `document.currentScript.remove()` +
             `})()` +
             `</script>`
           );
         } catch (err) {
           console.error(`[webjs] Suspense boundary "${id}" rejected:`, err);
+          // Render a boundary-scoped error state rather than leaving the
+          // fallback stuck forever (#471). Dev surfaces the message; prod
+          // renders a silent empty element (no leak). A failure HERE (the
+          // error render itself throwing) leaves the fallback in place.
+          try {
+            const e = err instanceof Error ? err : new Error(String(err));
+            const errHtml = await injectDSD(await render(defaultSSRErrorTemplate('webjs-suspense', e), ctx), ctx);
+            controller.enqueue(
+              `<template data-webjs-resolve="${id}">${errHtml}</template>` +
+              `<script${nonceAttr}>` +
+              `(function(){` +
+              `var t=document.currentScript.previousElementSibling;` +
+              `var b=document.getElementById("${id}");` +
+              `if(b&&t){b.replaceWith(t.content.cloneNode(true));t.remove()}` +
+              `document.currentScript.remove()` +
+              `})()` +
+              `</script>`
+            );
+          } catch (errorRenderThrew) {
+            console.error(`[webjs] Suspense boundary "${id}" error render also threw:`, errorRenderThrew);
+          }
         }
       })
     );