@webjsdev/core 0.7.48 → 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
@@ -400,12 +385,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)}"`;
@@ -480,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
@@ -1032,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
@@ -1276,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
@@ -1647,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));
   }
 }
 
@@ -1698,39 +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 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; }
-    } 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));
   }
 }
 
@@ -1739,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,
@@ -1756,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);
 }
 
 /**
@@ -1788,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
@@ -1978,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/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/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

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 {}