@webjsdev/core 0.7.48 → 0.7.50

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.50",
   "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/attribute-reader.js

@@ -0,0 +1,178 @@
+/**
+ * THE attribute reader, singular.
+ *
+ * `attributeChangedCallback` in `component.js` and `applyAttrsToInstance` in
+ * `render-server.js` are both thin callers of the two functions below, so the
+ * client and the SSR pass cannot drift on precedence, on a fallback, or on
+ * which attributes they read at all. They had drifted four ways before this
+ * module existed: the unparseable-JSON fallback (#1253), a missing converter
+ * arm (#1340), and three name-resolution gaps plus the entity decoding (#1341).
+ *
+ * The split between the two exports is the one place the sides legitimately
+ * differ. `resolveAttributeProperty` takes the name the PLATFORM would deliver,
+ * so the SSR caller lowercases its source name first and the client passes the
+ * browser's name straight through. Everything after that is common.
+ *
+ * WHY ITS OWN MODULE, rather than living beside the declaration semantics it
+ * interprets in `component.js`. That was the first shape, and `component.d.ts`
+ * cannot carry the declaration for it: `index.d.ts` re-exports that overlay
+ * with a bare `export *`, so a value declared there joins the ROOT public type
+ * surface of `@webjsdev/core` while `index.js` exports no such runtime value.
+ * An app writing `import { readAttributeValue } from '@webjsdev/core'` would
+ * then type-check and crash at load, which is exactly the phantom the #1031
+ * guard in `test/types/dts-no-phantom-exports.test.mjs` exists to catch, and it
+ * caught this one. Re-exporting the function from `index.js` would silence the
+ * guard by making an internal framework seam app-facing API, which is the wrong
+ * trade. A module with no `.d.ts` overlay keeps the seam internal and typed
+ * from its own JSDoc, which is how `escape.js` and `binding-prefixes.js`
+ * already work.
+ *
+ * It also drops an edge rather than adding one: `render-server.js` reaches the
+ * reader without importing `component.js` at all.
+ *
+ * lit solves the same problem structurally, though in the other direction.
+ * `@lit-labs/ssr`'s LitElementRenderer forwards its `attributeChangedCallback`
+ * into the element's own `_$attributeToProperty` through
+ * `lit-element/private-ssr-support.js`, so its server pass runs the browser's
+ * reader rather than a copy of it. lit can reach INTO the element because its
+ * elements are TypeScript with a generated declaration; WebJs ships buildless
+ * JS under a hand-written overlay, so the shared code moves out instead.
+ */
+
+/**
+ * Read one attribute string into its declared property value.
+ *
+ * The caller owns only the one platform-specific step, lowercasing the source
+ * name at SSR; `resolveAttributeProperty` below owns NAME resolution and
+ * declaration normalisation for both sides, and this function owns the value.
+ * The two callers used to reach an attribute by different routes and NOT see
+ * the same attribute set, which #1341 closed.
+ *
+ * @param {import('./component.js').PropertyDeclaration} def normalised declaration (`{ type, … }`)
+ * @param {string|null} value the attribute text
+ *
+ * BOTH callers hand in an already-decoded value, so no branch decodes anything
+ * (#1341). The client's came out of the DOM, which decodes every character
+ * reference before any reader sees it; the SSR caller runs `decodeAttrEntities`
+ * once at its own call site, ahead of this function, over EVERY branch rather
+ * than only the ones that parse. This used to be a third `decode` parameter
+ * applied to the JSON and converter branches alone, which left a `String`-typed
+ * prop holding the raw source text at SSR while `getAttribute()` on the client
+ * returned the decoded one.
+ * @returns {unknown}
+ */
+export function readAttributeValue(def, value) {
+  if (def.converter && def.converter.fromAttribute) {
+    // Deliberately UNGUARDED, and deliberately first (#1340). An author who
+    // supplies a converter owns the whole read, which is the same rule
+    // `_reflectAttribute` already states for `toAttribute`: its guards sit
+    // AFTER the converter branch because a custom converter is
+    // author-controlled. So a converter that throws throws, on both sides. At
+    // SSR that lands in per-component error isolation (render-server.js), which
+    // surfaces an error box in dev and an empty element at a 200 in prod with
+    // the cause in the server log; on the client it escapes
+    // attributeChangedCallback during upgrade. Catching on one side only would
+    // manufacture a fresh divergence (an SSR paint holding a fallback against a
+    // browser holding the constructor value), which is worse than both sides
+    // failing. lit propagates too (reactive-element `_$attributeToProperty`).
+    //
+    // A converter RETURN that SSR cannot serialise needs no guard here either.
+    // Unreflected it is only a property, and a function in a text hole renders
+    // as nothing. Reflected, the #1169 function guard and the #1253
+    // unserializable guard in `_reflectAttribute` already run on the SSR side
+    // and cover whatever the converter produced.
+    //
+    // The converter is handed DECODED text, which matters more here than
+    // anywhere: the documented reason to write one is a type the built-in
+    // converters cannot parse (Date, Map, Set), those parse their input, and
+    // `escapeAttr` encodes every `"` in an emitted attribute, so an encoded
+    // `{"a":1}` would throw inside the author's converter and (since
+    // the throw is deliberately uncaught) render an empty component at a 200.
+    // Both callers now decode before calling, so it gets the same text on both
+    // sides for hand-written markup as well as for anything WebJs emitted
+    // (#1341); this used to be a `decode` argument applied on this branch and
+    // the JSON one.
+    return def.converter.fromAttribute(value, def.type);
+  }
+  if (def.type === Number) return value == null ? null : Number(value);
+  if (def.type === Boolean) return value != null && value !== 'false';
+  if (def.type === Object || def.type === Array) {
+    // 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. Both readers reach this line, so they cannot disagree.
+    //
+    // An attribute that was never PRESENT does not reach either reader, so such
+    // a prop simply keeps its constructor value.
+    //
+    // The two readers now see the SAME attribute set, so this fallback is not
+    // the only thing they agree on (#1341). Both resolve a name through
+    // `resolveAttributeProperty` below, which matches the same
+    // `d.attribute || hyphenate(k)` expression `observedAttributes` maps over
+    // and nothing else, so it skips a `state: true` prop and ignores a name that
+    // maps to no attribute-backed property exactly as the observed list does.
+    // The SSR caller lowercases its source name first, because the browser
+    // lowercases while parsing. And both are handed a value with every
+    // character reference already decoded, legacy semicolon-less names included.
+    if (value == null) return null;
+    try { return JSON.parse(value); } catch { return null; }
+  }
+  return value;
+}
+
+/** Kebab-case a property name for its default HTML attribute. @param {string} s */
+function hyphenate(s) {
+  return s.replace(/([A-Z])/g, '-$1').toLowerCase();
+}
+
+/**
+ * Resolve an attribute NAME to the property it feeds, and to that property's
+ * normalised declaration.
+ *
+ * `state: true` props are skipped, because they are absent from
+ * `observedAttributes` and so the browser never delivers their attribute to any
+ * reader. lit reaches the same outcome the same way, resolving through the very
+ * map `observedAttributes` is built from (`reactive-element.ts`
+ * `_$attributeToProperty`).
+ *
+ * `attrName` must already be the name the PLATFORM would deliver. The browser
+ * lowercases attribute names while parsing, so the SSR caller lowercases its
+ * source name before calling and the client caller passes the browser's name
+ * through untouched. That one step is the only thing that differs between the
+ * two sides, which is why it lives in the callers and not here. A custom
+ * `attribute` option is matched VERBATIM, as lit matches it and as a browser
+ * would, so a camelCase custom attribute stays unreachable from markup rather
+ * than being reachable at SSR only. Lowercasing the DECLARED side would make
+ * SSR read MORE than a browser can deliver, which is the bug this function
+ * exists to remove, so do not add it.
+ *
+ * The match is EXACTLY `d.attribute || hyphenate(k)`, the same expression
+ * `observedAttributes` maps over, and nothing else. A `props[attrName] ||
+ * props[camelCase(attrName)]` fallback used to sit after the loop, so a prop
+ * declaring a custom attribute also answered to its PROPERTY name. Both readers
+ * carried that code, which read like an agreement and was not one: the browser
+ * only ever calls in with a name from `observedAttributes`, and that list holds
+ * the declared attribute alone, so the fallback was unreachable on the client
+ * and live on the server. Measured, `open: prop(Boolean, { attribute:
+ * 'is-open' })` with `<my-el open>` SSR'd `true` and upgraded to the
+ * constructor value. Deriving the match from the same expression the observed
+ * list is built from is what makes the two sides agree by construction rather
+ * than by two copies staying in step (#1341).
+ *
+ * @param {any} Cls  the component class
+ * @param {string} attrName
+ * @returns {{ propName: string, def: PropertyDeclaration } | undefined}
+ *   `undefined` when the attribute maps to no attribute-backed property, in
+ *   which case the caller must IGNORE the attribute entirely (#1341).
+ */
+export function resolveAttributeProperty(Cls, attrName) {
+  const props = (Cls && Cls.properties) || {};
+  for (const [k, decl] of Object.entries(props)) {
+    const d = typeof decl === 'object' && decl !== null ? decl : { type: decl };
+    if (d.state) continue;
+    if ((d.attribute || hyphenate(k)) === attrName) return { propName: k, def: d };
+  }
+  return undefined;
+}

package/src/component.d.ts

@@ -213,3 +213,13 @@ export declare function prop<T>(
 export declare function prop<T = string>(
   opts?: PropertyDeclaration<T>
 ): PropertyDeclaration<T>;
+
+// The shared attribute reader (`resolveAttributeProperty`, #1341) is NOT here,
+// and nothing about it belongs here. It lives in `src/attribute-reader.js`,
+// which has no `exports` entry, because two guards bracket every mapped entry
+// and `./component` is one: #388 forces every runtime named export of
+// `component.js` to be declared in this file, and #1031 forces every
+// declaration reachable from `index.d.ts` (which re-exports this file with
+// `export *`) to exist on `index.js` at runtime. Together they leave no way to
+// add an INTERNAL named export to `component.js`. That module's header carries
+// the full reasoning.

package/src/component.js

@@ -1,10 +1,12 @@
 import { render as clientRender } from './render-client.js';
+import { readAttributeValue } from './attribute-reader.js';
 import { setActiveActionSignal } from './action-abort-client.js';
 import { carriesFunction } from './form-action.js';
 import { isCSS, adoptStyles } from './css.js';
 import { register, tagOf } from './registry.js';
 import { parse as deserializeProp } from './serialize.js';
 import { Signal } from './signal.js';
+import { resolveAttributeProperty } from './attribute-reader.js';
 import {
   captureAuthoredChildren,
   adoptSSRAssignments,
@@ -85,7 +87,11 @@ const isBrowser = typeof window !== 'undefined' && typeof HTMLElement !== 'undef
  *
  * @property {{ fromAttribute: (value: string|null, type?: Function) => unknown, toAttribute: (value: unknown, type?: Function) => string|null }} [converter]
  *   Custom serialization/deserialization pair for the HTML attribute.
- *   `fromAttribute` is called in `attributeChangedCallback`;
+ *   `fromAttribute` is called by BOTH attribute readers through the shared
+ *   `readAttributeValue` in `attribute-reader.js`: the client
+ *   `attributeChangedCallback` and the SSR
+ *   `applyAttrsToInstance` in `render-server.js` (#1340). So it runs
+ *   server-side too, and must not touch browser globals.
  *   `toAttribute` is called when reflecting back to the attribute.
  *   If omitted, the built-in type-based coercion is used.
  */
@@ -100,6 +106,7 @@ function defaultHasChanged(a, b) {
   return a !== b;
 }
 
+
 /**
  * `String(v)` that cannot itself throw.
  *
@@ -157,6 +164,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 +788,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
@@ -1077,36 +1148,22 @@ class WebComponentBase extends Base {
     // resulting attributeChangedCallback to avoid infinite loops.
     if (this.__reflectingAttribute) return;
 
-    const Ctor = /** @type any */ (this.constructor);
-    const allProps = (Ctor.properties || {});
-    // Resolve the incoming attribute name to its property. A custom
-    // `attribute` option wins; otherwise the kebab-cased property name. Falls
-    // back to the camelCase of the attribute for the common (kebab) case.
-    let propName, raw;
-    for (const [k, decl] of Object.entries(allProps)) {
-      const d = typeof decl === 'object' ? decl : { type: decl };
-      if ((d.attribute || hyphenate(k)) === name) { propName = k; raw = decl; break; }
-    }
-    if (raw === undefined) { propName = camelCase(name); raw = allProps[propName] || allProps[name]; }
-    if (raw === undefined) return;
-    // A declaration is either a full descriptor (`{ type: Number, … }`) or the
-    // bare-constructor shorthand the factory accepts (`count: Number`), in which
-    // case the value IS the type. Normalise so type-based coercion fires either
-    // way (matches `_initializeProperties`).
-    const def = typeof raw === 'object' ? raw : { type: raw };
-
-    let v;
-    if (def.converter && def.converter.fromAttribute) {
-      v = def.converter.fromAttribute(value, def.type);
-    } else if (def.type === Number) {
-      v = value == null ? null : Number(value);
-    } 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; }
-    } else {
-      v = value;
-    }
+    // One name resolver for both sides (#1341). The browser only calls this for
+    // a name in `observedAttributes`, and it has already lowercased that name
+    // while parsing, so it passes straight through; the SSR caller lowercases
+    // its source name first. `resolveAttributeProperty` also normalises the
+    // declaration, so a bare-constructor shorthand (`count: Number`) and the
+    // long form (`{ type: Number, … }`) both arrive here as `{ type, … }`.
+    const resolved = resolveAttributeProperty(this.constructor, name);
+    if (resolved === undefined) return;
+    const { propName, def } = resolved;
+
+    // One reader for both sides, in `attribute-reader.js`: this and
+    // `applyAttrsToInstance` in `render-server.js` call the same function, so
+    // precedence and every fallback are shared rather than mirrored (#1340).
+    // It takes an already-decoded value, which the DOM has done here and
+    // `decodeAttrEntities` does at the SSR call site (#1341).
+    const v = readAttributeValue(def, value);
 
     if (this[propName] !== v) {
       this[propName] = v;