@webjsdev/core 0.7.49 → 0.7.50

package/src/render-client.js

@@ -750,11 +750,10 @@ function buildFormActionRecord(el, onEl, parts) {
  * record.
  *
  * FORMS FIRST, submitters second, regardless of the order the records were
- * collected in. A submitter asks whether its enclosing form is bound, and the
- * cheapest true answer is the identity field the form's own reconcile just
- * inserted. Document order gets this right for a form and a button in the SAME
- * template, but not for a `<form>` whose submitter arrives through a nested
- * template, so the ordering is made explicit rather than relied upon.
+ * collected in. Nothing reads an enclosing form's boundness any more (#1307
+ * made a bound submitter self-sufficient), but the ordering still makes a
+ * form's RELEASE run before its submitters reconcile, so it is kept rather
+ * than churned. See the note in the body.
  *
  * @param {FormActionRecord[] | null} formActions
  * @param {BoundPart[]} bound

package/src/render-server.js

@@ -16,6 +16,8 @@ import { isSuspense } from './suspense.js';
 import { unsafeHTML, isUnsafeHTML, isLive, isKeyed, isGuard, isTemplateContent, isRef, isCache, isUntil, isAsyncAppend, isAsyncReplace, isWatch } from './directives.js';
 import { stringify, parse } from './serialize.js';
 import { cspNonce } from './csp-nonce.js';
+import { readAttributeValue, resolveAttributeProperty } from './attribute-reader.js';
+import NAMED_ENTITIES, { LEGACY_NAMES } from './html-entities.js';
 
 /**
  * Render a TemplateResult (or any renderable value) to an HTML string.
@@ -180,23 +182,6 @@ async function renderTemplate(tr, ctx) {
   let pendingPropAttrs = [];
   /** @type {string[]} */
   let pendingSubmitterProps = [];
-  // Whether the tag stream is currently inside a form that BOUND an action
-  // (#1207), as THIS scan can see it. Three states, and the third is the point:
-  //   'bound'   an enclosing <form> opened here and bound an action
-  //   'unbound' an enclosing <form> opened here and bound nothing
-  //   'none'    there is conclusively no enclosing <form>
-  //   'unknown' there may be one, but this scan cannot see it
-  //
-  // The last two look alike and must not be merged, which is what a boolean did.
-  // A component's template is rendered by a SEPARATE pass (`injectDSD` calls
-  // `render` on it), so a `<button formaction=${fn}>` inside a component inside
-  // a bound form read as "no form", was refused, and in production vanished
-  // from a page that still returned 200. That pass now says 'unknown' and the
-  // boundness question is skipped, exactly as the client skips it when it
-  // cannot reach the form, so both renderers are best effort in the same place
-  // and for the same reason. A top-level scan that simply contains no form
-  // stays 'none' and is still refused, because there the answer IS known.
-  //
   let isCloseTag = false;
 
   // A bound `action=${fn}` is committed at its hole, but the edits it implies
@@ -483,14 +468,13 @@ async function renderTemplate(tr, ctx) {
             // #1207: the submitter binding. The identity replaces the
             // `formaction=` hole IN PLACE with the button's own name/value
             // pair, the one channel a browser submits for the pressed button
-            // alone. No `formaction` url is emitted, so the submission still
-            // targets the page and the form-level identity is simply overridden
-            // by this later entry.
+            // alone. No `formaction` url is emitted, so the submission targets
+            // whatever the FORM targets, and a form-level identity is simply
+            // overridden by this later entry.
             //
             // Refused here rather than at the `>` only where the answer cannot
-            // change later: boundness of the ENCLOSING form is already decided
-            // (its start tag is emitted), and an attribute written BEFORE the
-            // hole is already in `out`. Everything else waits for the close,
+            // change later: an attribute written BEFORE the hole is already in
+            // `out`. Everything else waits for the close,
             // where `assertSubmitterStartTag` sees the whole tag.
             // A second binding hole on this same tag, refused here so the
             // author gets the duplicate message rather than a confusing
@@ -1035,14 +1019,12 @@ async function injectDSD(html, ctx, ancestors = [], dev) {
       // Render the template to HTML. injectDSD recurses on the result so
       // nested custom elements (e.g. <theme-toggle> inside <blog-shell>)
       // get their own DSD pass.
-      // 'unknown' for the form scope (#1207): this is a SEPARATE render pass
-      // over one component's own template, driven by walking the already-emitted
-      // HTML, so it has no idea whether the host tag sits inside a bound
-      // `<form>`. Passing the default 'none' claimed there was no form at all,
-      // which refused a perfectly good `<button formaction=${fn}>` in a
-      // component inside a bound form and, because component SSR errors are
-      // isolated, made the button vanish from a page that still returned 200.
-      const rawInner = await render(tpl, ctx, 'unknown');
+      // This is a SEPARATE render pass over one component's own template,
+      // driven by walking the already-emitted HTML, so it has no idea whether
+      // the host tag sits inside a `<form>`. It does not need to: a bound
+      // submitter carries its whole submission (#1307), so nothing here asks
+      // about an enclosing form.
+      const rawInner = await render(tpl, ctx);
 
       if (isShadow) {
         // Shadow DOM: native <slot> stays as-is in the DSD template. The
@@ -1279,7 +1261,7 @@ async function processSuspenseElements(html, ctx, ancestors = [], dev) {
     result += rest.slice(0, openStart);
     const attrs = m[1] || '';
     const fbMatch = /data-webjs-fallback="([^"]*)"/i.exec(attrs);
-    const fallbackHtml = fbMatch ? unescapeAttr(fbMatch[1]) : '';
+    const fallbackHtml = fbMatch ? decodeAttrEntities(fbMatch[1]) : '';
 
     // Pass the FULL-input ranges shifted into `rest` coordinates rather than
     // letting the helper re-tokenize the suffix. `rest` can begin mid-comment
@@ -1650,7 +1632,7 @@ function parseAttrs(attrStr) {
 function seedServerAttrs(instance, attrs) {
   if (!instance || typeof instance.setAttribute !== 'function') return;
   for (const [name, raw] of Object.entries(attrs)) {
-    instance.setAttribute(name, unescapeAttr(raw));
+    instance.setAttribute(name, decodeAttrEntities(raw));
   }
 }
 
@@ -1701,67 +1683,41 @@ function appendReflectedAttrs(opening, instance, presentAttrNames) {
  * based on its static `properties` declaration.
  */
 function applyAttrsToInstance(instance, attrs, Cls) {
-  const props = Cls.properties || {};
-  for (const [key, raw] of Object.entries(attrs)) {
-    // Resolve the source attribute name to its property: a custom `attribute`
-    // option wins, else the kebab-cased property name, else the camelCase of
-    // the attribute (the common case). Mirrors the client attributeChangedCallback
-    // so a custom-attribute prop gets the right value in the SSR'd first paint.
-    let propName, rawDef;
-    for (const [k, decl] of Object.entries(props)) {
-      const d = typeof decl === 'object' ? decl : { type: decl };
-      if ((d.attribute || hyphenate(k)) === key) { propName = k; rawDef = decl; break; }
-    }
-    if (rawDef === undefined) {
-      rawDef = props[key] || props[camelCase(key)];
-      propName = props[key] ? key : camelCase(key);
-    }
-    if (!rawDef) {
-      instance[propName] = raw;
-      continue;
-    }
-    // The factory accepts a bare constructor shorthand (`{ expanded: Boolean }`)
-    // alongside the long form (`{ expanded: { type: Boolean } }`); normalize so
-    // the type-based coercion below sees a `{ type }` object either way.
-    const def = typeof rawDef === 'object' ? rawDef : { type: rawDef };
-    if (def.type === Number) instance[propName] = Number(raw);
-    else if (def.type === Boolean) instance[propName] = raw !== 'false';
-    else if (def.type === Object || def.type === Array) {
-      // `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 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;
+  for (const [sourceName, sourceValue] of Object.entries(attrs)) {
+    // The browser LOWERCASES every attribute name while parsing an HTML
+    // document, so `cfgData="x"` reaches the client reader as `cfgdata` and a
+    // camelCase name can never match anything in `observedAttributes`.
+    // Resolving the source case here made SSR read a name the platform cannot
+    // deliver, which is the divergence, not the fix (#1341).
+    const resolved = resolveAttributeProperty(Cls, sourceName.toLowerCase());
+    // An attribute mapping to no attribute-backed property is IGNORED, exactly
+    // as `attributeChangedCallback` ignores it and as lit's reader does. This
+    // used to assign it as an instance property (`instance[propName] = raw`),
+    // which no browser upgrade ever reproduces, and which on a real
+    // HTMLElement could mutate DOM state through `id` / `hidden` / `slot`.
+    // `seedServerAttrs` has already applied every source attribute properly,
+    // so nothing needs the copy (#1341).
+    if (resolved === undefined) continue;
+    const { propName, def } = resolved;
+    // A browser decodes every character reference BEFORE any reader sees the
+    // value, so decode once here, for every branch, and hand the shared reader
+    // an already-decoded string exactly as the DOM hands the client one. It
+    // used to be a `decode` argument the reader applied on the JSON and
+    // converter branches alone, which left a `String`-typed prop holding the
+    // raw source text while `getAttribute()` on the client returned the decoded
+    // one (#1341).
+    //
+    // One reader for both sides (#1340): `readAttributeValue` in
+    // `attribute-reader.js` is the same function `attributeChangedCallback` in
+    // `component.js` calls, so a custom `converter.fromAttribute` runs here
+    // too, ahead of type coercion, and the #1253 unparseable-JSON fallback is
+    // shared rather than mirrored.
+    //
+    // A converter that THROWS is not caught here. It lands in the
+    // per-component error isolation below, which is deliberate: an author who
+    // supplies a converter owns the read, the same rule `_reflectAttribute`
+    // states for `toAttribute`. See the comment on `readAttributeValue`.
+    instance[propName] = readAttributeValue(def, decodeAttrEntities(sourceValue));
   }
 }
 
@@ -1770,11 +1726,6 @@ function camelCase(s) {
   return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
 }
 
-/** Kebab-case a property name for its default HTML attribute (matches component.js). @param {string} s */
-function hyphenate(s) {
-  return s.replace(/([A-Z])/g, '-$1').toLowerCase();
-}
-
 /**
  * Inverse of camelCase. `userName` -> `user-name`, `userID` -> `user-i-d`.
  * Used to serialize property-binding names into HTML attribute names,
@@ -1787,20 +1738,142 @@ function kebabCase(s) {
   return s.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
 }
 
+/** windows-1252 mappings the HTML tokenizer applies to the C1 range. */
+const C1_REPLACEMENTS = {
+  0x80: 0x20ac, 0x82: 0x201a, 0x83: 0x0192, 0x84: 0x201e, 0x85: 0x2026,
+  0x86: 0x2020, 0x87: 0x2021, 0x88: 0x02c6, 0x89: 0x2030, 0x8a: 0x0160,
+  0x8b: 0x2039, 0x8c: 0x0152, 0x8e: 0x017d, 0x91: 0x2018, 0x92: 0x2019,
+  0x93: 0x201c, 0x94: 0x201d, 0x95: 0x2022, 0x96: 0x2013, 0x97: 0x2014,
+  0x98: 0x02dc, 0x99: 0x2122, 0x9a: 0x0161, 0x9b: 0x203a, 0x9c: 0x0153,
+  0x9e: 0x017e, 0x9f: 0x0178,
+};
+
+// The trailing `;` is OPTIONAL on the named arm, because a browser decodes a
+// legacy semicolon-less reference too. The callback decides which of the two
+// forms it has; see `decodeNamed`.
+const CHAR_REF = /&(?:#(\d+);?|#[xX]([0-9a-fA-F]+);?|([a-zA-Z][a-zA-Z0-9]*)(;?))/g;
+
+// A Map, not the imported object, so a name that collides with something on
+// `Object.prototype` misses instead of returning a function. See `decodeNamed`.
+const NAMED = new Map(Object.entries(NAMED_ENTITIES));
+const LEGACY = new Set(LEGACY_NAMES);
+
 /**
- * Reverse `escapeAttr` on a server-side attribute value. Needed
- * because `parseAttrs` returns the literal characters between the
- * quote marks; HTML entities are not decoded by the regex. The
- * browser handles this automatically, so client-side reads via
- * `getAttribute()` do not need the same step.
+ * Decode HTML character references in an attribute value.
+ *
+ * `parseAttrs` hands back the literal characters between the quote marks, so
+ * nothing has decoded them yet, while a browser decodes EVERY reference before
+ * any reader sees the value. This closes that gap (#1341): the full WHATWG
+ * named table plus decimal and hexadecimal numeric references, with the
+ * tokenizer's own numeric fix-ups (null, a surrogate, and anything past
+ * U+10FFFF become U+FFFD; the C1 range maps through windows-1252). It replaced
+ * a three-entity `unescapeAttr`, which left a `String`-typed prop undecoded
+ * entirely and turned `&lt;script&gt;` into the half-decoded `<script&gt;`.
+ *
+ * SINGLE PASS on purpose. A replacement is never rescanned, so `&amp;lt;`
+ * decodes to the literal `&lt;` and never to `<`. The old function got that
+ * from replacing `&amp;` last, which does not generalise past three entities.
+ *
+ * The 106 legacy semicolon-LESS names are covered too, because a browser really
+ * does decode them and measurably: Chromium, Firefox, and WebKit all hand a
+ * reader U+00A0 for `s="&nbsp"`. Leaving them literal would have been a value
+ * divergence of exactly the kind this function exists to remove, not a
+ * harmless non-goal. The rule that governs them, in an ATTRIBUTE value, is a
+ * one-character LOOKAHEAD rather than deep tokenizer state, which is why it is
+ * implementable here. `decodeNamed` carries the rule and the reason it takes
+ * the shape it does; the short version is that `&nbsp` at the end of a value
+ * decodes while `&nbspx`, `&nbsp=x`, and `&notin` stay literal, all three
+ * verified against the three engines.
+ *
+ * The same function also decodes `data-webjs-fallback`, which is MARKUP, where
+ * the tokenizer applies no such carve-out. Using the attribute rule there is
+ * deliberate and strictly conservative: that payload is written by
+ * `escapeAttr`, which emits only `&amp;` / `&quot;` / `&lt;`, so every
+ * reference in it is semicolon-terminated and never reaches this path.
  *
  * @param {string} s
+ * @returns {string}
+ */
+function decodeAttrEntities(s) {
+  // Load bearing, not a micro-optimisation: skipping the scan for the common
+  // no-`&` value is what makes this cheaper per attribute than the three
+  // chained `replace` calls it replaced, which paid for three passes always.
+  if (s.indexOf('&') === -1) return s;
+  return s.replace(CHAR_REF, (match, dec, hex, name, semi, offset) => {
+    if (dec !== undefined) return fromCodePoint(parseInt(dec, 10));
+    if (hex !== undefined) return fromCodePoint(parseInt(hex, 16));
+    return decodeNamed(match, name, semi === ';', s[offset + match.length]);
+  });
+}
+
+/**
+ * Resolve one named reference, semicolon-terminated or legacy.
+ *
+ * The table is read through a `Map` rather than by indexing the imported
+ * object. An object-literal lookup resolves through `Object.prototype`, so
+ * `&constructor;` / `&toString;` / `&hasOwnProperty;` and four more returned a
+ * FUNCTION instead of `undefined` and threw on the spread in
+ * `codePointsToString`, a path `seedServerAttrs` reaches for every attribute of
+ * every custom element, which rendered the whole component as an SSR error box.
+ * A browser leaves those literal, since they are not named references, so the
+ * throw was a divergence of exactly the kind this file exists to remove. A
+ * `Map` has no prototype chain to fall through, which closes the shape rather
+ * than guarding one call site.
+ *
+ * WHY THERE IS NO LONGEST-PREFIX LOOP. The tokenizer consumes the longest name
+ * in the table, so `&notin` is `&not` followed by `in`. Here that always
+ * collapses to the whole name: `CHAR_REF` captures `[a-zA-Z][a-zA-Z0-9]*`, so a
+ * prefix SHORTER than the name is by construction followed by an ASCII
+ * alphanumeric, which is precisely when the attribute carve-out declines to
+ * decode. A loop over shorter prefixes could therefore only ever return
+ * `match`, which is what falling through to the end already does. `&notin`
+ * stays literal either way, verified against the three engines, though note it
+ * gets there by not being a legacy name rather than by the carve-out.
+ *
+ * That same greediness means an ASCII alphanumeric character can never follow
+ * the match: whatever follows is by construction not `[a-zA-Z0-9]`, or the
+ * capture would have eaten it. So only the `=` check is needed for the
+ * attribute carve-out. `&nbspx` is literal because `nbspx` is not a legacy
+ * name, NOT because of the lookahead; `&nbsp=x` is the shape the lookahead
+ * actually decides.
+ *
+ * @param {string} match  the whole matched reference, returned unchanged when nothing decodes
+ * @param {string} name   the name, with no `&` and no `;`
+ * @param {boolean} hadSemi
+ * @param {string|undefined} nextChar  the character after the match, if any
+ * @returns {string}
+ */
+function decodeNamed(match, name, hadSemi, nextChar) {
+  if (hadSemi) {
+    const cp = NAMED.get(name);
+    return cp === undefined ? match : codePointsToString(cp);
+  }
+  if (!LEGACY.has(name)) return match;
+  // The attribute carve-out: a legacy name decodes only when what follows is
+  // neither `=` nor an ASCII alphanumeric. Nothing following at all (the end of
+  // the value) decodes, which is the common `s="&nbsp"` shape. Because CHAR_REF
+  // captures greedily, what follows is never an ASCII alphanumeric, so only `=`
+  // needs to be checked here.
+  if (nextChar === '=') return match;
+  // Every legacy name is in the table under the same name, asserted by a test
+  // rather than left to trust, so this cannot miss.
+  return codePointsToString(NAMED.get(name));
+}
+
+/** @param {number|number[]} cp */
+function codePointsToString(cp) {
+  return typeof cp === 'number' ? String.fromCodePoint(cp) : String.fromCodePoint(...cp);
+}
+
+/**
+ * The tokenizer's numeric character reference fix-ups.
+ * @param {number} n
+ * @returns {string}
  */
-function unescapeAttr(s) {
-  return s
-    .replace(/&lt;/g, '<')
-    .replace(/&quot;/g, '"')
-    .replace(/&amp;/g, '&');
+function fromCodePoint(n) {
+  if (n === 0 || n > 0x10ffff || (n >= 0xd800 && n <= 0xdfff)) return '\uFFFD';
+  if (C1_REPLACEMENTS[n] !== undefined) return String.fromCodePoint(C1_REPLACEMENTS[n]);
+  return String.fromCodePoint(n);
 }
 
 /**
@@ -1819,7 +1892,7 @@ function consumePropAttrs(attrs) {
     if (!key.startsWith('data-webjs-prop-')) continue;
     const propName = camelCase(key.slice('data-webjs-prop-'.length));
     try {
-      props[propName] = parse(unescapeAttr(attrs[key]));
+      props[propName] = parse(decodeAttrEntities(attrs[key]));
     } catch {
       // Malformed payload. Skip silently so the rest of the component
       // can still render. The client-side hydration will also try and
@@ -2009,8 +2082,6 @@ async function streamTemplate(tr, ctx, controller) {
   let pendingSubmitterProps = [];
   /** @type {string | null} */
   let pendingSubmitterTag = null;  // tag of a bound submitter, until it closes
-  // See the buffered machine: seeded from the caller so a nested template
-  // rendered into a bound form's children knows it is inside one.
   let isCloseTag = false;
 
   // See the buffered machine for why this runs at the `>` rather than at the

package/src/webjs-config.d.ts

@@ -10,8 +10,19 @@
  * This object is read key by key, mostly by the server and for a few keys
  * by the CLI. Without a type or schema a typo'd key (e.g. `redirect` for
  * `redirects`) was silently dropped and the feature stayed at its default
- * with no diagnostic. This type plus the published JSON Schema close that
- * gap.
+ * with no diagnostic. Three things close that gap now, at three different
+ * moments: this type while an agent or a human authors the block, the
+ * published JSON Schema in an editor via the scaffold's `.vscode` `$ref`,
+ * and `webjs-config-validate.js` at BOOT (#1300), which runs that same
+ * schema from `createRequestHandler` and warns once, naming every unknown
+ * top-level key, every bad `enum` value, and every wrong-typed `boolean` /
+ * `integer` (9 of the 17 keys). It does NOT type-check the other 8
+ * (`headers`, `redirects`, `basePath`, `allowedOrigins`, `csp`, `dev`,
+ * `start`, `doctor`), and it does not descend into a nested object, so a
+ * misspelling inside `dev` or `start` is not reported either. Whether
+ * anything else notices what this check passes over is up to the
+ * individual reader. The boot check warns and never throws, so a typo
+ * costs one feature its setting rather than the whole app its boot.
  *
  * LOCKSTEP: this file, the JSON Schema at
  * packages/server/webjs-config.schema.json, and the reader functions MUST