@webjsdev/core 0.7.16 → 0.7.18

package/index-browser.js

@@ -52,6 +52,10 @@ export { signal, computed, effect, batch, isSignal, Signal } from './src/signal.
 // Optimistic-mutation helper (thin signal wrapper, rolls back on failure)
 export { optimistic } from './src/optimistic.js';
 
+// SSR action-seed consumer (#472): the generated RPC stub reads a seed on its
+// first call so async-render hydration does not re-fetch the SSR'd data.
+export { takeSeed, scanSeeds, SEED_MISS } from './src/action-seed-client.js';
+
 // Directives, also available via '@webjsdev/core/directives'. The full
 // lit-html-parity set is re-exported here so the dist browser bundle (which
 // the `@webjsdev/core/directives` subpath collapses onto in dist mode) carries

package/index.d.ts

@@ -91,6 +91,7 @@ export { Task, TaskStatus } from './src/task.js';
 // src/*.d.ts (#388 fixed the index.d.ts drift from index.js).
 export { signal, computed, effect, batch, isSignal, Signal } from './src/signal.js';
 export { cspNonce, setCspNonceProvider } from './src/csp-nonce.js';
+export { takeSeed, scanSeeds, SEED_MISS } from './src/action-seed-client.js';
 export { stringify, parse, serialize, deserialize } from './src/serialize.js';
 export { WebjsFrame } from './src/webjs-frame.js';
 export { WebjsStream, renderStream } from './src/webjs-stream.js';

package/index.js

@@ -34,6 +34,10 @@ export { signal, computed, effect, batch, isSignal, Signal } from './src/signal.
 // Optimistic-mutation helper (thin signal wrapper, rolls back on failure)
 export { optimistic } from './src/optimistic.js';
 
+// SSR action-seed consumer (#472): the generated RPC stub reads a seed on its
+// first call so async-render hydration does not re-fetch. Inert server-side.
+export { takeSeed, scanSeeds, SEED_MISS } from './src/action-seed-client.js';
+
 // Directives, also available via '@webjsdev/core/directives'. The full
 // lit-html-parity set is re-exported so the bare specifier exposes the same
 // directive surface in Node as the browser bundle does.

package/package.json

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

package/src/action-seed-client.d.ts

@@ -0,0 +1,17 @@
+/** Client-side SSR action-seed consumer (#472). Inert server-side. */
+
+/** Returned by `takeSeed` when no seed matches; distinct from any real value. */
+export const SEED_MISS: unique symbol;
+
+/**
+ * Merge any seeds found under `root` (or the whole document) into the global
+ * consume-once store, removing the carriers. Reads the page-level
+ * `#__webjs-seeds` JSON block and per-element `[data-webjs-seed]` carriers.
+ */
+export function scanSeeds(root?: ParentNode): void;
+
+/**
+ * Look up and CONSUME the seed for an action call, or return `SEED_MISS`.
+ * Keyed `hash/fn/argsKey`; the first call lazily scans the initial document.
+ */
+export function takeSeed(hash: string, fnName: string, argsKey: string): unknown;

package/src/action-seed-client.js

@@ -0,0 +1,107 @@
+/**
+ * Client-side SSR action-seed consumer (#472).
+ *
+ * The server (`@webjsdev/server`'s `action-seed.js`) serializes each action
+ * result invoked during SSR into a `<script type="application/json"
+ * id="__webjs-seeds">` block (and, for streamed regions, per-element
+ * `data-webjs-seed` attributes). On the client, the generated RPC stub
+ * (`actions.js`) calls `takeSeed(hash, fn, argsKey)` on its FIRST invocation: a
+ * hit resolves the action synchronously with the SSR value (no RPC, no flicker
+ * on hydration); a miss falls through to the normal RPC.
+ *
+ * Consume-once: a hit removes the seed, so a later refetch / arg-change always
+ * goes to the network (the seed is a first-paint optimization, not a cache).
+ * Keyed `hash/fn/stringify(args)`, where `hash` and `stringify` match exactly
+ * what the server emitted, so distinct components and distinct args each map to
+ * their own seed. A miss is always safe (it just re-fetches).
+ *
+ * This module is imported by the generated stub via the bare `@webjsdev/core`
+ * specifier; on the server it is inert (its only DOM access is inside
+ * `scanSeeds`, never called server-side).
+ */
+
+import { parse } from './serialize.js';
+
+/** Global consume-once seed store: `key -> value`. */
+const seeds = new Map();
+
+/** Returned by `takeSeed` when no seed matches; distinct from any real value. */
+export const SEED_MISS = Symbol('webjs.seed.miss');
+
+/** One-time eager scan guard (the initial-load document is scanned lazily). */
+let scannedInitial = false;
+
+/**
+ * Merge any seeds found under `root` into the global store, then remove the
+ * carriers so a re-scan (a streamed boundary, a soft navigation) never
+ * re-ingests stale data. Reads both the page-level `#__webjs-seeds` JSON block
+ * and per-element `[data-webjs-seed]` carriers. Idempotent and fail-open: a
+ * malformed payload is skipped, never thrown.
+ * @param {ParentNode & { querySelectorAll?: Function }} [root]
+ */
+export function scanSeeds(root) {
+  const scope = root || (typeof document !== 'undefined' ? document : null);
+  if (!scope || typeof scope.querySelectorAll !== 'function') return;
+  // Page-level JSON block(s).
+  for (const el of scope.querySelectorAll('script[type="application/json"]#__webjs-seeds, script[type="application/json"][data-webjs-seeds]')) {
+    ingest(el.textContent, el);
+  }
+  // Per-element carriers (streamed boundaries / future per-component seeding).
+  for (const el of scope.querySelectorAll('[data-webjs-seed]')) {
+    ingest(el.getAttribute('data-webjs-seed'), el, () => el.removeAttribute('data-webjs-seed'));
+  }
+}
+
+/**
+ * Parse one serialized seed payload and merge it (first write wins, so an
+ * already-consumed or earlier seed is never clobbered by a later duplicate),
+ * then run `cleanup` (or remove the element).
+ * @param {string | null} raw
+ * @param {Element} el
+ * @param {() => void} [cleanup]
+ */
+function ingest(raw, el, cleanup) {
+  if (raw) {
+    try {
+      const obj = parse(raw);
+      if (obj && typeof obj === 'object') {
+        for (const k in obj) if (!seeds.has(k)) seeds.set(k, obj[k]);
+      }
+    } catch {
+      // Malformed payload: ignore, the stub re-fetches.
+    }
+  }
+  if (cleanup) cleanup();
+  else el.remove?.();
+}
+
+/**
+ * Look up and CONSUME the seed for an action call. Returns the seeded value
+ * (removing it) on a hit, or `SEED_MISS` when there is none. The first call
+ * lazily scans the initial document, so the boot path needs no wiring; the
+ * router calls `scanSeeds(subtree)` for content that arrives later.
+ * @param {string} hash the action file's hash (the RPC endpoint hash)
+ * @param {string} fnName the exported action name
+ * @param {string} argsKey `stringify(args)`, computed by the stub with the same
+ *   serializer the server used, so identical args produce an identical key
+ * @returns {unknown | typeof SEED_MISS}
+ */
+export function takeSeed(hash, fnName, argsKey) {
+  if (!scannedInitial) {
+    scannedInitial = true;
+    scanSeeds();
+  }
+  const key = `${hash}/${fnName}/${argsKey}`;
+  if (seeds.has(key)) {
+    const v = seeds.get(key);
+    seeds.delete(key);
+    return v;
+  }
+  return SEED_MISS;
+}
+
+/** Test seam: drop all seeds and reset the lazy-scan guard. */
+export function __resetSeeds() {
+  seeds.clear();
+  scannedInitial = false;
+}

package/src/render-server.js

@@ -30,8 +30,14 @@ import { cspNonce } from './csp-nonce.js';
  */
 export async function renderToString(value, opts = { ssr: true }) {
   const ctx = opts && opts.suspenseCtx;
+  // The server `dev` flag drives prod-silence of SSR error states (#483).
+  // `opts.dev` wins; else inherit a `dev` already stamped on the ctx (so a
+  // streamed sub-context inherits it); back-fill the ctx so downstream renders
+  // sharing it see the same flag. Undefined stays undefined (NODE_ENV fallback).
+  const dev = opts && opts.dev !== undefined ? opts.dev : ctx && ctx.dev;
+  if (ctx && ctx.dev === undefined && dev !== undefined) ctx.dev = dev;
   const html = await render(value, ctx);
-  return opts && opts.ssr === false ? html : await injectDSD(html, ctx);
+  return opts && opts.ssr === false ? html : await injectDSD(html, ctx, [], dev);
 }
 
 /**
@@ -377,12 +383,21 @@ function isProd() {
  * Dev surfaces the tag + message loudly so the failure is obvious; prod
  * renders an empty (silent, isolated) element so no internal detail leaks.
  *
+ * The prod-silence signal is the SERVER's `dev` flag, threaded through the SSR
+ * render context (#483). webjs keys prod on the CLI `dev` flag, not `NODE_ENV`,
+ * and `webjs start` does not export `NODE_ENV=production`, so a bare prod launch
+ * would otherwise leak the message. When `dev` is undefined (a context-free
+ * `renderToString` with no server signal, e.g. a bare unit test) it falls back
+ * to `isProd()` / `NODE_ENV`, preserving the prior behaviour for that path.
+ *
  * @param {string} tag
  * @param {Error} err
+ * @param {boolean} [dev]  server dev flag; undefined falls back to NODE_ENV
  * @returns {unknown} a TemplateResult (dev) or '' (prod)
  */
-function defaultSSRErrorTemplate(tag, err) {
-  if (isProd()) return '';
+function defaultSSRErrorTemplate(tag, err, dev) {
+  const surface = dev === undefined ? !isProd() : !!dev;
+  if (!surface) 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>
@@ -397,15 +412,18 @@ function defaultSSRErrorTemplate(tag, err) {
  *
  * @param {string} html
  * @param {SuspenseCtx} [ctx]
+ * @param {any[]} [ancestors]
+ * @param {boolean} [dev]  server dev flag, threaded to the per-component error
+ *   template for prod-silence (#483); undefined falls back to NODE_ENV
  * @returns {Promise<string>}
  */
-async function injectDSD(html, ctx, ancestors = []) {
+async function injectDSD(html, ctx, ancestors = [], dev) {
   // 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);
+  html = await processSuspenseElements(html, ctx, ancestors, dev);
   const tags = allTags();
   if (!tags.length) return html;
   // Sort longest tag name first so the regex alternation tries the most
@@ -487,7 +505,7 @@ async function injectDSD(html, ctx, ancestors = []) {
         // Shadow DOM: native <slot> stays as-is in the DSD template. The
         // browser handles projection from the host's light-DOM children
         // into the shadow tree natively. No framework substitution here.
-        const innerProcessed = await injectDSD(rawInner, ctx, [...ancestors, instance]);
+        const innerProcessed = await injectDSD(rawInner, ctx, [...ancestors, instance], dev);
         const rawStyles = /** @type any */ (Cls).styles;
         const styleList = Array.isArray(rawStyles) ? rawStyles : rawStyles && isCSS(rawStyles) ? [rawStyles] : [];
         const styleStr = stylesToString(styleList);
@@ -550,7 +568,7 @@ async function injectDSD(html, ctx, ancestors = []) {
         }
         const partitioned = partitionAuthoredBySlot(authoredInner);
         const innerWithSlots = substituteSlotsInRender(rawInner, partitioned);
-        const innerProcessed = await injectDSD(innerWithSlots, ctx, [...ancestors, instance]);
+        const innerProcessed = await injectDSD(innerWithSlots, ctx, [...ancestors, instance], dev);
         edits.push({
           start: m.index,
           end: closeEnd,
@@ -582,10 +600,10 @@ async function injectDSD(html, ctx, ancestors = []) {
         if (instance && typeof instance.renderError === 'function') {
           errTpl = instance.renderError(err);
         }
-        if (errTpl === undefined) errTpl = defaultSSRErrorTemplate(tag, err);
+        if (errTpl === undefined) errTpl = defaultSSRErrorTemplate(tag, err, dev);
         errorInner = await render(errTpl, ctx);
         if (errorInner.trim()) {
-          errorInner = await injectDSD(errorInner, ctx, instance ? [...ancestors, instance] : ancestors);
+          errorInner = await injectDSD(errorInner, ctx, instance ? [...ancestors, instance] : ancestors, dev);
         }
       } catch (renderErrorThrew) {
         console.error(`[webjs] renderError() for <${tag}> also threw:`, renderErrorThrew);
@@ -691,9 +709,11 @@ function isVoidElement(tag) {
  * @param {string} html
  * @param {SuspenseCtx} [ctx]
  * @param {any[]} [ancestors]
+ * @param {boolean} [dev]  server dev flag for prod-silence of a throwing
+ *   component in an inline (ctx-absent) boundary (#483)
  * @returns {Promise<string>}
  */
-async function processSuspenseElements(html, ctx, ancestors = []) {
+async function processSuspenseElements(html, ctx, ancestors = [], dev) {
   if (html.indexOf('<webjs-suspense') === -1) return html;
   const OPEN = /<webjs-suspense((?:"[^"]*"|'[^']*'|[^>])*?)>/i;
   let result = '';
@@ -732,7 +752,7 @@ async function processSuspenseElements(html, ctx, ancestors = []) {
       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);
+      const innerProcessed = await injectDSD(inner, ctx, ancestors, dev);
       result += `<webjs-suspense>${innerProcessed}</webjs-suspense>`;
     }
     rest = afterClose;
@@ -1130,6 +1150,11 @@ function consumePropAttrs(attrs) {
  */
 export function renderToStream(value, opts = { ssr: true }) {
   const ctx = opts && opts.suspenseCtx;
+  // Server dev flag for prod-silence of SSR error states (#483), same sourcing
+  // as renderToString: opts.dev wins, else inherit from the ctx, else undefined
+  // (NODE_ENV fallback). Back-fill the ctx so the streamed sub-renders share it.
+  const dev = opts && opts.dev !== undefined ? opts.dev : ctx && ctx.dev;
+  if (ctx && ctx.dev === undefined && dev !== undefined) ctx.dev = dev;
   return new ReadableStream({
     async start(controller) {
       try {
@@ -1141,13 +1166,13 @@ export function renderToStream(value, opts = { ssr: true }) {
           // the full HTML), then enqueue the result. This matches the
           // semantics of renderToString but still gives us a stream.
           const html = await render(value, ctx);
-          const full = await injectDSD(html, ctx);
+          const full = await injectDSD(html, ctx, [], dev);
           controller.enqueue(full);
         }
 
         // Stream resolved Suspense boundaries after the main content.
         if (ctx && ctx.pending.length) {
-          await streamSuspenseBoundaries(ctx, controller);
+          await streamSuspenseBoundaries(ctx, controller, dev);
         }
         controller.close();
       } catch (err) {
@@ -1404,8 +1429,10 @@ async function streamTemplate(tr, ctx, controller) {
  *
  * @param {SuspenseCtx} ctx
  * @param {ReadableStreamDefaultController<string>} controller
+ * @param {boolean} [dev]  server dev flag for prod-silence of a rejected
+ *   streamed boundary (#483); undefined falls back to NODE_ENV
  */
-async function streamSuspenseBoundaries(ctx, controller) {
+async function streamSuspenseBoundaries(ctx, controller, dev) {
   // Resolve the per-request nonce once per call. The provider in
   // @webjsdev/server sources it from AsyncLocalStorage; outside a
   // request scope (or in the browser) the helper returns '' and we
@@ -1421,7 +1448,7 @@ async function streamSuspenseBoundaries(ctx, controller) {
         try {
           const resolved = await promise;
           const html = await render(resolved, ctx);
-          const full = await injectDSD(html, ctx);
+          const full = await injectDSD(html, ctx, [], dev);
           controller.enqueue(
             `<template data-webjs-resolve="${id}">${full}</template>` +
             `<script${nonceAttr}>` +
@@ -1441,7 +1468,7 @@ async function streamSuspenseBoundaries(ctx, controller) {
           // 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);
+            const errHtml = await injectDSD(await render(defaultSSRErrorTemplate('webjs-suspense', e, dev), ctx), ctx, [], dev);
             controller.enqueue(
               `<template data-webjs-resolve="${id}">${errHtml}</template>` +
               `<script${nonceAttr}>` +

package/src/router-client.js

@@ -11,6 +11,9 @@ import { renderStream } from './webjs-stream.js';
 // Register <webjs-suspense> (the element-level streaming boundary, #471) so it
 // is layout-neutral and available for the progressive soft-nav streaming apply.
 import './webjs-suspense.js';
+// Ingest SSR action seeds (#472) from an incoming soft-nav document before its
+// components hydrate, so a navigated async component resolves from the seed.
+import { scanSeeds } from './action-seed-client.js';
 
 /** The content type a content-negotiated stream-action response carries (#248). */
 const STREAM_MIME = 'text/vnd.webjs-stream.html';
@@ -2067,6 +2070,13 @@ function upgradeCustomElementsInRange(range) {
 }
 
 function applySwap(doc, frameId, revalidating, href, incomingBuild) {
+  // SSR action seeding (#472): ingest any seed payload the incoming page
+  // carries BEFORE its components are grafted into the live DOM and upgrade, so
+  // a soft-navigated async component resolves from the seed instead of
+  // re-fetching. Scanning `doc` (the detached parse) also strips the seed
+  // carriers, so the inert payload never lands in the live document.
+  try { scanSeeds(doc); } catch { /* seeding is best-effort */ }
+
   // Any clean swap (no importmap mismatch, including cache restores
   // and frame swaps where we don't even run the mismatch check) is a
   // signal that the user successfully navigated, so clear the reload

package/src/webjs-config.d.ts

@@ -109,6 +109,15 @@ export interface WebjsConfig {
    */
   elide?: boolean;
 
+  /**
+   * SSR action-result seeding switch (#472). Default `true`. When on, a
+   * `'use server'` action's SSR result is serialized into the page so an
+   * `async render()` component does not re-fetch it over RPC on hydration. Set
+   * to `false` to disable (the client re-fetches as before). The `WEBJS_SEED`
+   * env override wins over this.
+   */
+  seed?: boolean;
+
   /** Per-path response-header rules, shaped like Next's. */
   headers?: WebjsHeaderRule[];