@opentf/web 0.5.0 → 0.7.0

package/runtime/dom.js

@@ -3,6 +3,7 @@
 // no diffing — just direct, fine-grained DOM writes wired to signals.
 
 import { effect, signal } from "../core/signals.js";
+import { claimRegionEnd, claimRegionStart } from "./hydrate.js";
 
 // Attribute names that must be assigned as JS properties (not setAttribute) for
 // correct behavior. Mirrors the set the old runtime relied on (core/constants).
@@ -64,6 +65,13 @@ export function toText(value) {
   return value == null || value === false ? "" : String(value);
 }
 
+/** Sentinel for "nothing written yet" — distinct from any real attribute value. */
+const UNSET = Symbol("unset");
+
+/** A value safe to compare by identity for write elision (no internal mutation). */
+const isPrimitive = (v) =>
+  v === null || (typeof v !== "object" && typeof v !== "function");
+
 /**
  * clsx-style class normalization. Falsy entries are skipped; strings/numbers are
  * kept; arrays recurse; objects contribute the keys whose values are truthy. Lets
@@ -165,30 +173,64 @@ export function spread(el, obj, asProps) {
  */
 export function bindText(node, fn) {
   let inserted = [];
+  let lastText; // undefined sentinel — toText() never returns undefined
   return effect(() => {
     const value = fn();
+
+    // Primitive text: the common case. Skip the write when the rendered string
+    // is unchanged (a shared dependency can re-run this effect with the same
+    // result), so unchanged text nodes don't churn.
+    if (!(value instanceof Node) && !Array.isArray(value)) {
+      const text = toText(value);
+      if (text === lastText) return;
+      lastText = text;
+      for (const n of inserted) {
+        if (n.parentNode) n.parentNode.removeChild(n);
+      }
+      inserted = [];
+      node.data = text;
+      return;
+    }
+
+    // Node / array value (e.g. JSX stored as a value): insert before the stable
+    // text anchor. Reset the text memo so a later primitive value re-applies.
+    lastText = undefined;
     for (const n of inserted) {
       if (n.parentNode) n.parentNode.removeChild(n);
     }
     inserted = [];
-    if (value instanceof Node || Array.isArray(value)) {
-      node.data = "";
-      const parent = node.parentNode;
-      if (parent) {
-        for (const n of toNodes(value)) {
-          parent.insertBefore(n, node);
-          inserted.push(n);
-        }
+    node.data = "";
+    const parent = node.parentNode;
+    if (parent) {
+      for (const n of toNodes(value)) {
+        parent.insertBefore(n, node);
+        inserted.push(n);
       }
-    } else {
-      node.data = toText(value);
     }
   });
 }
 
-/** Wire an element attribute/prop to a reactive expression. Returns the disposer. */
+/**
+ * Wire an element attribute/prop to a reactive expression. Returns the disposer.
+ *
+ * No-op writes are elided for primitive values: when the expression recomputes
+ * to the same primitive it last wrote, the DOM write is skipped. This matters
+ * when many elements share one dependency — e.g. a keyed list where every row's
+ * `class={selected === row.id ? "danger" : ""}` subscribes to a single
+ * `selected` signal. Changing it re-runs every row's effect, but only the two
+ * rows whose class actually changes should touch the DOM; the rest would
+ * otherwise call `setAttribute` with an unchanged value and trigger needless
+ * style invalidation. Object values (style/class objects, spreads) may have
+ * mutated internally, so they are always re-applied.
+ */
 export function bindAttr(el, name, fn) {
-  return effect(() => setAttr(el, name, fn()));
+  let last = UNSET;
+  return effect(() => {
+    const value = fn();
+    if (isPrimitive(value) && Object.is(value, last)) return;
+    last = value;
+    setAttr(el, name, value);
+  });
 }
 
 /** Flatten a reactive child value into DOM nodes: nodes pass through, arrays
@@ -212,9 +254,40 @@ function toNodes(value) {
  * Returns the effect disposer.
  */
 export function bindChild(anchor, fn) {
-  let current = [];
+  return childEffect(anchor, fn, [], false);
+}
+
+/**
+ * Hydrate a server-rendered conditional / dynamic-node region (docs/HYDRATION.md §3.1,
+ * 2.1b). The cursor `cur` is at the `<!--[-->` marker; between it and `<!--]-->` sits the
+ * one branch the server rendered (or nothing). `adoptFn(cur)` evaluates the same branch
+ * expression with *adopt* calls — only the taken branch's builder runs, claiming its nodes
+ * off the shared cursor — so the adopted nodes become the region's initial content with no
+ * rebuild. `buildFn()` is the CSR version (build calls) the effect swaps to when a later
+ * reactive change selects a different branch. The closing `<!--]-->` is the swap anchor.
+ * Returns the effect disposer.
+ */
+export function hydrateChild(cur, adoptFn, buildFn) {
+  claimRegionStart(cur);
+  const adopted = toNodes(adoptFn(cur));
+  const anchor = claimRegionEnd(cur);
+  // Seed with the adopted nodes and skip the first effect run's DOM write: the branch is
+  // already in place. The first run still evaluates `buildFn` to subscribe to its reactive
+  // deps (the built nodes are discarded); from the second run on it swaps normally.
+  return childEffect(anchor, buildFn, adopted, true);
+}
+
+/** The child-region effect shared by {@link bindChild} (empty seed, no skip) and
+ * {@link hydrateChild} (seeded with adopted nodes, first DOM write skipped). On each run
+ * the previous nodes are replaced with the new ones, inserted before `anchor`. */
+function childEffect(anchor, fn, current, skipFirst) {
+  let first = skipFirst;
   return effect(() => {
     const next = toNodes(fn());
+    if (first) {
+      first = false;
+      return; // hydration: keep the adopted DOM on first paint (subscribe only)
+    }
     const host = anchor.parentNode;
     for (const n of current) {
       if (n.parentNode === host) host.removeChild(n);
@@ -238,13 +311,57 @@ export function bindChild(anchor, fn) {
 export function bindList(parent, sourceFn, renderItem, keyFn) {
   const anchor = document.createComment("");
   parent.appendChild(anchor);
-  let cache = new Map(); // key -> { sig, node }
+  return reconcileList(anchor, sourceFn, renderItem, keyFn, new Map(), []);
+}
+
+/**
+ * Hydrate a server-rendered list region (docs/HYDRATION.md §3.1/2.1). The cursor `cur` is
+ * positioned at the `<!--[-->` marker; the region holds one root node per item, then
+ * `<!--]-->`. Adopts each item's server node via `adoptItem(cur, itemSignal, index)`
+ * (claiming off the shared cursor, which advances to the next item), seeds the reconcile
+ * cache with the adopted `{sig, node}` pairs, then wires the *same* keyed-reconcile effect
+ * `bindList` uses — so a later data change builds/moves/removes with no first-paint flash.
+ * The closing `<!--]-->` becomes the reconcile anchor. Returns the effect disposer.
+ */
+export function hydrateList(cur, sourceFn, adoptItem, renderItem, keyFn) {
+  claimRegionStart(cur);
+  const data = sourceFn();
+  const items = Array.isArray(data) ? data : [];
+  const cache = new Map();
+  const prevKeys = [];
+  for (let index = 0; index < items.length; index++) {
+    const item = items[index];
+    const key = keyFn ? keyFn(item, index) : index;
+    const sig = signal(item);
+    const node = adoptItem(cur, sig, index); // claims one item subtree off `cur`
+    cache.set(key, { sig, node });
+    prevKeys.push(key);
+  }
+  const anchor = claimRegionEnd(cur);
+  // The seeded effect's first run re-reads the same data: every key hits the cache, so it
+  // subscribes for future updates without mutating the already-correct adopted DOM.
+  return reconcileList(anchor, sourceFn, renderItem, keyFn, cache, prevKeys);
+}
 
+/**
+ * The keyed-reconcile effect shared by {@link bindList} (empty seed) and
+ * {@link hydrateList} (seeded from adopted nodes). `anchor` is the trailing comment new
+ * items are inserted before; `cache` (key → `{sig, node}`) and `prevKeys` (keys in DOM
+ * order) carry reconciliation state across runs. Returns the effect disposer.
+ */
+function reconcileList(anchor, sourceFn, renderItem, keyFn, cache, prevKeys) {
   return effect(() => {
     const data = sourceFn();
     const items = Array.isArray(data) ? data : [];
     const next = new Map();
-    const nodes = [];
+    const nodes = new Array(items.length);
+    const newKeys = new Array(items.length);
+    // For each new position, the node's index in the *previous* order, or -1 if
+    // it is newly created. Drives the LIS-based minimal move below.
+    const prevIndex = new Array(items.length);
+
+    const prevPos = new Map();
+    for (let i = 0; i < prevKeys.length; i++) prevPos.set(prevKeys[i], i);
 
     for (let index = 0; index < items.length; index++) {
       const item = items[index];
@@ -252,13 +369,16 @@ export function bindList(parent, sourceFn, renderItem, keyFn) {
       let entry = cache.get(key);
       if (entry) {
         cache.delete(key);
-        entry.sig.value = item; // fine-grained per-item update
+        entry.sig.value = item; // fine-grained per-item update (no-op if unchanged)
+        prevIndex[index] = prevPos.has(key) ? prevPos.get(key) : -1;
       } else {
         const sig = signal(item);
         entry = { sig, node: renderItem(sig, index) };
+        prevIndex[index] = -1;
       }
       next.set(key, entry);
-      nodes.push(entry.node);
+      newKeys[index] = key;
+      nodes[index] = entry.node;
     }
 
     // Remove nodes whose keys disappeared.
@@ -266,15 +386,52 @@ export function bindList(parent, sourceFn, renderItem, keyFn) {
       if (entry.node.parentNode) entry.node.parentNode.removeChild(entry.node);
     }
     cache = next;
+    prevKeys = newKeys;
 
-    // Place nodes in order, just before the anchor (works even after the
-    // initial fragment has been flushed into the real parent).
-    const host = anchor.parentNode || parent;
-    let ref = anchor;
+    // Minimal-move placement. Nodes whose previous indices form the longest
+    // increasing subsequence are already in relative order and stay put; only
+    // the rest (and newly created nodes) are inserted. A 2-row swap moves 2
+    // nodes, not the ~n nodes a naive "fix every wrong nextSibling" pass would
+    // cascade into. Walk back to front so each insertion's reference node is
+    // already in its final position.
+    const keep = longestIncreasingRun(prevIndex);
+    const host = anchor.parentNode;
+    if (!host) return; // anchor detached (list torn down) — nothing to place
     for (let i = nodes.length - 1; i >= 0; i--) {
-      const node = nodes[i];
-      if (node.nextSibling !== ref) host.insertBefore(node, ref);
-      ref = node;
+      if (keep.has(i)) continue;
+      const ref = i + 1 < nodes.length ? nodes[i + 1] : anchor;
+      if (nodes[i].nextSibling !== ref) host.insertBefore(nodes[i], ref);
     }
   });
 }
+
+/**
+ * Indices `i` of `seq` whose values form a longest strictly-increasing
+ * subsequence (patience sorting, O(n log n)). Entries equal to -1 (new nodes)
+ * are excluded — they always need insertion. Returned as a Set for O(1) lookup
+ * during placement; these are the nodes that can stay where they are.
+ */
+function longestIncreasingRun(seq) {
+  const piles = []; // piles[k] = index of the smallest tail of a length-(k+1) run
+  const prev = new Array(seq.length).fill(-1);
+  for (let i = 0; i < seq.length; i++) {
+    const v = seq[i];
+    if (v < 0) continue; // new node — never part of the stable run
+    let lo = 0;
+    let hi = piles.length;
+    while (lo < hi) {
+      const mid = (lo + hi) >> 1;
+      if (seq[piles[mid]] < v) lo = mid + 1;
+      else hi = mid;
+    }
+    if (lo > 0) prev[i] = piles[lo - 1];
+    piles[lo] = i;
+  }
+  const keep = new Set();
+  let k = piles.length ? piles[piles.length - 1] : -1;
+  while (k >= 0) {
+    keep.add(k);
+    k = prev[k];
+  }
+  return keep;
+}

package/runtime/error-boundary.js

@@ -9,7 +9,7 @@
 // A descendant component's connectedCallback funnels a thrown error through
 // `handleError(this, …)` (emitted by the compiler): it reports the error (dev
 // overlay / logging) and walks up the DOM — hopping across portals, like
-// `readContext` — to the nearest `web-error-boundary`, which swaps its children
+// `readContext` — to the nearest `web-internal-error-boundary`, which swaps its children
 // for the fallback. `reset()` rebuilds the original subtree (snapshotted before it
 // ran) to retry. Only synchronous render/mount errors are caught; later
 // effect/event errors still go to global reporting (as with React boundaries).
@@ -24,7 +24,7 @@ export function handleError(el, error, context = {}) {
   reportError(error, context); // always log / surface in the dev overlay
   let node = el;
   while (node) {
-    const boundary = node.closest ? node.closest("web-error-boundary") : null;
+    const boundary = node.closest ? node.closest("web-internal-error-boundary") : null;
     if (boundary) {
       boundary.catch(error, context);
       return;
@@ -102,8 +102,8 @@ export class ErrorBoundaryElement extends HTMLElement {
 }
 
 // Exported so `import { ErrorBoundary } from "@opentf/web"` resolves; the import
-// side effect registers the element (JSX uses the `web-error-boundary` tag).
+// side effect registers the element (JSX uses the `web-internal-error-boundary` tag).
 export const ErrorBoundary = ErrorBoundaryElement;
-if (typeof customElements !== "undefined" && !customElements.get("web-error-boundary")) {
-  customElements.define("web-error-boundary", ErrorBoundaryElement);
+if (typeof customElements !== "undefined" && !customElements.get("web-internal-error-boundary")) {
+  customElements.define("web-internal-error-boundary", ErrorBoundaryElement);
 }

package/runtime/hydrate.js

@@ -0,0 +1,268 @@
+// Hydration primitives (Phase 2 — see docs/HYDRATION.md). The client *adopts* the
+// server-rendered DOM instead of rebuilding it: it claims existing nodes and wires
+// reactivity (bindText/bindAttr/events from dom.js) onto them. There is no separate
+// "hydrate" binding logic — those helpers already operate on existing nodes; the only
+// new work is *node acquisition*, which is what this module provides.
+//
+// Acquisition is a **cursor walk** (the decided approach, like Solid): the Hydrate
+// codegen emits claim calls in the exact order the SSG backend emitted nodes, so a
+// cursor over a parent's childNodes lines up 1:1 with the template. The server output
+// carries no inter-element whitespace (ssg.rs concatenates with no padding), so the
+// re-parsed DOM has text nodes only where the template does — the walk stays aligned.
+//
+// Markers (only where structure is variable): a dynamic text hole is delimited by
+// `<!--$-->value<!--/-->` so it is findable even when the value is empty or adjacent
+// to static text (which the HTML parser would otherwise merge into one text node).
+// Static structure carries no markers and is claimed by position.
+
+/** Comment markers bounding a dynamic text hole in server HTML. */
+export const HOLE_START = "$";
+export const HOLE_END = "/";
+
+/** Comment markers bounding a variable structural region — a list or a conditional —
+ * in server HTML (docs/HYDRATION.md §3.1): `<!--[-->` opens, `<!--]-->` closes. A list
+ * holds one item root node per item; a conditional holds the currently rendered branch
+ * (or nothing). The closing marker becomes the reconcile/swap anchor on hydration. */
+export const REGION_START = "[";
+export const REGION_END = "]";
+
+/** Markers bounding a *component's* light-DOM `{children}` slot (docs/HYDRATION.md §3.1,
+ * 2.1d) — distinct bytes from the list/conditional region markers so a component's own
+ * internal regions never collide with its slot. The slot's content is the *parent's* JSX
+ * (server-rendered here), so the parent finds this slot by its `<!--c[-->` marker within the
+ * host and adopts the children (its reactivity), while the component steps over the slot. */
+export const SLOT_START = "c[";
+export const SLOT_END = "c]";
+
+const ELEMENT = 1;
+const TEXT = 3;
+const COMMENT = 8;
+
+/** Thrown when the server DOM doesn't match the template at a claim site. The
+ * component boundary catches this and recovers by rebuilding via CSR (never silent;
+ * see docs/HYDRATION.md §3.5). */
+export class HydrationMismatch extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "HydrationMismatch";
+  }
+}
+
+// ── the hydration flag ────────────────────────────────────────────────────────
+// True during the initial hydration pass. A component's connectedCallback reads it
+// to decide whether to *adopt* its server children or *build* a fresh subtree — the
+// custom-element-as-island coordination (docs/HYDRATION.md §3.4).
+//
+// Why a flag and not the per-instance `this.firstChild` test: a server-rendered host
+// and a client-`createElement`'d host that was handed call-site children both have a
+// `firstChild`, so the structural test alone can't tell "adopt the server DOM" from
+// "build and slot these children" (it mis-adopts on plain SPA navigation). The flag is
+// the unambiguous signal — it is only ever set during the one-shot first-paint pass.
+let _hydrating = false;
+
+/** Is the client mid-hydration right now? */
+export function isHydrating() {
+  return _hydrating;
+}
+
+/** Run `fn` with the hydration flag set, restoring the prior value (nesting-safe).
+ * Synchronous only — for the async first-paint pass use {@link beginHydration} /
+ * {@link endHydration}, which span the route module's `import()`. */
+export function runHydration(fn) {
+  const prev = _hydrating;
+  _hydrating = true;
+  try {
+    return fn();
+  } finally {
+    _hydrating = prev;
+  }
+}
+
+// Route modules are code-split (`() => import(...)`), so a route's custom elements are
+// defined — and its server-rendered hosts upgrade synchronously — *during* the router's
+// `await import()`, before the page `hydrate` factory runs. The flag therefore has to be
+// set across that whole async region, which a synchronous `runHydration` can't do; the
+// router brackets first paint with these instead. First-paint hydration is a single,
+// sequential boot step (no concurrent navigation), so a plain module-global set is safe.
+
+/** Begin the first-paint hydration pass; pair with {@link endHydration}. Set *before*
+ * the route module is imported so every server host upgrading at `customElements.define`
+ * observes it and adopts (docs/HYDRATION.md §3.4). */
+export function beginHydration() {
+  _hydrating = true;
+}
+
+/** End the first-paint hydration pass — subsequent client navigations build fresh. */
+export function endHydration() {
+  _hydrating = false;
+}
+
+// ── the serialized props payload (compiler-driven data hydration) ─────────────
+// SSG/SSR embeds each island's rich props in a `<script type="application/json"
+// id="__otfw_h">`, keyed by the host's `data-h` id (see server/ssg-runtime.js). A
+// hydrating component reads its props from here — real JS values (objects, arrays,
+// numbers), not lossy string attributes — so it resumes with correct data, with no flash
+// and no dependence on a parent walk re-applying props. Read once and cached.
+let _payload; // undefined = not yet read; null = none present; else the parsed array
+
+function hydrationPayload() {
+  if (_payload === undefined) {
+    const el = typeof document !== "undefined" ? document.getElementById("__otfw_h") : null;
+    try {
+      _payload = el ? JSON.parse(el.textContent || "[]") : null;
+    } catch {
+      _payload = null;
+    }
+  }
+  return _payload;
+}
+
+/**
+ * The rich hydration props recorded for host `el` (keyed by its `data-h` id), or `null`
+ * when there is no payload for it — a client-`createElement`'d element on SPA navigation,
+ * or a plain CSR build. A hydrate-target component constructor reads this to initialize
+ * its prop signals, falling back to attributes/defaults when it returns `null`.
+ */
+export function hydrationProps(el) {
+  const data = hydrationPayload();
+  if (!data || !el || typeof el.getAttribute !== "function") return null;
+  const id = el.getAttribute("data-h");
+  if (id == null) return null;
+  const entry = data[+id];
+  return entry == null ? null : entry;
+}
+
+/** Reset the cached payload (tests only — a fresh document between cases). */
+export function __resetHydrationPayload() {
+  _payload = undefined;
+}
+
+// ── the cursor ────────────────────────────────────────────────────────────────
+
+/** A walker over `parent`'s children, positioned at the next node to claim. */
+export function cursor(parent) {
+  return { node: parent.firstChild };
+}
+
+/** Advance past the next node without claiming it (a static text node between
+ * dynamic siblings), returning it. The template only emits a skip for a static
+ * `ViewNode::Text`, which the server renders as a real text node; assert that so a
+ * cursor misalignment surfaces *here* (with a clear message) instead of downstream at
+ * an unrelated claim. Throws {@link HydrationMismatch} on a wrong/absent node. */
+export function skipNode(cur) {
+  const n = cur.node;
+  if (!n || n.nodeType !== TEXT) {
+    throw new HydrationMismatch(`expected static text, found ${describe(n)}`);
+  }
+  cur.node = n.nextSibling;
+  return n;
+}
+
+/**
+ * Claim the next node as an element, optionally asserting its tag, and advance the
+ * cursor past it. Returns the element so the caller can claim its children with a
+ * fresh `cursor(el)`. A wrong/absent node throws {@link HydrationMismatch}.
+ */
+export function claimElement(cur, tag) {
+  const el = cur.node;
+  if (!el || el.nodeType !== ELEMENT || (tag && el.tagName.toLowerCase() !== tag.toLowerCase())) {
+    throw new HydrationMismatch(`expected <${tag ?? "element"}>, found ${describe(el)}`);
+  }
+  cur.node = el.nextSibling;
+  return el;
+}
+
+/**
+ * Claim a dynamic text hole delimited by `<!--$-->…<!--/-->`, returning the text node
+ * to bind onto (created empty when the server rendered no value), and advance the
+ * cursor past the closing marker. Wire reactivity with `bindText(node, fn)` from
+ * dom.js — the binding logic is shared with CSR; only the node is adopted, not built.
+ */
+export function claimText(cur) {
+  const start = cur.node;
+  if (!start || start.nodeType !== COMMENT || start.data !== HOLE_START) {
+    throw new HydrationMismatch(`expected a text-hole marker, found ${describe(start)}`);
+  }
+  let node = start.nextSibling;
+  let textNode = null;
+  while (node && !(node.nodeType === COMMENT && node.data === HOLE_END)) {
+    if (node.nodeType === TEXT && !textNode) textNode = node;
+    node = node.nextSibling;
+  }
+  const end = node; // the `<!--/-->` marker (or null if the markup is malformed)
+  if (!textNode) {
+    // Empty hole (`<!--$--><!--/-->`): synthesize the anchor bindText will write into.
+    textNode = document.createTextNode("");
+    (start.parentNode || document).insertBefore(textNode, end);
+  }
+  cur.node = end ? end.nextSibling : null;
+  return textNode;
+}
+
+/** Claim the `<!--[-->` marker that opens a server-rendered region (list or conditional),
+ * advancing the cursor past it. Throws {@link HydrationMismatch} on a wrong/absent node. */
+export function claimRegionStart(cur) {
+  const n = cur.node;
+  if (!n || n.nodeType !== COMMENT || n.data !== REGION_START) {
+    throw new HydrationMismatch(`expected a region start marker, found ${describe(n)}`);
+  }
+  cur.node = n.nextSibling;
+  return n;
+}
+
+/** Claim the `<!--]-->` marker that closes a region and return it — it becomes the
+ * reconcile/swap anchor (`hydrateList`/`hydrateChild` insert later nodes before it).
+ * Advances the cursor past it. Throws {@link HydrationMismatch} on a wrong/absent node. */
+export function claimRegionEnd(cur) {
+  const n = cur.node;
+  if (!n || n.nodeType !== COMMENT || n.data !== REGION_END) {
+    throw new HydrationMismatch(`expected a region end marker, found ${describe(n)}`);
+  }
+  cur.node = n.nextSibling;
+  return n;
+}
+
+/** Step a component's own adopt walk past its `{children}` slot — claim the
+ * `<!--c[-->`…`<!--c]-->` markers and skip the slotted nodes (the parent owns their
+ * reactivity, wired separately by {@link hydrateSlot}), leaving them in place. Advances the
+ * cursor past the closing marker. Throws {@link HydrationMismatch} on a missing start marker. */
+export function skipSlot(cur) {
+  const start = cur.node;
+  if (!start || start.nodeType !== COMMENT || start.data !== SLOT_START) {
+    throw new HydrationMismatch(`expected a children-slot marker, found ${describe(start)}`);
+  }
+  let n = start.nextSibling;
+  while (n && !(n.nodeType === COMMENT && n.data === SLOT_END)) n = n.nextSibling;
+  cur.node = n ? n.nextSibling : null; // step past the `<!--c]-->` end marker
+}
+
+/**
+ * Adopt a component's slotted children — the *parent's* JSX, server-rendered inside the
+ * component host at its `{children}` slot. The parent owns their reactivity but the
+ * component decides where they sit, so the parent locates the slot by its `<!--c[-->` marker
+ * within `host` and adopts from the first slotted node via `adoptFn(cursor)`. Independent of
+ * when the component upgrades: the markers are static server DOM and adoption only *wires*
+ * (never moves) nodes, so it commutes with the component's own `skipSlot`. A missing marker
+ * (a rebuilt component, or no children) is a no-op.
+ */
+export function hydrateSlot(host, adoptFn) {
+  const start = findComment(host, SLOT_START);
+  if (start) adoptFn({ node: start.nextSibling });
+}
+
+/** The first descendant comment of `root` whose data is `data` (tree order). */
+function findComment(root, data) {
+  const walker = document.createTreeWalker(root, 128 /* NodeFilter.SHOW_COMMENT */);
+  let n;
+  while ((n = walker.nextNode())) if (n.data === data) return n;
+  return null;
+}
+
+/** A short human description of a node for mismatch messages. */
+function describe(node) {
+  if (!node) return "nothing";
+  if (node.nodeType === ELEMENT) return `<${node.tagName.toLowerCase()}>`;
+  if (node.nodeType === TEXT) return `text "${(node.data || "").slice(0, 20)}"`;
+  if (node.nodeType === COMMENT) return `comment <!--${node.data}-->`;
+  return `node(${node.nodeType})`;
+}

package/runtime/index.js

@@ -1,16 +1,22 @@
 // Built-in custom elements self-register on import. They're used in JSX as *tags*
-// (`<Portal>` → `web-portal`), so their bindings are never referenced and a plain
+// (`<Portal>` → `web-internal-portal`), so their bindings are never referenced and a plain
 // re-export would be tree-shaken away (the element never registers). Bare imports
 // force the registration side effect to be retained.
 import "./context.js";
 import "./error-boundary.js";
 import "./portal.js";
+import "./raw-html.js";
+import "./code-block.js";
 
 export * from "./dom.js";
 export * from "./events.js";
 export * from "./mount.js";
+export * from "./hydrate.js";
 export * from "./lifecycle.js";
 export * from "./router.js";
 export * from "./context.js";
 export * from "./error-boundary.js";
 export * from "./portal.js";
+export * from "./raw-html.js";
+export * from "./code-block.js";
+export * from "./clipboard.js";

package/runtime/portal.js

@@ -3,7 +3,7 @@
 //
 //   <Portal to="#toast-root"> … </Portal>   // selector, element, or default body
 //
-// `<Portal>` compiles to this built-in `web-portal` element (capitalized name →
+// `<Portal>` compiles to this built-in `web-internal-portal` element (capitalized name →
 // tag, like <ContextProvider>) — no compiler changes. At connect it moves its
 // light-DOM children to the target; on disconnect it removes them so their
 // custom-element disconnect + effect cleanups run (the part userland leaks).
@@ -52,8 +52,8 @@ export class PortalElement extends HTMLElement {
 }
 
 // Exported so `import { Portal } from "@opentf/web"` resolves; the import side
-// effect registers the element (JSX uses the `web-portal` tag).
+// effect registers the element (JSX uses the `web-internal-portal` tag).
 export const Portal = PortalElement;
-if (typeof customElements !== "undefined" && !customElements.get("web-portal")) {
-  customElements.define("web-portal", PortalElement);
+if (typeof customElements !== "undefined" && !customElements.get("web-internal-portal")) {
+  customElements.define("web-internal-portal", PortalElement);
 }

package/runtime/raw-html.js

@@ -0,0 +1,33 @@
+//! RawHtml — render a trusted HTML string as light-DOM content.
+//
+//   <RawHtml html={"<pre>…</pre>"} />   // compiles to the built-in `web-internal-raw-html`
+//
+// Used by the MDX front-end for build-time syntax-highlighted code blocks: the
+// highlighted markup is static (no reactivity), so the element just assigns its
+// `html` property to `innerHTML`. The string is treated as trusted — it comes from
+// the compiler, not user input. SSG renders the string inline (server/builtins.js).
+
+export class RawHtmlElement extends HTMLElement {
+  set html(v) {
+    this._html = v;
+    if (this.isConnected) this.innerHTML = v == null ? "" : String(v);
+  }
+  get html() {
+    return this._html;
+  }
+
+  connectedCallback() {
+    // Apply once on connect (the property is set before append during CSR build).
+    if (this._html != null && !this._applied) {
+      this.innerHTML = String(this._html);
+      this._applied = true;
+    }
+  }
+}
+
+// Exported so `import { RawHtml } from "@opentf/web"` resolves; the import side
+// effect registers the element (JSX uses the `web-internal-raw-html` tag).
+export const RawHtml = RawHtmlElement;
+if (typeof customElements !== "undefined" && !customElements.get("web-internal-raw-html")) {
+  customElements.define("web-internal-raw-html", RawHtmlElement);
+}