@webjsdev/core 0.7.4 → 0.7.5

package/package.json

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

package/src/render-server.js

@@ -314,6 +314,41 @@ async function renderTemplate(tr, ctx) {
   return out;
 }
 
+// Browser-only names whose absence during SSR produces a recognisable error.
+// Mirrors the `no-browser-globals-in-render` webjs check rule, which catches
+// these at edit time; this turns the runtime SSR crash into the same guidance.
+const SSR_BROWSER_GLOBALS = new Set([
+  'document', 'window', 'localStorage', 'sessionStorage', 'navigator',
+  'matchMedia', 'requestAnimationFrame', 'getComputedStyle',
+  'IntersectionObserver', 'MutationObserver', 'ResizeObserver',
+]);
+const SSR_HTMLELEMENT_METHODS = new Set([
+  'attachShadow', 'setAttribute', 'getAttribute', 'removeAttribute',
+  'hasAttribute', 'dispatchEvent', 'querySelector', 'querySelectorAll',
+  'getBoundingClientRect', 'focus', 'blur', 'scrollIntoView',
+]);
+
+/**
+ * If `e` is the recognisable failure of touching a browser-only API during
+ * SSR (a `ReferenceError` for a browser global, or a `TypeError` calling an
+ * HTMLElement method that does not exist on the bare server-side instance),
+ * return an actionable, member-naming hint; otherwise null.
+ * @param {unknown} e
+ * @returns {string | null}
+ */
+function browserMemberHint(e) {
+  const msg = e && typeof (/** @type any */ (e).message) === 'string' ? /** @type any */ (e).message : '';
+  let m = /^(\w+) is not defined$/.exec(msg);
+  if (e instanceof ReferenceError && m && SSR_BROWSER_GLOBALS.has(m[1])) {
+    return `\`${m[1]}\` is a browser-only global and is undefined during SSR.`;
+  }
+  m = /\.(\w+) is not a function$/.exec(msg);
+  if (e instanceof TypeError && m && SSR_HTMLELEMENT_METHODS.has(m[1])) {
+    return `\`${m[1]}\` is an HTMLElement method that does not exist on the server-side component instance during SSR.`;
+  }
+  return null;
+}
+
 /**
  * Scan an HTML string for registered custom elements and inject
  * Declarative Shadow DOM (`<template shadowrootmode="open">`).
@@ -443,7 +478,15 @@ async function injectDSD(html, ctx) {
         });
       }
     } catch (e) {
-      console.error(`[webjs] SSR failed for <${tag}>:`, e);
+      const hint = browserMemberHint(e);
+      if (hint) {
+        console.error(
+          `[webjs] SSR failed for <${tag}>: ${hint} It was touched in the component's constructor or render(), which run during SSR. Move browser-only work to connectedCallback() or a lifecycle hook (firstUpdated/updated), which SSR never calls; seed first-paint defaults in the constructor only from server-known inputs (attributes / props).`,
+          e,
+        );
+      } else {
+        console.error(`[webjs] SSR failed for <${tag}>:`, e);
+      }
     }
   }
   if (!edits.length) return html;

package/src/router-client.js

@@ -1003,7 +1003,17 @@ function drainPrefetchQueue() {
 }
 
 /**
- * Store a speculative entry under LRU + cap.
+ * Store a speculative entry under LRU + cap, then announce that the
+ * fragment is cached and consumable.
+ *
+ * The `webjs:prefetch` event fires the instant a speculative fragment
+ * becomes consumable (after the response body has been read), which is
+ * strictly later than the prefetch request going out. App code can
+ * listen to instrument prefetch hit rate, and tests can await it to know
+ * a subsequent click will consume the cache rather than refetch. The
+ * detail carries the cached URL and a `from: 'prefetch'` tag so a single
+ * listener can disambiguate it from `webjs:navigate`.
+ *
  * @param {string} key
  * @param {PrefetchEntry} entry
  */
@@ -1014,6 +1024,11 @@ function prefetchStore(key, entry) {
     const oldest = prefetchCache.keys().next().value;
     prefetchCache.delete(oldest);
   }
+  if (typeof document !== 'undefined') {
+    document.dispatchEvent(new CustomEvent('webjs:prefetch', {
+      detail: { url: entry.finalUrl, key, from: 'prefetch' },
+    }));
+  }
 }
 
 /**
@@ -1267,7 +1282,7 @@ async function fetchAndApply(href, frameId, recordHistory, optimisticState, meth
     }
   }
 
-  document.dispatchEvent(new CustomEvent('webjs:navigate', { detail: { url: finalUrl, frameId } }));
+  document.dispatchEvent(new CustomEvent('webjs:navigate', { detail: { url: finalUrl, frameId, from: 'navigate' } }));
 }
 
 /**

package/src/serialize.js

@@ -321,15 +321,26 @@ function decode(v, ctx) {
 
 function decodeTagged(v, tag, ctx) {
   const id = v[ID_KEY];
+  // Register the decoded value under its `_id` so a later `Ref` to it
+  // resolves. Container tags (Map/Set/Arr/Error/object) register BEFORE
+  // decoding children (so a cycle through the container resolves); leaf
+  // rich types (Date, typed arrays, Blob, ...) have no children and register
+  // through this helper at return. Without it, a SHARED Date or typed array
+  // (the same instance appearing twice) decodes the first copy but throws
+  // "Dangling reference" on the second.
+  const reg = (value) => {
+    if (typeof id === 'number') ctx.refs.set(id, value);
+    return value;
+  };
   switch (tag) {
     case 'undef': return undefined;
     case 'NaN':   return NaN;
     case 'Inf':   return Infinity;
     case '-Inf':  return -Infinity;
     case '-0':    return -0;
-    case 'BigInt': return BigInt(v.v);
-    case 'Sym':   return Symbol.for(v.v);
-    case 'Date':  return v.v == null ? new Date(NaN) : new Date(v.v);
+    case 'BigInt': return reg(BigInt(v.v));
+    case 'Sym':   return reg(Symbol.for(v.v));
+    case 'Date':  return reg(v.v == null ? new Date(NaN) : new Date(v.v));
     case 'Error': {
       const e = new Error(v.v.message);
       e.name = v.v.name;
@@ -365,16 +376,17 @@ function decodeTagged(v, tag, ctx) {
     case 'Blob': {
       if (typeof Blob === 'undefined') throw new TypeError('Blob is not available in this environment.');
       const bytes = b64ToBytes(v.v);
-      return new Blob([bytes], { type: v.t || '' });
+      return reg(new Blob([bytes], { type: v.t || '' }));
     }
     case 'File': {
       if (typeof File === 'undefined') throw new TypeError('File is not available in this environment.');
       const bytes = b64ToBytes(v.v);
-      return new File([bytes], v.n, { type: v.t || '', lastModified: v.m });
+      return reg(new File([bytes], v.n, { type: v.t || '', lastModified: v.m }));
     }
     case 'FD': {
       if (typeof FormData === 'undefined') throw new TypeError('FormData is not available in this environment.');
       const fd = new FormData();
+      reg(fd);
       for (const [k, val] of v.v) {
         const decoded = decode(val, ctx);
         fd.append(k, decoded);
@@ -385,17 +397,17 @@ function decodeTagged(v, tag, ctx) {
       // Typed arrays + binary buffers
       if (tag === 'buf') {
         const bytes = b64ToBytes(v.v);
-        return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+        return reg(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength));
       }
       if (tag === 'dv') {
         const bytes = b64ToBytes(v.v);
-        return new DataView(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength));
+        return reg(new DataView(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength)));
       }
       const Ctor = TAG_TO_TYPED_ARRAY[tag];
       if (Ctor) {
         const bytes = b64ToBytes(v.v);
         const sliced = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
-        return new Ctor(sliced);
+        return reg(new Ctor(sliced));
       }
       throw new TypeError(`Unknown serialization tag: ${tag}`);
     }