@webjsdev/core 0.7.64 → 0.8.0

package/src/directives.d.ts

@@ -96,3 +96,5 @@ export function asyncReplace<T>(
 export function isAsyncReplace(x: unknown): x is AsyncReplaceDirective;
 export function watch<T>(sig: { get(): T; __isSignal: true }): WatchDirective<T>;
 export function isWatch(x: unknown): x is WatchDirective;
+
+export { classMap, styleMap, ifDefined } from './attribute-directives.js';

package/src/directives.js

@@ -458,3 +458,5 @@ export function watch(sig) {
 export function isWatch(x) {
   return !!x && typeof x === 'object' && /** @type {any} */ (x)._$webjs === 'watch';
 }
+
+export { classMap, styleMap, ifDefined } from './attribute-directives.js';

package/src/escape.js

@@ -1,6 +1,14 @@
+// Both escapers skip the three replaces when the string carries none of the
+// characters they rewrite, which is the common case for a template value and
+// was measurable on the SSR hot path (#1646).
+const TEXT_SPECIAL = /[&<>]/;
+const ATTR_SPECIAL = /[&"<]/;
+
 /** @param {string} s */
 export function escapeText(s) {
-  return String(s)
+  const str = String(s);
+  if (!TEXT_SPECIAL.test(str)) return str;
+  return str
     .replace(/&/g, '&amp;')
     .replace(/</g, '&lt;')
     .replace(/>/g, '&gt;');
@@ -8,7 +16,9 @@ export function escapeText(s) {
 
 /** @param {string} s */
 export function escapeAttr(s) {
-  return String(s)
+  const str = String(s);
+  if (!ATTR_SPECIAL.test(str)) return str;
+  return str
     .replace(/&/g, '&amp;')
     .replace(/"/g, '&quot;')
     .replace(/</g, '&lt;');

package/src/form-action.js

@@ -87,10 +87,10 @@ import { escapeAttr } from './escape.js';
  * it looks like from any one file and are easy to change one at a time. That
  * is why the predicates live here rather than at each site.
  *
- * The second SSR machine (`streamTemplate`) is reached only through
- * `renderToStream(v, { ssr: false })`, which no page render uses: the server
- * renders every page, Suspense included, via `renderToString`. It is kept in
- * lockstep for the public API surface rather than for a live page.
+ * Since #1646 there is ONE SSR interpreter (`render-server/walk.js`), shared
+ * by the buffered page render and `renderToStream(v, { ssr: false })`, so the
+ * two can no longer drift; the predicates still live here because the CLIENT
+ * renderer applies the same rules.
  */
 
 /**
@@ -967,9 +967,9 @@ function ensureIdentityField(form, id) {
 /**
  * SSR: judge one submitter's emitted START TAG, at its `>`.
  *
- * Called from BOTH state machines so the rules cannot drift between them, which
- * is the failure #1154 already had once (a guard shipped in `renderTemplate`
- * and not in `streamTemplate`). Judged at the `>` rather than at the hole
+ * Called from the one SSR interpreter (`render-server/walk.js`, #1646); there
+ * used to be two hand-synchronised state machines, which is the failure #1154
+ * had once (a guard shipped in one and not the other). Judged at the `>` rather than at the hole
  * because every input is an attribute the author may have written AFTER the
  * binding.
  *

package/src/html.d.ts

@@ -2,8 +2,12 @@ export interface TemplateResult {
   _$webjs: 'template';
   strings: TemplateStringsArray | string[];
   values: unknown[];
+  /** Set by the `svg` tag: the client parses the strings inside an `<svg>` wrapper. */
+  svg?: boolean;
 }
 
 export function html(strings: TemplateStringsArray | string[], ...values: unknown[]): TemplateResult;
+/** lit's `svg` tag: a fragment parsed as SVG on the client, rendered like `html` on the server. */
+export function svg(strings: TemplateStringsArray | string[], ...values: unknown[]): TemplateResult;
 export function isTemplate(x: unknown): x is TemplateResult;
 export const MARKER: 'wjm-';

package/src/html.js

@@ -4,7 +4,7 @@
  * A TemplateResult is an isomorphic description of HTML: the static string
  * pieces plus the dynamic values. Server and client renderers both consume it.
  *
- * @typedef {{ _$webjs: 'template', strings: TemplateStringsArray | string[], values: unknown[] }} TemplateResult
+ * @typedef {{ _$webjs: 'template', strings: TemplateStringsArray | string[], values: unknown[], svg?: boolean }} TemplateResult
  *
  * @param {TemplateStringsArray | string[]} strings
  * @param {...unknown} values
@@ -14,6 +14,27 @@ export function html(strings, ...values) {
   return { _$webjs: 'template', strings, values };
 }
 
+/**
+ * Tagged template literal for an SVG FRAGMENT, lit's `svg` tag.
+ *
+ * Use it for markup that sits INSIDE an `<svg>` element but is built in its
+ * own template (a `<rect>` per data point, a `<path>` a helper returns).
+ * An `html` template is parsed as HTML on the client, so a `<rect>` there
+ * becomes an HTML element and never paints. An `svg` template is parsed
+ * inside an `<svg>` wrapper, so its elements are SVG elements. A whole
+ * `<svg>` element still belongs in `html`.
+ *
+ * The server renders it exactly like `html` (markup is text there), so the
+ * two differ only in how the client parses the static strings.
+ *
+ * @param {TemplateStringsArray | string[]} strings
+ * @param {...unknown} values
+ * @returns {TemplateResult}
+ */
+export function svg(strings, ...values) {
+  return { _$webjs: 'template', strings, values, svg: true };
+}
+
 /**
  * Identity check for TemplateResult.
  * @param {unknown} x

package/src/optimistic.js

@@ -44,7 +44,7 @@ class OptimisticState {
   }
 }
 
-async function runLegacyOptimistic(signal, value, action) {
+async function runImperativeOptimistic(signal, value, action) {
   const prev = signal.get();
   signal.set(value);
   let result;
@@ -105,7 +105,7 @@ async function runLegacyOptimistic(signal, value, action) {
  *   4. The returned `release()` fn removes the update by ID and re-renders.
  *   5. Concurrent updates stack; each release removes only its own entry.
  *
- * Backward-compatible imperative API (signal-based rollback):
+ * Imperative form (signal-based rollback), for a one-shot toggle:
  *   await optimistic(signal, value, () => likePost(postId));
  *
  * Client-only: it calls `host.requestUpdate()` (client work), so a component
@@ -119,7 +119,7 @@ async function runLegacyOptimistic(signal, value, action) {
  */
 export function optimistic(first, second, third) {
   if (first && typeof first.get === 'function' && typeof first.set === 'function') {
-    return runLegacyOptimistic(first, second, third);
+    return runImperativeOptimistic(first, second, third);
   }
   return new OptimisticState(first, second);
 }

package/src/registry.d.ts

@@ -15,3 +15,8 @@ export function lookupModuleUrl(tag: string): string | undefined;
 export function isLazy(tag: string): boolean;
 export function tagOf(cls: WebComponentInstanceConstructor): string | undefined;
 export function allTags(): string[];
+/**
+ * The registry's tag-set version: bumped on a first-time registration, so a
+ * memo keyed on it (the SSR scanner's tag regex) is valid while it is unchanged.
+ */
+export function registryVersion(): number;

package/src/registry.js

@@ -31,7 +31,7 @@
  *   user-app:  ThemeToggle.register('theme-toggle')   → instance-A registry
  *   server:    lookup('theme-toggle')                  → instance-B registry (empty)
  *
- * SSR's `injectDSD` would then skip the tag and emit bare
+ * The SSR walk's `lookup(tag)` would then find no class and emit bare
  * `<theme-toggle></theme-toggle>` even though the user registered it
  * correctly. Symptom: components render with no children server-side
  * and only "appear" after the browser hydrates.
@@ -50,6 +50,21 @@ const registry = _g[REGISTRY_KEY] || (_g[REGISTRY_KEY] = new Map());
 /** @type {WeakMap<Function, string>} */
 const classToTag = _g[CLASS_TO_TAG_KEY] || (_g[CLASS_TO_TAG_KEY] = new WeakMap());
 
+/**
+ * The registry's tag-set version (#1644): bumped whenever a NEW key enters
+ * the registry, by a class registration OR by `primeModuleUrl` (the prod
+ * component scan creates the entry before the class arrives), so the SSR
+ * scanner can memoize the regex it builds from every registered tag and
+ * rebuild it only when the set changed. Shared on
+ * `globalThis` like the registry itself, because under `bun --hot` the app
+ * imports a fresh copy of this module while the first run's server keeps
+ * rendering through the old one; a copy-local counter would leave that server
+ * blind to a tag the new copy registered.
+ * @type {{ v: number }}
+ */
+const REGISTRY_VERSION_KEY = Symbol.for('webjs:registryVersion');
+const version = _g[REGISTRY_VERSION_KEY] || (_g[REGISTRY_VERSION_KEY] = { v: 0 });
+
 const isBrowser =
   typeof window !== 'undefined' && typeof customElements !== 'undefined';
 
@@ -76,6 +91,8 @@ function registerInternal(tag, cls) {
     entry.lazy = lazy;
   } else {
     registry.set(tag, { cls, moduleUrl: null, lazy, tag });
+    // A new tag changes the set the SSR scanner matches on (#1644).
+    version.v += 1;
   }
   classToTag.set(cls, tag);
 }
@@ -126,9 +143,10 @@ if (!isBrowser) {
  * ------------------------------------------------------------------ */
 
 /**
- * @deprecated Low-level internal: prefer `customElements.define(tag, cls)`.
- * Kept as a minimal wrapper for back-compat with any framework code that
- * calls it directly.
+ * Register a component class under a tag. The primitive behind
+ * `Class.register('tag')` (the app-facing idiom): `customElements.define` in
+ * the browser, the SSR registry on the server. Reachable as
+ * `@webjsdev/core/registry` for framework tooling; apps use the static method.
  *
  * @param {string} tag
  * @param {typeof import('./component.js').WebComponent} cls
@@ -163,6 +181,10 @@ export function primeModuleUrl(tag, moduleUrl) {
     lazy: false,
     tag,
   });
+  // A primed tag is a new KEY, and `allTags()` lists keys: the SSR scanner's
+  // pattern must include it before its class arrives, or a pattern memoized
+  // while the registry was empty would stay empty for the process (#1644).
+  version.v += 1;
 }
 
 /** @param {string} tag */
@@ -188,3 +210,12 @@ export function tagOf(cls) {
 export function allTags() {
   return [...registry.keys()];
 }
+
+/**
+ * The current tag-set version: moves only when a tag is registered for the
+ * first time. A memo keyed on it is valid for as long as it is unchanged.
+ * @returns {number}
+ */
+export function registryVersion() {
+  return version.v;
+}

package/src/render-client/adopt-slots.js

@@ -0,0 +1,245 @@
+/**
+ * Hydration slot adoption: keep a light-DOM host's SSR-projected children in
+ * the document while its first client render replaces the SSR markup (#1666).
+ *
+ * Hydration renders the template from a fresh clone and swaps it in for the
+ * SSR markup. The projected children sit inside the SSR `<slot>`, so swapping
+ * the SSR tree out took them out of the document, and the first slot apply put
+ * them back a microtask later. A removal is not free: the HTML spec navigates
+ * a re-inserted iframe again (and `loading="lazy"` defers only the FIRST
+ * insertion, so a hidden lazy frame loads), and every nested custom element
+ * disconnects and reconnects.
+ *
+ * So for each of the template's own slots whose SSR counterpart holds exactly
+ * the nodes the host's record adopted, the SSR slot and its ancestor chain up
+ * to the host are KEPT: the parts that target a fresh element on that chain
+ * are pointed at its live twin, and the fresh siblings around the chain are
+ * inserted into the live elements instead of the live tree being replaced. No
+ * kept node moves, so the projected children never leave the document. The
+ * fresh slot's cloned fallback goes to the slot's holding fragment, where the
+ * slot part would have put it.
+ *
+ * Conservative by construction: a slot is adopted only when every link of
+ * both chains matches by tag, no link is a custom element (whose SSR markup is
+ * its own rendered template) or a `<form>` (form-action reconciliation inserts
+ * children into it), the slot's name is static, and the kept nodes sit in the
+ * same relative order on both sides. Anything else, a slot inside a
+ * conditional template among them, falls back to the plain swap.
+ *
+ * @module
+ */
+import {
+  PROJECTION_ACTUAL, PROJECTION_ATTR, SLOT_FALLBACK_FRAG, SLOT_OWNER_ATTR,
+  ensureSlotState, hasSlotState, keyOfName,
+} from '../slot.js';
+
+/**
+ * Live SSR slots a hydration render adopted. The slot part's finalize reads
+ * it to leave the slot's children (the projected nodes) in place instead of
+ * harvesting them as fallback, since the holding fragment is already set.
+ * @type {WeakSet<Element>}
+ */
+export const adoptedSlots = new WeakSet();
+
+/**
+ * @typedef {{ map: Map<Node, Element>, slots: [Element, Element][], chains: [Element, Element][] }} AdoptionPlan
+ */
+
+/**
+ * Plan the adoption for a hydration render, after the parts are bound and
+ * before any is applied. Returns null when no slot qualifies.
+ *
+ * @param {Element | DocumentFragment | ShadowRoot} container
+ * @param {DocumentFragment} frag the fresh clone
+ * @param {any[]} bound the template's bound parts
+ * @returns {AdoptionPlan | null}
+ */
+export function planSlotAdoption(container, frag, bound) {
+  if (/** @type {any} */ (container).nodeType !== 1 || !hasSlotState(/** @type {Element} */ (container))) return null;
+  const state = ensureSlotState(/** @type {Element} */ (container));
+  /** @type {Set<Element>} */
+  const dynamicName = new Set();
+  for (const p of bound) {
+    if ((p.kind === 'attr' || p.kind === 'attr-mixed' || p.kind === 'bool') && p.name === 'name') dynamicName.add(p.el);
+  }
+  /** @type {Map<Node, Element>} fresh element to its live twin */
+  const map = new Map();
+  /** @type {Set<Element>} */
+  const usedLive = new Set();
+  /** @type {[Element, Element][]} */
+  const slots = [];
+  /** @type {[Element, Element][]} */
+  const chains = [];
+  for (const p of bound) {
+    if (p.kind !== 'slot') continue;
+    const slotF = /** @type {Element} */ (p.slotEl);
+    if (dynamicName.has(slotF)) continue;
+    const assigned = state.assignedByName.get(keyOfName(slotF.getAttribute('name')));
+    if (!assigned || assigned.length === 0) continue;
+    const slotL = /** @type {Element | null} */ (assigned[0].parentNode);
+    if (!slotL || slotL.nodeType !== 1 || slotL.localName !== 'slot' || usedLive.has(slotL)) continue;
+    if (slotL.getAttribute(PROJECTION_ATTR) !== PROJECTION_ACTUAL) continue;
+    if (!sameNodes(slotL.childNodes, assigned)) continue;
+    const fChain = ancestorsUpTo(slotF, frag);
+    const lChain = ancestorsUpTo(slotL, container);
+    if (!fChain || !lChain || fChain.length !== lChain.length) continue;
+    let ok = true;
+    for (let i = 0; i < fChain.length && ok; i++) {
+      const f = fChain[i];
+      const l = lChain[i];
+      const name = f.localName;
+      if (name !== l.localName || name.includes('-') || name === 'form') ok = false;
+      else {
+        const prior = map.get(f);
+        if (prior ? prior !== l : usedLive.has(l)) ok = false;
+      }
+    }
+    if (!ok) continue;
+    map.set(slotF, slotL);
+    usedLive.add(slotL);
+    slots.push([slotF, slotL]);
+    for (let i = 0; i < fChain.length; i++) {
+      if (map.has(fChain[i])) continue;
+      map.set(fChain[i], lChain[i]);
+      usedLive.add(lChain[i]);
+      chains.push([fChain[i], lChain[i]]);
+    }
+  }
+  if (slots.length === 0) return null;
+  // No kept node may have to move: under each kept parent the kept children
+  // must already sit in the order the template puts them in.
+  for (const fParent of [frag, ...chains.map(([f]) => f)]) {
+    let last = null;
+    for (const child of fParent.childNodes) {
+      const live = map.get(child);
+      if (!live) continue;
+      if (last && !(last.compareDocumentPosition(live) & Node.DOCUMENT_POSITION_FOLLOWING)) return null;
+      last = live;
+    }
+  }
+  return { map, slots, chains };
+}
+
+/**
+ * Point every bound part that targets a kept fresh element at its live twin,
+ * and give each kept element the fresh one's static attributes. Runs before
+ * the parts apply, so every dynamic value lands on the live element directly.
+ *
+ * @param {AdoptionPlan} plan
+ * @param {any[]} bound
+ */
+export function retargetParts(plan, bound) {
+  /** @type {Map<Element, Set<string>>} attributes a part owns, per live element */
+  const owned = new Map();
+  for (const p of bound) {
+    if (p.kind === 'slot') {
+      const live = plan.map.get(p.slotEl);
+      if (live) p.slotEl = live;
+      continue;
+    }
+    if (!p.el) continue;
+    const live = plan.map.get(p.el);
+    if (!live) continue;
+    if (p.kind === 'event') {
+      p.el.removeEventListener(p.name, p.dispatcher);
+      live.addEventListener(p.name, p.dispatcher);
+    }
+    p.el = live;
+    if (p.kind === 'attr' || p.kind === 'attr-mixed' || p.kind === 'bool') {
+      let names = owned.get(live);
+      if (!names) owned.set(live, names = new Set());
+      names.add(p.name);
+    }
+  }
+  for (const [fresh, live] of [...plan.chains, ...plan.slots]) {
+    const isSlot = live.localName === 'slot';
+    const names = owned.get(live);
+    for (const a of Array.from(live.attributes)) {
+      if (fresh.hasAttribute(a.name) || names?.has(a.name)) continue;
+      // The SSR projection stamps stay: the slot IS projected, and the owner
+      // carrier is what isOwnSlot reads until the owner symbol is stamped.
+      if (isSlot && (a.name === PROJECTION_ATTR || a.name === SLOT_OWNER_ATTR)) continue;
+      live.removeAttribute(a.name);
+    }
+    for (const a of Array.from(fresh.attributes)) {
+      if (live.getAttribute(a.name) !== a.value) live.setAttribute(a.name, a.value);
+    }
+  }
+}
+
+/**
+ * Commit the fresh template into the container around the kept live nodes:
+ * every live child that is not kept is removed, every fresh node is inserted
+ * in template order, and no kept node moves. The fresh slots' cloned fallback
+ * goes to each kept slot's holding fragment.
+ *
+ * @param {AdoptionPlan} plan
+ * @param {Element} container
+ * @param {Node[]} top the container's new children, bookends included
+ */
+export function commitAdoption(plan, container, top) {
+  const mapped = (/** @type {Node} */ n) => plan.map.get(n) || n;
+  const state = ensureSlotState(container);
+  for (const [fresh, live] of plan.chains) mergeChildren(live, Array.from(fresh.childNodes, mapped));
+  mergeChildren(container, top.map(mapped));
+  for (const [fresh, live] of plan.slots) {
+    const fallback = document.createDocumentFragment();
+    while (fresh.firstChild) fallback.appendChild(fresh.firstChild);
+    /** @type {any} */ (live)[SLOT_FALLBACK_FRAG] = fallback;
+    adoptedSlots.add(live);
+    // Forget the adopted snapshot so the first apply reports the initial
+    // projection (one slotchange), exactly as the plain swap did.
+    state.lastSnapshot.delete(live);
+  }
+}
+
+/**
+ * Make `parent`'s children exactly `want`, removing what is not wanted and
+ * inserting the rest, without moving a node already in place in order.
+ *
+ * @param {Node} parent
+ * @param {Node[]} want
+ */
+function mergeChildren(parent, want) {
+  const keep = new Set(want);
+  for (const c of Array.from(parent.childNodes)) {
+    if (!keep.has(c)) parent.removeChild(c);
+  }
+  let cursor = parent.firstChild;
+  for (const node of want) {
+    if (node === cursor) {
+      cursor = cursor.nextSibling;
+      continue;
+    }
+    parent.insertBefore(node, cursor);
+  }
+}
+
+/**
+ * The element ancestors of `node` below `root`, nearest first, or null when
+ * `root` is not an ancestor.
+ *
+ * @param {Node} node
+ * @param {Node} root
+ * @returns {Element[] | null}
+ */
+function ancestorsUpTo(node, root) {
+  const out = [];
+  let p = node.parentNode;
+  while (p && p !== root) {
+    if (p.nodeType !== 1) return null;
+    out.push(/** @type {Element} */ (p));
+    p = p.parentNode;
+  }
+  return p === root ? out : null;
+}
+
+/**
+ * @param {NodeListOf<ChildNode>} list
+ * @param {Node[]} nodes
+ */
+function sameNodes(list, nodes) {
+  if (list.length !== nodes.length) return false;
+  for (let i = 0; i < nodes.length; i++) if (list[i] !== nodes[i]) return false;
+  return true;
+}