@webjsdev/core 0.7.48 → 0.7.49

package/index-browser.js

@@ -8,9 +8,10 @@
  * Stripped:
  *   - `renderToString`, `renderToStream` (server SSR pipeline; reach
  *     for `@webjsdev/core/server` if you need them in a Node test).
- *   - `setCspNonceProvider` (server-side wiring called by
- *     `@webjsdev/server`'s context module; `cspNonce()` stays
- *     because layouts can call it).
+ *   - `setCspNonceProvider`, `setAssetUrlProvider` and
+ *     `setFormActionResolver` (server-side wiring called by
+ *     `@webjsdev/server`; the reader halves stay, because a layout
+ *     can call `cspNonce()` / `asset()`).
  *
  * The framework's own SSR pipeline runs on Node and resolves the
  * package via the package.json `"default"` condition, which still
@@ -52,7 +53,14 @@ export {
 // the re-export still also evaluates the module, so the two are belt-and-
 // suspenders, not a double-enable (ESM evaluates once, enable is idempotent).
 import './src/router-client.js';
-export { enableClientRouter, disableClientRouter, navigate, revalidate } from './src/router-client.js';
+// `loadFrame` is here (and in `./index.js`, keeping the two symmetric) because
+// `@webjsdev/core/client-router`'s `default` condition points at THIS bundle, so
+// in dist mode the subpath resolves here while its published `types`
+// (`src/router-client.d.ts`) declare all five public router functions. Without
+// it, `import { loadFrame } from '@webjsdev/core/client-router'` type-checks,
+// works in dev (where the subpath maps to `src/router-client.js`) and is
+// `undefined` in production.
+export { enableClientRouter, disableClientRouter, navigate, revalidate, loadFrame } from './src/router-client.js';
 export { WebjsFrame } from './src/webjs-frame.js';
 export { WebjsStream, renderStream } from './src/webjs-stream.js';
 

package/index.d.ts

@@ -81,7 +81,7 @@ export { repeat, isRepeat } from './src/repeat.js';
 export { Suspense, isSuspense } from './src/suspense.js';
 export { connectWS } from './src/websocket-client.js';
 export { richFetch } from './src/rich-fetch.js';
-export { enableClientRouter, disableClientRouter, revalidate } from './src/router-client.js';
+export { enableClientRouter, disableClientRouter, revalidate, loadFrame } from './src/router-client.js';
 
 // `navigate` is typed against the generated `Route` union (#258) rather than
 // the JSDoc `string`. Until an app runs `webjs types`, `Route` resolves to

package/index.js

@@ -28,7 +28,7 @@ export {
   stringify, parse,
   serialize, deserialize,
 } from './src/serialize.js';
-export { enableClientRouter, disableClientRouter, navigate, revalidate } from './src/router-client.js';
+export { enableClientRouter, disableClientRouter, navigate, revalidate, loadFrame } from './src/router-client.js';
 export { WebjsFrame } from './src/webjs-frame.js';
 export { WebjsStream, renderStream } from './src/webjs-stream.js';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/core",
-  "version": "0.7.48",
+  "version": "0.7.49",
   "type": "module",
   "description": "The runtime for WebJs, a full-stack JavaScript framework built on web components with server-side rendering and no build step. Ships the html and css template tags, the WebComponent base class, signals, directives, and the isomorphic renderers.",
   "types": "./index.d.ts",

package/src/component.js

@@ -157,6 +157,42 @@ function warnFunctionReflection(host, propName, attrName) {
   );
 }
 
+/**
+ * Warn that a value with no JSON representation was dropped rather than
+ * reflected (#1253).
+ *
+ * `JSON.stringify` throws for three reasons an app hits in practice: a cycle,
+ * a `BigInt`, and an author `toJSON()` that throws. All three mean the same
+ * thing here, that there is no string to put in the attribute, so all three
+ * get the same answer as a function does.
+ *
+ * The caught message IS included, unlike `warnFunctionReflection`, which
+ * withholds its value on purpose. A function's string form is its source,
+ * which is the leak that guard exists to prevent; `JSON.stringify`'s own
+ * message names the property path rather than a value, and the sibling
+ * `.prop=${val}` SSR drop in `render-server.js` already ends the same way.
+ *
+ * UNCONDITIONAL, for the reason recorded on `warnFunctionReflection` above: a
+ * `NODE_ENV` gate is folded to a constant by the dist build, which would make
+ * the SSR half unreachable in every published build, and the SSR half is where
+ * the component silently vanishes.
+ *
+ * @param {{ constructor: unknown, tagName?: string }} host
+ * @param {string} propName
+ * @param {string} attrName
+ * @param {string} [detail] the message `JSON.stringify` threw
+ */
+function warnUnserializableReflection(host, propName, attrName, detail) {
+  if (typeof console === 'undefined' || !console.warn) return;
+  const tag = tagOf(/** @type any */ (host.constructor)) || host.tagName?.toLowerCase() || 'unknown';
+  console.warn(
+    `[webjs] reflect:true property "${propName}" on <${tag}> holds a value `
+    + `JSON.stringify cannot serialize (a cycle, a BigInt, or a throwing `
+    + `toJSON), so it has no HTML attribute representation. Removing `
+    + `"${attrName}" instead. Detail: ${detail}`
+  );
+}
+
 /**
  * A minimal base for HTML Custom Elements that mirrors Lit's ergonomics
  * while staying JSDoc-only and no-build.
@@ -745,12 +781,40 @@ class WebComponentBase extends Base {
       } else if (value == null) {
         this.removeAttribute(attrName);
       } else if (decl.type === Object || decl.type === Array) {
+        // One rule about an unserializable reflected value, in two halves.
+        //
         // A JSON-typed prop CARRYING a function is safe and stays whole:
         // `JSON.stringify` drops a function to `null` in an array and omits
         // the key in an object, so `[1, 2, fn]` serializes to `[1,2,null]`
         // with no source and no data loss. Refusing here would discard the
         // `1` and the `2` on a path that never leaked.
-        this.setAttribute(attrName, JSON.stringify(value));
+        //
+        // A value `JSON.stringify` cannot serialize AT ALL is the other half
+        // (#1253): a cycle, a `BigInt`, or an author `toJSON()` that throws.
+        // The throw used to escape reflection entirely, so a property
+        // assignment threw from the setter, a client upgrade threw out of
+        // `connectedCallback` before the first render, and an SSR render was
+        // swallowed by per-component isolation, which surfaces an error box in
+        // dev and emits the component EMPTY at a 200 in PRODUCTION, where the
+        // cause is only in the server log. There is no string to put in the
+        // attribute, so the
+        // attribute goes, exactly as it does for a function. The `catch` IS
+        // the detection: `JSON.stringify` already walks the value, so its own
+        // failure covers all three causes, where a cycle-only pre-walk would
+        // miss the other two and pay a full traversal per reflection.
+        let serialized;
+        let serializable = true;
+        try {
+          serialized = JSON.stringify(value);
+        } catch (e) {
+          serializable = false;
+          this.removeAttribute(attrName);
+          warnUnserializableReflection(this, propName, attrName, e && e.message);
+        }
+        // Outside the `try` on purpose, so a genuine `setAttribute` failure
+        // (an invalid attribute name) still surfaces instead of being folded
+        // into the unserializable path.
+        if (serializable) this.setAttribute(attrName, serialized);
       } else if (carriesFunction(value)) {
         // The string fall-through is the one place a CARRIED function still
         // leaks. `String([fn])` is `Array.prototype.join`, which runs
@@ -1103,7 +1167,35 @@ class WebComponentBase extends Base {
     } else if (def.type === Boolean) {
       v = value != null && value !== 'false';
     } else if (def.type === Object || def.type === Array) {
-      try { v = value == null ? null : JSON.parse(value); } catch { v = value; }
+      // An attribute that is not parseable JSON yields `null` rather than the
+      // raw string (#1253), because a STRING is never a valid value for a
+      // property the author declared `Object` or `Array`, whatever put it
+      // there. lit's `defaultConverter.fromAttribute` lands on the same `null`,
+      // for the reason its own comment gives: an element does not complain
+      // about being mis-configured.
+      //
+      // `applyAttrsToInstance` in `render-server.js` is the SSR counterpart of
+      // THIS branch and yields `null` for the same input. They have to agree,
+      // or an element SSRs holding one value and re-renders holding another.
+      // The agreement is about an attribute that is PRESENT and unparseable;
+      // an attribute that was never there does not reach either reader, so
+      // such a prop simply keeps its constructor value.
+      //
+      // That agreement is about this FALLBACK, not a guarantee that the two
+      // readers see the same attributes in the first place. They reach an
+      // attribute by different routes (this one via `observedAttributes` and
+      // the browser's own name-lowercasing, the SSR one by walking the parsed
+      // source tag), and hand-written markup can land in the gaps between
+      // those routes, so an author literal can still be read by one and not
+      // the other. Those gaps predate #1253 and it neither causes nor closes
+      // any of them; no attempt is made here to enumerate them, because every
+      // attempt so far has been incomplete.
+      //
+      // Scoped to the default converter. A prop supplying its own
+      // `converter.fromAttribute` is handled by the arm above and the SSR
+      // reader has no converter arm at all, so the two sides already read such
+      // a prop differently. That gap predates #1253 and is left alone.
+      try { v = value == null ? null : JSON.parse(value); } catch { v = null; }
     } else {
       v = value;
     }

package/src/render-server.js

@@ -400,12 +400,15 @@ 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.
+          // `<webjs-suspense .fallback=${html`...`}>` (#471). This element is
+          // defined only in the browser, so the injectDSD walk skips it
+          // (`lookup(tag)` finds no class) and no server-side instance runs
+          // consumePropAttrs. A normal data-webjs-prop-* binding would then
+          // land at connectedCallback, 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. (The value itself would serialize
+          // fine: a TemplateResult is a plain {strings, values} object.)
           if (currentTag === 'webjs-suspense' && name === 'fallback') {
             const fbHtml = await render(val, ctx);
             out += `data-webjs-fallback="${escapeAttr(fbHtml)}"`;
@@ -1727,9 +1730,37 @@ function applyAttrsToInstance(instance, attrs, Cls) {
       // `raw` is the entity-encoded attribute text (parseAttrs returns the
       // literal characters between the quotes), so decode the HTML entities
       // before JSON.parse. A JSON attribute carries `&quot;` for every `"`;
-      // parsing it raw throws and would silently fall back to the string,
-      // leaving an Object/Array prop holding a string at SSR.
-      try { instance[propName] = JSON.parse(unescapeAttr(raw)); } catch { instance[propName] = raw; }
+      // parsing it raw throws, and the prop then falls to the failure value
+      // below rather than to the object the author wrote.
+      //
+      // An unparseable attribute falls back to `null`, NOT to the raw string
+      // (#1253), matching this branch's counterpart in
+      // `attributeChangedCallback`. They have to agree, or the same
+      // `<my-el cfg="oops">` SSRs holding a string and re-renders holding
+      // something else the moment the element upgrades. `null` is the right
+      // value to agree on: a string is never a valid value for a property the
+      // author declared `Object` or `Array`. This function iterates the
+      // attributes PRESENT on the source tag, so an absent one is not read here
+      // at all and its property keeps whatever the constructor gave it; the
+      // agreement being asserted is about a present, unparseable attribute.
+      //
+      // That agreement is about this FALLBACK, not a guarantee that the two
+      // readers see the same attributes in the first place. This function
+      // walks the parsed source tag while the client goes through
+      // `observedAttributes` and the browser's own name-lowercasing, and
+      // hand-written markup can land in the gaps between those routes (the
+      // entity decoding just below is one, since it reverses far less than a
+      // browser does). Those gaps predate #1253 and it neither causes nor
+      // closes any of them; no attempt is made here to enumerate them,
+      // because every attempt so far has been incomplete.
+      //
+      // Scoped to the DEFAULT converter, which is all this branch is. The
+      // client reader tries `converter.fromAttribute` FIRST and only falls
+      // through to here when there is none, while this function has no
+      // converter arm at all, so a prop declaring one is read differently by
+      // the two sides regardless of what this line does. That gap predates
+      // #1253 and is left alone rather than widened.
+      try { instance[propName] = JSON.parse(unescapeAttr(raw)); } catch { instance[propName] = null; }
     } else instance[propName] = raw;
   }
 }

package/src/router-client.js

@@ -859,9 +859,13 @@ function onSubmit(e) {
   const submitter = /** @type {HTMLElement | null} */ (e.submitter ?? null);
   if (submitter && submitter.hasAttribute('data-no-router')) return;
 
-  const target = (submitter && submitter.getAttribute('formtarget'))
-    || form.getAttribute('target')
-    || '';
+  // Presence, not truthiness, exactly as `getSubmitAction` resolves the action
+  // (#1322). The form-submission algorithm asks whether the submitter HAS a
+  // `formtarget`, so a present-but-empty one overrides the form and then means
+  // the current browsing context, per the rules for choosing a navigable.
+  const target = (submitter && submitter.hasAttribute('formtarget'))
+    ? (submitter.getAttribute('formtarget') || '')
+    : (form.getAttribute('target') || '');
   if (target && target !== '_self') return;
 
   const method = getSubmitMethod(form, submitter);
@@ -911,14 +915,21 @@ function onSubmit(e) {
  * Method resolution: submitter's `formmethod` wins over form's `method`.
  * Returns lowercase.
  *
+ * Resolved on PRESENCE, not truthiness (#1322), the same way `getSubmitAction`
+ * below resolves the action. The form-submission algorithm reads the
+ * submitter's `formmethod` if the submitter HAS one, so a present-but-empty
+ * `formmethod=""` overrides the form and then falls to its own invalid-value
+ * default, GET. Resolving with `||` instead sent a multipart POST for a button
+ * every engine submits as `GET`, which is a JS-on versus JS-off divergence.
+ *
  * @param {HTMLFormElement} form
  * @param {HTMLElement | null} submitter
  */
 function getSubmitMethod(form, submitter) {
-  const v = (submitter && submitter.getAttribute('formmethod'))
-    || form.getAttribute('method')
-    || 'get';
-  return v.toLowerCase();
+  const v = (submitter && submitter.hasAttribute('formmethod'))
+    ? (submitter.getAttribute('formmethod') || '')
+    : (form.getAttribute('method') || '');
+  return (v || 'get').toLowerCase();
 }
 
 /**
@@ -965,12 +976,19 @@ function normalizeEnctype(raw) {
  * `enctype`, exactly as `getSubmitMethod` resolves the method (#1307). Turbo
  * resolves it the same way, in `core/drive/form_submission.js`.
  *
+ * On PRESENCE, not truthiness (#1322), for the reason spelled out on
+ * `getSubmitMethod`: a present-but-empty `formenctype=""` overrides the form
+ * and normalizes to urlencoded, its own invalid-value default, so a button on
+ * a multipart form sends urlencoded with JS on exactly as it does with JS off.
+ *
  * @param {HTMLFormElement} form
  * @param {HTMLElement | null} submitter
  */
 function getSubmitEnctype(form, submitter) {
   return normalizeEnctype(
-    (submitter && submitter.getAttribute('formenctype')) || form.getAttribute('enctype'),
+    (submitter && submitter.hasAttribute('formenctype'))
+      ? submitter.getAttribute('formenctype')
+      : form.getAttribute('enctype'),
   );
 }
 
@@ -1537,7 +1555,7 @@ function setNavigating(on) {
  * @returns {Map<string, { routeKey: string, start: Comment, end: Comment }> | null}
  *   The boundary map, or null when the tree's boundaries are malformed.
  */
-export function collectBoundaries(root) {
+function collectBoundaries(root) {
   /** @type {Map<string, { routeKey: string, start: Comment, end: Comment }>} */
   const out = new Map();
   /** @type {{ segment: string, routeKey: string, start: Comment }[]} */
@@ -1654,7 +1672,7 @@ export function collectBoundaries(root) {
  *   live: { routeKey: string, start: Comment, end: Comment },
  *   incoming: { routeKey: string, start: Comment, end: Comment } } | null}
  */
-export function planBoundarySwap(here, there) {
+function planBoundarySwap(here, there) {
   // Shared segments, shallowest first (a nested path prefix is shorter).
   const shared = [...here.keys()].filter((s) => there.has(s)).sort((a, b) => a.length - b.length);
   if (shared.length === 0) return null;

package/src/websocket-client.js

@@ -81,7 +81,8 @@ export function connectWS(url, opts = {}) {
 
   return {
     /** Send a message. Objects are JSON-stringified; strings and binary pass through.
-     *  If the socket isn't open yet, the message is queued until it is. */
+     *  If the socket isn't open yet, the message is queued until it is.
+     *  @param {string | ArrayBuffer | ArrayBufferView | object} data */
     send(data) {
       const payload =
         typeof data === 'string' || data instanceof ArrayBuffer || ArrayBuffer.isView(data)
@@ -90,7 +91,9 @@ export function connectWS(url, opts = {}) {
       if (ws && ws.readyState === WebSocket.OPEN) ws.send(/** @type any */ (payload));
       else queue.push(payload);
     },
-    /** Permanently close the socket. Disables reconnect. */
+    /** Permanently close the socket. Disables reconnect.
+     *  @param {number} [code]
+     *  @param {string} [reason] */
     close(code, reason) {
       stopped = true;
       try { ws?.close(code, reason); } catch {}