@webjsdev/core 0.7.65 → 0.9.0

package/src/render-client/reconciler.js

@@ -1,4 +1,5 @@
-import { isTemplate, MARKER } from '../html.js';
+import { nothing, noChange } from '../sentinels.js';
+import { isTemplate, MARKER, html } from '../html.js';
 import {
   reconcileFormAction, isBoundFormAction, ABSENT, assertSubmitterHasNoName, assertSubmitterType,
   assertSubmitterHasNoValue, assertSubmitterHasNoStaticFormAction,
@@ -10,17 +11,69 @@ import { isLive } from '../directives.js';
 import { attrHoleValue } from '../binding-prefixes.js';
 import { RENDERING, SLOT_OWNER, SLOT_STATE, drainRendererBackstop, rescueAssignedNodes } from '../slot.js';
 import { compile, submitterActionBindings, INSTANCE } from './template-compiler.js';
+import { commitAdoption, planSlotAdoption, retargetParts } from './adopt-slots.js';
 import {
-  applyPart, bindPart, currentRenderRoot, findSlotHost, setCurrentRenderRoot, updateInstance,
+  applyPart, bindPart, currentRenderHost, setCurrentRenderHost, currentRenderRoot, findSlotHost, setCurrentRenderRoot, updateInstance,
+  releaseInstanceDirectives, setInstanceDirectivesConnected, ROOT_DISCONNECTED,
 } from './parts.js';
 
+/**
+ * A top-level list as one child binding. One call site, so its strings are a
+ * stable identity and a re-render updates the list in place.
+ * @param {unknown} list
+ */
+const rootList = (list) => html`${list}`;
+
 /**
  * Render a value into a container, reusing DOM where possible.
  *
  * @param {unknown} value
  * @param {Element | DocumentFragment | ShadowRoot} container
+ * @param {{host?: object}} [options]
  */
-export function render(value, container) {
+export function render(value, container, options = {}) {
+  renderValue(value, container, options);
+  return rootPart(container);
+}
+
+/** @type {WeakMap<object, { setConnected(connected: boolean): void }>} */
+const rootParts = new WeakMap();
+
+/**
+ * What `render()` returns, lit's `RootPart`: `setConnected(false)` reports
+ * every async directive in the container disconnected (and starts the ones a
+ * later render creates disconnected), `setConnected(true)` reconnects them.
+ * @param {any} container
+ */
+function rootPart(container) {
+  let part = rootParts.get(container);
+  if (!part) {
+    part = {
+      setConnected(connected) {
+        container[ROOT_DISCONNECTED] = !connected;
+        setInstanceDirectivesConnected(container[INSTANCE], connected);
+      },
+    };
+    rootParts.set(container, part);
+  }
+  return part;
+}
+
+/**
+ * @param {unknown} value
+ * @param {Element | DocumentFragment | ShadowRoot} container
+ * @param {{host?: object}} options
+ */
+function renderValue(value, container, options) {
+  if (value === noChange) return;
+  // Any object that is not a template (an array or other iterable such as a
+  // `map()` / `join()` / `range()` generator or a Set, a DOM node, a directive)
+  // renders through a child binding, as Lit's `render()` renders every value
+  // (#1686). It used to be written as text, "[object Generator]" or
+  // "[object Object]".
+  if (value !== null && typeof value === 'object' && !isTemplate(value)) {
+    value = rootList(value);
+  }
   const host = /** @type any */ (container);
   // Open the renderer-write window for the whole commit: every host-receiver
   // write below (and in createInstance / updateInstance / clearInstance / all
@@ -29,6 +82,8 @@ export function render(value, container) {
   // between a renderer commit and an author write.
   const prevRendering = host[RENDERING];
   host[RENDERING] = true;
+  const prevHost = currentRenderHost;
+  setCurrentRenderHost(options.host);
   const prevRenderRoot = currentRenderRoot;
   setCurrentRenderRoot(container);
   try {
@@ -44,12 +99,12 @@ export function render(value, container) {
 
       // Light DOM hydration: if container has SSR content (marked by
       // <!--webjs-hydrate-->), remove the marker and proceed with normal
-      // rendering. The content will be replaced with identical output -
-      // no visible flash because SSR and client render produce the same HTML.
+      // rendering. The content is replaced with identical output, so nothing
+      // flashes, except that the SSR slots holding projected children stay in
+      // place (createInstance, #1666), so those children never leave the page.
       const firstChild = container.firstChild;
-      if (firstChild && firstChild.nodeType === 8 && /** @type {Comment} */ (firstChild).data === 'webjs-hydrate') {
-        firstChild.remove();
-      }
+      const hydrating = !!firstChild && firstChild.nodeType === 8 && /** @type {Comment} */ (firstChild).data === 'webjs-hydrate';
+      if (hydrating) firstChild.remove();
 
       // Pre-set the symbol to an explicit null BEFORE the commit,
       // UNCONDITIONALLY: if createInstance throws after its replaceChildren
@@ -59,7 +114,7 @@ export function render(value, container) {
       // instance on the template-swap path (whose bookends would misclassify
       // the half-committed new roots as unowned and fold them).
       host[INSTANCE] = null;
-      const inst = createInstance(tr, container);
+      const inst = createInstance(tr, container, hydrating);
       host[INSTANCE] = inst;
       return;
     }
@@ -68,17 +123,11 @@ export function render(value, container) {
     if (prev) clearInstance(prev, container);
     host[INSTANCE] = null;
     container.replaceChildren();
-    if (value == null || value === false || value === true) return;
-    if (Array.isArray(value)) {
-      for (const v of value) {
-        const text = document.createTextNode(String(v ?? ''));
-        container.appendChild(text);
-      }
-      return;
-    }
+    if (value == null || value === nothing) return;
     container.appendChild(document.createTextNode(String(value)));
   } finally {
     setCurrentRenderRoot(prevRenderRoot);
+    setCurrentRenderHost(prevHost);
     host[RENDERING] = prevRendering;
     // Outermost window closing: drain this commit's childList records off the
     // slot backstop (drainRendererBackstop processes them with a renderer-output
@@ -203,7 +252,7 @@ function reconcileSubmitterAction(
   if (!id) {
     // A function that was MEANT as an action still refuses, so a button never
     // silently submits the form's action instead of its own.
-    if (typeof value === 'function') assertIdentifiableAction(null, el.localName);
+    if (typeof value === 'function') assertIdentifiableAction(null, el.localName, value);
     releaseSubmitterAction(el);
     // The submission attributes the framework supplied go with the identity, or
     // a released button keeps a `formmethod` / `formenctype` SSR does not emit
@@ -307,14 +356,19 @@ function resolveHoleValue(v) {
  * @param {import('../html.js').TemplateResult} tr
  * @param {Element | DocumentFragment | ShadowRoot} container
  */
-function createInstance(tr, container) {
+function createInstance(tr, container, hydrating = false) {
   const { templateEl, parts, formActions } = compile(tr);
-  const frag = /** @type DocumentFragment */ (templateEl.content.cloneNode(true));
+  const frag = /** @type DocumentFragment */ (document.importNode(templateEl.content, true));
   // Bookend markers bound the instance so we can tear it down cleanly.
   const startNode = document.createComment(`${MARKER}s`);
   const endNode = document.createComment(`${MARKER}e`);
 
   const bound = parts.map((p) => bindPart(p, frag));
+  // Hydration keeps the SSR slots that hold projected children, and their
+  // ancestors, in the document (#1666): the parts targeting them are pointed at
+  // the live elements now, before any applies.
+  const adoption = hydrating ? planSlotAdoption(container, frag, bound) : null;
+  if (adoption) retargetParts(adoption, bound);
   const lastValues = [];
   for (let i = 0; i < tr.values.length; i++) {
     applyPart(bound[i], tr.values[i], undefined, tr.values, reconcileFormActions);
@@ -322,7 +376,11 @@ function createInstance(tr, container) {
   }
   reconcileFormActions(formActions, bound, tr.values);
 
-  /** @type any */ (container).replaceChildren(startNode, ...frag.childNodes, endNode);
+  if (adoption) {
+    commitAdoption(adoption, /** @type {Element} */ (container), [startNode, ...frag.childNodes, endNode]);
+  } else {
+    /** @type any */ (container).replaceChildren(startNode, ...frag.childNodes, endNode);
+  }
 
   // Slot parts have no value-hole to drive applyPart from the loop above.
   // Apply them once now that the fragment is inserted into the live
@@ -362,8 +420,11 @@ function clearInstance(inst, container) {
   // element parts, and rescue any projected children sitting inside
   // slot parts so they survive teardown of a collapsing conditional
   // fragment.
+  // Custom directives in the outgoing template are released first (an async
+  // one runs its `disconnected()`), as lit does when a part goes away.
+  releaseInstanceDirectives(inst);
   for (const p of inst.bound) {
-    if (p.kind === 'event') p.el.removeEventListener(p.name, p.dispatcher);
+    if (p.kind === 'event') p.el.removeEventListener(p.name, p.dispatcher, p.handler);
     if (p.kind === 'element') {
       // Guarded for the same reason as the sibling in `disposeInstance`, and
       // the stakes are higher here: this is the container-level teardown
@@ -375,7 +436,7 @@ function clearInstance(inst, container) {
       const prev = /** @type any */ (p).lastTarget;
       if (prev) {
         if (typeof prev === 'function') {
-          try { prev(undefined); } catch {}
+          try { prev.call(/** @type any */ (p).refHost, undefined); } catch {}
         } else if (typeof prev === 'object') {
           try { prev.value = undefined; } catch {}
         }

package/src/render-client/template-compiler.js

@@ -2,6 +2,7 @@ import { MARKER } from '../html.js';
 import { BINDING_PREFIXES, isBindingPrefix } from '../binding-prefixes.js';
 import { isSubmitterReflectedProp } from '../form-action.js';
 import { LIGHT_SLOT_ATTR } from '../slot.js';
+import { assertNoJsxIsms } from '../jsx-guard.js';
 
 /** @type {WeakMap<TemplateStringsArray | string[], { templateEl: HTMLTemplateElement, parts: PartDescriptor[], formActions: FormActionRecord[] | null }>} */
 export const templateCache = new WeakMap();
@@ -12,6 +13,12 @@ export const templateCache = new WeakMap();
  */
 export const submitterActionBindings = new WeakMap();
 export const INSTANCE = Symbol.for('webjs.instance');
+/** Elements whose content the HTML parser reads as text, never markup. */
+const RAW_TEXT_TAGS = new Set(['script', 'style', 'textarea', 'title']);
+/** HTML's own whitespace; `\s` would also match U+00A0, which is attribute text. */
+const HTML_WS = /[ \t\n\f\r]/;
+/** Delimits a raw-text hole's index; a private-use character no parser alters. */
+const RAW_SENTINEL = '\uE000';
 
 /**
  * @typedef {{
@@ -31,13 +38,13 @@ export const INSTANCE = Symbol.for('webjs.instance');
  * }} TemplateInstance
  *
  * @typedef {
- *   | { kind: 'child', marker: Comment, child?: TemplateInstance | ChildNode[] }
+ *   | { kind: 'child', marker: Comment, __eventHost?: object, child?: TemplateInstance | ChildNode[] }
  *   | { kind: 'attr', el: Element, name: string }
  *   | { kind: 'attr-mixed', el: Element, name: string, statics: string[], group: number[] }
- *   | { kind: 'event', el: Element, name: string, handler: ((e: Event) => void) | null, dispatcher: (e: Event) => void }
+ *   | { kind: 'event', el: Element, name: string, handler: (EventListenerOrEventListenerObject & AddEventListenerOptions) | null, eventHost?: object, dispatcher: (e: Event) => void }
  *   | { kind: 'prop', el: Element, name: string }
  *   | { kind: 'bool', el: Element, name: string }
- *   | { kind: 'element', el: Element, lastTarget?: any }
+ *   | { kind: 'element', el: Element, lastTarget?: any, refHost?: object }
  *   | { kind: 'slot', slotEl: HTMLSlotElement, applied: boolean }
  *   | { kind: 'noop' }
  * } BoundPart
@@ -48,6 +55,14 @@ export function compile(tr) {
   const { strings } = tr;
   let cached = templateCache.get(strings);
   if (cached) return cached;
+  // Only a tagged template's own strings array carries `raw`, so a template
+  // result that arrived as data (JSON with the `_$webjs` brand) is refused
+  // rather than parsed as markup, lit's `trustFromTemplateString` check.
+  if (!Array.isArray(strings) || !Object.prototype.hasOwnProperty.call(strings, 'raw')) {
+    throw new Error('[webjs] refusing to render a template result whose strings are not a tagged template\'s (a TemplateResult built from data, not by html``).');
+  }
+  // `className=`, `htmlFor=`, `<Link>`: JSX that HTML silently ignores.
+  assertNoJsxIsms(strings);
 
   /** @type {PartDescriptor[]} */
   const parts = [];
@@ -60,7 +75,15 @@ export function compile(tr) {
   /** @type {{ name: string, firstPartIdx: number } | null} */
   let mixedAttr = null;
   let currentTag = '';
+  let closingTag = false;
   let rawTail = '';
+  // The content state a start tag's `>` opens: raw text for `script` / `style`
+  // / `textarea` / `title`, whose content the HTML parser never reads as markup,
+  // whichever attribute state the tag ended in (lit's `rawTextElement`).
+  const afterTag = () => {
+    rawTail = '';
+    return (!closingTag && RAW_TEXT_TAGS.has(currentTag)) ? 'rawtext' : 'text';
+  };
 
   for (let i = 0; i < strings.length; i++) {
     const s = strings[i];
@@ -74,18 +97,23 @@ export function compile(tr) {
         case 'tag-open':
           html += c;
           if (c === '!') state = 'bang-1';
-          else if (c === '/') { state = 'tag-name'; currentTag = ''; }
-          else if (/[a-zA-Z]/.test(c)) { state = 'tag-name'; currentTag = c.toLowerCase(); }
+          else if (c === '/') { state = 'tag-name'; currentTag = ''; closingTag = true; }
+          else if (/[a-zA-Z]/.test(c)) { state = 'tag-name'; currentTag = c.toLowerCase(); closingTag = false; }
           else state = 'text';
           break;
         case 'bang-1':
           html += c;
-          state = c === '-' ? 'bang-dash' : 'tag-name';
+          state = c === '-' ? 'bang-dash' : 'bogus';
           break;
         case 'bang-dash':
           html += c;
           if (c === '-') { state = 'comment'; commentDashes = 0; }
-          else state = 'tag-name';
+          else state = 'bogus';
+          break;
+        case 'bogus':
+          // A bogus comment (`<!x ...>`, `</ ...>`) runs to the next `>`.
+          html += c;
+          if (c === '>') state = 'text';
           break;
         case 'comment':
           html += c;
@@ -95,18 +123,15 @@ export function compile(tr) {
           break;
         case 'tag-name':
           html += c;
-          if (c === '>') {
-            state = (currentTag === 'script' || currentTag === 'style') ? 'rawtext' : 'text';
-            if (state === 'rawtext') rawTail = '';
-          } else if (/\s/.test(c)) state = 'in-tag';
+          if (closingTag && currentTag === '' && c !== '>' && !/[a-zA-Z]/.test(c)) state = 'bogus';
+          else if (c === '>') state = afterTag();
+          else if (HTML_WS.test(c)) state = 'in-tag';
           else currentTag += c.toLowerCase();
           break;
         case 'in-tag':
           html += c;
-          if (c === '>') {
-            state = (currentTag === 'script' || currentTag === 'style') ? 'rawtext' : 'text';
-            if (state === 'rawtext') rawTail = '';
-          } else if (!/\s/.test(c) && c !== '/') {
+          if (c === '>') state = afterTag();
+          else if (!HTML_WS.test(c) && c !== '/') {
             state = 'attr-name';
             attrName = c;
             attrStart = html.length - 1;
@@ -114,8 +139,10 @@ export function compile(tr) {
           break;
         case 'rawtext':
           html += c;
-          rawTail = (rawTail + c.toLowerCase()).slice(-9);
-          if (rawTail.endsWith('</script>') || rawTail.endsWith('</style>')) {
+          // Only the element's OWN end tag closes it: a `</style>` inside a
+          // `<script>` is script text.
+          rawTail = (rawTail + c.toLowerCase()).slice(-(currentTag.length + 3));
+          if (rawTail === `</${currentTag}>`) {
             state = 'text';
             rawTail = '';
             currentTag = '';
@@ -123,19 +150,28 @@ export function compile(tr) {
           break;
         case 'attr-name':
           if (c === '=') { state = 'after-eq'; html += c; }
-          else if (/\s/.test(c)) { state = 'in-tag'; attrName = ''; html += c; }
-          else if (c === '>') { state = 'text'; attrName = ''; html += c; }
+          else if (HTML_WS.test(c)) { state = 'after-name'; html += c; }
+          else if (c === '>') { state = afterTag(); attrName = ''; html += c; }
           else { attrName += c; html += c; }
           break;
+        case 'after-name':
+          // Whitespace between a name and its `=` (`abc = ${x}`), as the HTML
+          // tokenizer allows.
+          html += c;
+          if (c === '=') state = 'after-eq';
+          else if (c === '>') { state = afterTag(); attrName = ''; }
+          else if (c === '/') { state = 'in-tag'; attrName = ''; }
+          else if (!HTML_WS.test(c)) { state = 'attr-name'; attrName = c; attrStart = html.length - 1; }
+          break;
         case 'after-eq':
           if (c === '"' || c === "'") { state = 'attr-quoted'; attrQuote = c; html += c; }
-          else if (/\s/.test(c)) { state = 'in-tag'; attrName = ''; html += c; }
-          else if (c === '>') { state = 'text'; attrName = ''; html += c; }
+          else if (HTML_WS.test(c)) { html += c; }
+          else if (c === '>') { state = afterTag(); attrName = ''; html += c; }
           else { state = 'attr-unquoted'; html += c; }
           break;
         case 'attr-unquoted':
-          if (/\s/.test(c)) { state = 'in-tag'; attrName = ''; html += c; }
-          else if (c === '>') { state = 'text'; attrName = ''; html += c; }
+          if (HTML_WS.test(c)) { state = 'in-tag'; attrName = ''; html += c; }
+          else if (c === '>') { state = afterTag(); attrName = ''; html += c; }
           else html += c;
           break;
         case 'attr-quoted':
@@ -144,8 +180,10 @@ export function compile(tr) {
           break;
         case 'skip-attr':
           // Consume mixed-attribute chars without appending to html.
-          // The attribute was replaced with a sentinel on the first hole.
-          if (c === attrQuote) {
+          // The attribute was replaced with a sentinel on the first hole. An
+          // UNQUOTED value (`attrQuote` empty, `a=x${y}` or `a=${x}${y}`) ends
+          // at whitespace, `>` or `/>`, as the HTML tokenizer ends it.
+          if (attrQuote === '' ? (HTML_WS.test(c) || c === '>' || (c === '/' && s[j + 1] === '>')) : c === attrQuote) {
             // Closing quote: finalize the attr-mixed part.
             if (mixedAttr) {
               const idx0 = mixedAttr.firstPartIdx;
@@ -160,19 +198,27 @@ export function compile(tr) {
               // statics[n] = prefix of strings[last+1] up to closing quote
               const statics = [];
               const s0 = strings[group[0]];
-              const qp = s0.lastIndexOf(attrQuote);
-              statics.push(qp >= 0 ? s0.slice(qp + 1) : s0);
+              if (attrQuote === '') {
+                statics.push(s0.slice(s0.lastIndexOf('=') + 1).trimStart());
+              } else {
+                const qp = s0.lastIndexOf(attrQuote);
+                statics.push(qp >= 0 ? s0.slice(qp + 1) : s0);
+              }
               for (let k = 1; k < group.length; k++) {
                 statics.push(strings[group[k]]);
               }
               const sLast = strings[group[group.length - 1] + 1];
-              const eq = sLast.indexOf(attrQuote);
+              const eq = attrQuote === '' ? j : sLast.indexOf(attrQuote);
               statics.push(eq >= 0 ? sLast.slice(0, eq) : sLast);
 
+              const specialized = isBindingPrefix(mixedAttr.name[0]);
+              if (specialized && (group.length !== 1 || statics.some((piece) => piece !== ''))) {
+                throw new Error('Event, property and boolean bindings require exactly one expression with no surrounding text.');
+              }
               parts[idx0] = {
-                kind: 'attr-mixed',
+                kind: specialized ? BINDING_PREFIXES[mixedAttr.name[0]] : 'attr-mixed',
                 path: [],
-                name: mixedAttr.name,
+                name: specialized ? mixedAttr.name.slice(1) : mixedAttr.name,
                 statics,
                 group,
               };
@@ -187,8 +233,11 @@ export function compile(tr) {
               }
               mixedAttr = null;
             }
-            state = 'in-tag';
             attrName = '';
+            // A quoted value's closing quote was consumed with it; an unquoted
+            // value's terminator is markup and is kept.
+            if (attrQuote === '') html += c;
+            state = (attrQuote === '' && c === '>') ? afterTag() : 'in-tag';
           }
           break;
       }
@@ -205,28 +254,38 @@ export function compile(tr) {
         continue;
       }
       if (state === 'rawtext') {
-        // Inside <script>/<style>: per-render interpolation isn't supported;
-        // the compile cache would lock in whatever was first rendered. The
-        // hole is dropped and authors should set body text via a child part
-        // outside the raw-text container, or inline style/script directly.
+        // Inside <script> / <style> / <textarea> / <title> the parser reads a
+        // comment marker as text, so the hole leaves a text sentinel that
+        // `splitRawTextSentinels` turns into a marker comment after parsing.
+        // It is then an ordinary child part committing text nodes, which is
+        // what lit does and what SSR's raw-text hole emits.
         rawTail = '';
-        parts.push({ kind: 'noop', path: [] });
+        html += `${RAW_SENTINEL}${partIdx}${RAW_SENTINEL}`;
+        parts.push({ kind: 'child', path: [] });
         continue;
       }
+      // An unquoted value that goes on after its hole (`a=${x}${y}`,
+      // `a=${x}px`) is interpolated, like a quoted one.
+      const next = strings[i + 1];
+      const unquotedGoesOn = state === 'after-eq'
+        && (next === '' ? i + 1 < strings.length - 1 : !/^([ \t\n\f\r]|>|\/>)/.test(next));
       if (state === 'text') {
         // Child hole: insert a comment marker. Use bracketed markers so we can
         // later walk all comments and find ours without ambiguity.
         html += `<!--${MARKER}${partIdx}-->`;
         parts.push({ kind: 'child', path: [] });
-      } else if (state === 'in-tag') {
-        // Element-position hole: `<tag ${expr}>`. Used by the `ref` directive
+      } else if (state === 'in-tag' || state === 'after-name') {
+        // Element-position hole: `<tag ${expr}>`, also after a bare attribute
+        // (`<input disabled ${expr}>`). Used by the `ref` directive
         // (and any future element-bound directive). Emit a sentinel attribute
         // on the current open tag; at bind time the attribute is stripped
         // and the element is captured into the part.
         const sentinel = `data-${MARKER}${partIdx}`;
         html += `${sentinel}=""`;
         parts.push({ kind: 'element', path: [] });
-      } else if (state === 'after-eq') {
+        state = 'in-tag';
+        attrName = '';
+      } else if (state === 'after-eq' && !unquotedGoesOn) {
         const prefix = attrName[0];
         const name = attrName.slice(1);
         if (isBindingPrefix(prefix)) {
@@ -245,24 +304,42 @@ export function compile(tr) {
         }
         state = 'in-tag';
         attrName = '';
-      } else if (state === 'attr-quoted' || state === 'attr-unquoted') {
+      } else if (state === 'attr-quoted' || state === 'attr-unquoted' || state === 'after-eq') {
         // First hole inside a quoted attribute value: start mixed-attr tracking.
         // Replace the entire attribute with a sentinel (same as regular attr).
+        if (state !== 'attr-quoted') attrQuote = '';
         html = html.slice(0, attrStart);
         const sentinel = `data-${MARKER}${partIdx}`;
         html += `${sentinel}=""`;
         mixedAttr = { name: attrName, firstPartIdx: partIdx };
         parts.push({ kind: 'noop', path: [] }); // patched to attr-mixed at close-quote
         state = 'skip-attr';
-      } else if (state === 'skip-attr') {
-        // Subsequent hole in the same mixed attribute.
+      } else {
+        // `skip-attr`: a later hole in the same mixed attribute. Any other
+        // state is a hole where no binding can sit (a tag name, `</div ${x}>`):
+        // it binds nothing, as in lit's production build, and still takes its
+        // index so every later part keeps its own.
         parts.push({ kind: 'noop', path: [] });
       }
     }
   }
 
   const templateEl = document.createElement('template');
-  templateEl.innerHTML = html;
+  if (tr.svg || tr.mathml) {
+    // An svg`` (or mathml``) fragment is parsed inside an <svg> (or <math>)
+    // wrapper so its elements land in that namespace, then the wrapper is
+    // unwrapped BEFORE the slot and path walks, so every recorded path is
+    // relative to the fragment's own root, as it is for an html`` template
+    // (lit does the same).
+    const wrapTag = tr.svg ? 'svg' : 'math';
+    templateEl.innerHTML = `<${wrapTag}>${html}</${wrapTag}>`;
+    const wrapper = /** @type {Element} */ (templateEl.content.firstChild);
+    wrapper.replaceWith(...wrapper.childNodes);
+  } else {
+    templateEl.innerHTML = html;
+  }
+
+  if (html.includes(RAW_SENTINEL)) splitRawTextSentinels(templateEl.content);
 
   // Mark every <slot> in the template for framework projection and
   // register a SLOT part for each so the slot-apply step can find them on
@@ -281,6 +358,38 @@ export function compile(tr) {
   return cached;
 }
 
+/**
+ * Replace each raw-text hole's sentinel with a `wjm-<idx>` marker comment, so
+ * the path walk records it as a child part. A comment inside `<script>` or
+ * `<textarea>` is a DOM child the element's text (`textContent`, `.text`,
+ * `.value`) ignores, which is how lit anchors a raw-text binding too.
+ *
+ * @param {DocumentFragment} root
+ */
+function splitRawTextSentinels(root) {
+  /** @type {Text[]} */
+  const hits = [];
+  /** @param {Node} node */
+  const collect = (node) => {
+    for (const child of node.childNodes) {
+      if (child.nodeType === 3) { if (/** @type {Text} */ (child).data.includes(RAW_SENTINEL)) hits.push(/** @type {Text} */ (child)); }
+      else collect(child);
+    }
+  };
+  collect(root);
+  for (const text of hits) {
+    const pieces = text.data.split(RAW_SENTINEL);
+    /** @type {Node[]} */
+    const nodes = [];
+    // pieces alternate text, index, text, index, ..., text
+    for (let k = 0; k < pieces.length; k++) {
+      if (k % 2) nodes.push(document.createComment(`${MARKER}${pieces[k]}`));
+      else if (pieces[k]) nodes.push(document.createTextNode(pieces[k]));
+    }
+    text.replaceWith(...nodes);
+  }
+}
+
 /**
  * Walk the compiled template content for <slot> elements (the static ones
  * written into the template, not dynamically-inserted ones). For each:

package/src/render-client.d.ts

@@ -1 +1,6 @@
-export function render(value: unknown, container: Element | DocumentFragment | ShadowRoot): void;
+export interface RenderOptions { host?: object; }
+/** What `render()` returns, lit's `RootPart`: `setConnected(false)` disconnects the async directives the render created, `setConnected(true)` reconnects them. */
+export interface RootPart {
+  setConnected(isConnected: boolean): void;
+}
+export function render(value: unknown, container: Element | DocumentFragment | ShadowRoot, options?: RenderOptions): RootPart;

package/src/render-server/attrs.js

@@ -67,7 +67,7 @@ export function withHostMarker(opening) {
  * `getAttribute` API so it works whether the instance is the server shim or a
  * real `HTMLElement`. Returns the opening tag unchanged when there is nothing
  * to add, so existing SSR output stays byte-identical when no component
- * reflects, which preserves the elision on-vs-off differential invariant.
+ * reflects.
  *
  * @param {string} opening  the element's opening tag, ending in `>`
  * @param {any} instance
@@ -129,7 +129,7 @@ export function applyAttrsToInstance(instance, attrs, Cls) {
     // 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));
+    instance[propName] = readAttributeValue(def, decodeAttrEntities(sourceValue), propName);
   }
 }