@webjsdev/core 0.7.17 → 0.7.19

package/index-browser.js

@@ -52,6 +52,16 @@ 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';
+// Client tag-cache coordinator for HTTP-verb actions (#488): tag-based
+// browser-cache eviction after a mutation. Inert server-side.
+export { markStale, registerKeyTags, consumeStale, parseTagHeader, fetchMark } from './src/action-cache-client.js';
+// Client action-abort plumbing (#492): a superseded async render aborts its
+// in-flight action fetches. Inert server-side.
+export { setActiveActionSignal, activeActionSignal } from './src/action-abort-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,11 @@ 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 { markStale, registerKeyTags, consumeStale, parseTagHeader, fetchMark } from './src/action-cache-client.js';
+// Client action-abort plumbing (#492): a superseded async render aborts its
+// in-flight action fetches. Inert server-side.
+export { setActiveActionSignal, activeActionSignal } from './src/action-abort-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,16 @@ 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';
+// Client tag-cache coordinator for HTTP-verb actions (#488): tag-based
+// browser-cache eviction after a mutation. Inert server-side.
+export { markStale, registerKeyTags, consumeStale, parseTagHeader, fetchMark } from './src/action-cache-client.js';
+// Client action-abort plumbing (#492): a superseded async render aborts its
+// in-flight action fetches. Inert server-side.
+export { setActiveActionSignal, activeActionSignal } from './src/action-abort-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.17",
+  "version": "0.7.19",
   "type": "module",
   "description": "webjs core runtime - html/css tags, WebComponent base, isomorphic renderers",
   "types": "./index.d.ts",

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

@@ -0,0 +1,3 @@
+/** Client action-abort plumbing (#492). Inert server-side. */
+export function setActiveActionSignal(signal: AbortSignal | null): void;
+export function activeActionSignal(): AbortSignal | undefined;

package/src/action-abort-client.js

@@ -0,0 +1,39 @@
+/**
+ * Client-side action abort plumbing (#492).
+ *
+ * An `async render()` that supersedes an in-flight one should ABORT the previous
+ * render's action fetches, not just drop their results. The component sets a
+ * fresh AbortController's signal as the "active" signal right before each render
+ * (`setActiveActionSignal`), and the generated RPC stub binds every `fetch` to
+ * `activeActionSignal()`. When the next render supersedes, the component aborts
+ * the previous controller, cancelling those fetches.
+ *
+ * Best-effort by design: the stub reads the active signal SYNCHRONOUSLY when the
+ * action is called, so it binds for an action invoked in the synchronous portion
+ * of `render()` (the common `const u = await getUser(id)` first statement). An
+ * action invoked after a later `await` may see no active signal; it then simply
+ * runs to completion and its result is dropped by the existing render-token
+ * guard, exactly as before this feature. Inert server-side (never set there).
+ */
+
+/** The AbortSignal the currently-rendering component bound, or null. */
+let active = null;
+
+/**
+ * Set (or clear with null) the signal the generated RPC stub binds its fetches
+ * to. The component sets this around the synchronous portion of `render()`.
+ * @param {AbortSignal | null} signal
+ */
+export function setActiveActionSignal(signal) {
+  active = signal || null;
+}
+
+/**
+ * The active abort signal a stub should bind a fetch to, or undefined when no
+ * render is in flight (an action called from an event handler is not bound, so
+ * a re-render never aborts a user-triggered mutation).
+ * @returns {AbortSignal | undefined}
+ */
+export function activeActionSignal() {
+  return active || undefined;
+}

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

@@ -0,0 +1,6 @@
+/** Client tag-cache coordinator for HTTP-verb server actions (#488). Inert server-side. */
+export function markStale(tags: string[]): void;
+export function fetchMark(): number;
+export function registerKeyTags(key: string, tags: string[], since?: number): void;
+export function consumeStale(key: string): boolean;
+export function parseTagHeader(value: string | null): string[];

package/src/action-cache-client.js

@@ -0,0 +1,103 @@
+/**
+ * Client-side tag cache coordinator for HTTP-verb server actions (#488).
+ *
+ * A GET action is cached by the BROWSER HTTP cache (its `Cache-Control` +
+ * ETag). After a mutation, that cached entry would still be served within its
+ * `max-age`, so a tag-based eviction is layered on top: the server tells the
+ * client which tags a GET belongs to (the `X-Webjs-Tags` response header) and
+ * which tags a mutation invalidated (`X-Webjs-Invalidate`). When a later GET's
+ * tags were invalidated AFTER that key's last fetch STARTED, the stub re-fetches
+ * with `cache: 'no-cache'` (a conditional revalidation that bypasses the stale
+ * browser-cache entry and returns fresh data, since the ETag changed).
+ *
+ * Mechanism: a monotonic CLOCK, bumped on every invalidation. Each tag records
+ * the clock at its last invalidation; each GET records the clock value SAMPLED
+ * JUST BEFORE its fetch was dispatched. A read needs a bypass when any of its
+ * tags was invalidated at a clock value greater than the key's sampled value.
+ * Sampling before the fetch (not when the response lands) is what closes the
+ * race where a mutation commits while a read is in flight: such a mutation has
+ * a higher clock than the read's sample, so the next read still bypasses.
+ *
+ * A thin coordinator, NOT a data store (the data lives in the browser HTTP
+ * cache, on-thesis: no bespoke client query cache). Inert server-side.
+ */
+
+/** Monotonic logical clock; bumped once per `markStale` call. */
+let clock = 0;
+
+/** `tag -> clock value at its last invalidation`. */
+const tagInvalidatedAt = new Map();
+
+/** `key -> { tags, since }` where `since` is the clock sampled before its fetch. */
+const keyInfo = new Map();
+
+/** Bound `keyInfo` growth for a long-lived session (FIFO-evict the oldest). */
+const MAX_KEYS = 1000;
+
+/**
+ * Mark tags invalidated (called after a mutation reports `X-Webjs-Invalidate`):
+ * advance the clock and stamp each tag with it.
+ * @param {string[]} tags
+ */
+export function markStale(tags) {
+  if (!Array.isArray(tags) || !tags.length) return;
+  clock += 1;
+  for (const t of tags) if (t) tagInvalidatedAt.set(t, clock);
+}
+
+/**
+ * Sample the clock just before dispatching a GET fetch. The value is passed to
+ * `registerKeyTags` so an invalidation that lands WHILE the fetch is in flight
+ * (a higher clock than this sample) is detected on the next read.
+ * @returns {number}
+ */
+export function fetchMark() {
+  return clock;
+}
+
+/**
+ * Record the tags a GET response declared for its key, stamped with the clock
+ * value sampled before the fetch (`since`).
+ * @param {string} key the GET cache key (`stringify(args)`)
+ * @param {string[]} tags
+ * @param {number} [since] the `fetchMark()` sampled before the fetch
+ */
+export function registerKeyTags(key, tags, since) {
+  if (!Array.isArray(tags) || !tags.length) return;
+  // Re-insert to move the key to the newest position (LRU-ish), then cap.
+  keyInfo.delete(key);
+  keyInfo.set(key, { tags: tags.slice(), since: typeof since === 'number' ? since : clock });
+  if (keyInfo.size > MAX_KEYS) {
+    const oldest = keyInfo.keys().next().value;
+    if (oldest !== undefined) keyInfo.delete(oldest);
+  }
+}
+
+/**
+ * Whether a GET for `key` should bypass the browser cache (re-fetch with
+ * `cache: 'no-cache'`) because one of its tags was invalidated AFTER this key's
+ * last fetch started. An unrecorded key (never fetched, e.g. resolved from the
+ * SSR seed) returns false: its browser-cache entry does not exist yet, so a
+ * normal fetch already returns fresh data.
+ * @param {string} key
+ * @returns {boolean}
+ */
+export function consumeStale(key) {
+  const info = keyInfo.get(key);
+  if (!info) return false;
+  for (const t of info.tags) if ((tagInvalidatedAt.get(t) || 0) > info.since) return true;
+  return false;
+}
+
+/** Parse a comma-separated tag header into a trimmed, non-empty list. */
+export function parseTagHeader(value) {
+  if (!value) return [];
+  return value.split(',').map((s) => s.trim()).filter(Boolean);
+}
+
+/** Test seam: clear all tag state. */
+export function __resetActionCache() {
+  clock = 0;
+  tagInvalidatedAt.clear();
+  keyInfo.clear();
+}

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/component.js

@@ -1,4 +1,5 @@
 import { render as clientRender } from './render-client.js';
+import { setActiveActionSignal } from './action-abort-client.js';
 import { isCSS, adoptStyles } from './css.js';
 import { register, tagOf } from './registry.js';
 import { parse as deserializeProp } from './serialize.js';
@@ -1015,11 +1016,23 @@ export class WebComponent extends Base {
         // 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;
+        // Abort the superseded render's in-flight action fetches (#492), start a
+        // fresh controller for this render, and bind it as the active signal so
+        // the RPC stub ties its fetches to this render. A superseded fetch's
+        // AbortError is dropped by the render-token guard in _commitAsync.
+        if (this.__renderAbort) this.__renderAbort.abort();
+        this.__renderAbort = typeof AbortController !== 'undefined' ? new AbortController() : null;
+        setActiveActionSignal(this.__renderAbort ? this.__renderAbort.signal : null);
         try {
           const r = this.update(changedProperties);
           if (r && typeof r.then === 'function') pendingCommit = r;
         } catch (error) {
           this._handleRenderError(/** @type {Error} */ (error));
+        } finally {
+          // The synchronous portion of render() has run; actions invoked there
+          // already captured the signal. Clear it so a later event handler is
+          // not bound to a stale render's controller.
+          setActiveActionSignal(null);
         }
 
         if (!pendingCommit) {

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/serialize.js

@@ -51,6 +51,36 @@
 const TAG = '_$wj';
 const ID_KEY = '_id';
 
+/**
+ * Keys that, assigned with bracket notation, mutate the target instead of
+ * adding an own data property: `out['__proto__'] = x` invokes the prototype
+ * setter (a prototype-pollution vector on decode, reachable because
+ * `JSON.parse` makes a wire `"__proto__"` an OWN key; and on encode it silently
+ * DROPS a legitimate own `__proto__` data property and corrupts the
+ * accumulator's prototype). `constructor` / `prototype` shadow in ways
+ * downstream code can be confused by.
+ */
+const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+/**
+ * Assign `value` onto a plain accumulator under `key`. A normal key is a plain
+ * assignment (the hot path); an unsafe key is written as an ordinary own
+ * enumerable data property via `defineProperty`, so the value survives as data
+ * (round-trippable, since JSON includes an own enumerable `__proto__`) and the
+ * prototype chain is never touched. Used on BOTH the encode and decode object
+ * loops so `serialize` / `deserialize` stay inverses on these keys.
+ * @param {Record<string, unknown>} out
+ * @param {string} key
+ * @param {unknown} value
+ */
+function safeAssign(out, key, value) {
+  if (UNSAFE_KEYS.has(key)) {
+    Object.defineProperty(out, key, { value, writable: true, enumerable: true, configurable: true });
+  } else {
+    out[key] = value;
+  }
+}
+
 /* ----------------------------------------------------------------- *
  * Public API                                                        *
  * ----------------------------------------------------------------- */
@@ -225,7 +255,7 @@ function encodeOne(v, ctx) {
     for (const k in v) {
       if (!Object.prototype.hasOwnProperty.call(v, k)) continue;
       const escaped = isReservedKey(k) ? '_' + k : k;
-      out[escaped] = encodeOne(v[k], ctx);
+      safeAssign(out, escaped, encodeOne(v[k], ctx));
     }
   }
 
@@ -314,7 +344,7 @@ function decode(v, ctx) {
     if (!Object.prototype.hasOwnProperty.call(v, k)) continue;
     if (k === ID_KEY) continue;
     const realKey = isEscapedReservedKey(k) ? k.slice(1) : k;
-    out[realKey] = decode(v[k], ctx);
+    safeAssign(out, realKey, decode(v[k], ctx));
   }
   return out;
 }

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[];