@opentf/web 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opentf/web",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "The native-first OTF Web runtime — signal-based reactivity and zero-VDOM DOM operations, paired with the IR-based compiler.",
   "type": "module",
   "exports": {

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).
@@ -253,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);
@@ -279,9 +311,45 @@ 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 }
-  let prevKeys = []; // keys in current DOM order, for minimal-move reconciliation
+  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 : [];
@@ -327,7 +395,8 @@ export function bindList(parent, sourceFn, renderItem, keyFn) {
     // 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 || parent;
+    const host = anchor.parentNode;
+    if (!host) return; // anchor detached (list torn down) — nothing to place
     for (let i = nodes.length - 1; i >= 0; i--) {
       if (keep.has(i)) continue;
       const ref = i + 1 < nodes.length ? nodes[i + 1] : anchor;

package/runtime/hydrate.js

@@ -19,6 +19,21 @@
 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;
@@ -37,6 +52,12 @@ export class HydrationMismatch extends Error {
 // 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? */
@@ -44,7 +65,9 @@ export function isHydrating() {
   return _hydrating;
 }
 
-/** Run `fn` with the hydration flag set, restoring the prior value (nesting-safe). */
+/** 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;
@@ -55,6 +78,65 @@ export function runHydration(fn) {
   }
 }
 
+// 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. */
@@ -63,10 +145,16 @@ export function cursor(parent) {
 }
 
 /** Advance past the next node without claiming it (a static text node between
- * dynamic siblings), returning it. */
+ * 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;
-  cur.node = n ? n.nextSibling : null;
+  if (!n || n.nodeType !== TEXT) {
+    throw new HydrationMismatch(`expected static text, found ${describe(n)}`);
+  }
+  cur.node = n.nextSibling;
   return n;
 }
 
@@ -111,6 +199,65 @@ export function claimText(cur) {
   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";

package/runtime/router.js

@@ -15,6 +15,7 @@
 
 import { clearError, reportError } from "../core/errors.js";
 import { signal } from "../core/signals.js";
+import { beginHydration, cursor, endHydration } from "./hydrate.js";
 import { runCleanup, runMount } from "./mount.js";
 
 const isBrowser = typeof window !== "undefined";
@@ -200,6 +201,55 @@ export async function buildRouteNode(match, query = {}) {
   return { node, nodes };
 }
 
+/**
+ * Adopt a matched route's server-rendered DOM (docs/HYDRATION.md §3.4, 2.1c) — the hydrate
+ * analogue of {@link buildRouteNode}. One cursor threads the whole layout chain: the
+ * outermost layout adopts at the container, and each layout hands that cursor to the next at
+ * its `{children}` slot (`props.children` is a thunk that claims the nested route's subtree
+ * and advances the cursor), down to the page. Returns `{ nodes }` (page → … → root) for
+ * lifecycle, or `null` if the page or any layout isn't adoptable (no `hydrateAt` export) — the
+ * caller then falls back to a clean CSR build. A thrown `HydrationMismatch` propagates up,
+ * disposing each layer's partial wiring on the way (each `hydrateAt` has its own guard).
+ */
+export async function hydrateRouteNode(match, query, rootEl) {
+  const props = { params: match.params, query };
+  const pageMod = await resolveModule(match.entry);
+  if (!pageMod || typeof pageMod.hydrateAt !== "function") return null;
+  const chain = layoutChain(match.route);
+  const layoutMods = [];
+  for (const entry of chain) {
+    const m = await resolveModule(entry);
+    if (!m || typeof m.hydrateAt !== "function") return null; // whole chain must be adoptable
+    layoutMods.push(m);
+  }
+
+  // Compose the adopt thunks innermost-first: the page, then each layout wrapping it. Each
+  // thunk pushes its claimed root node, so `nodes` ends up page → … → outermost (the inner
+  // thunk runs — and pushes — during the outer layout's walk, before the outer pushes).
+  const nodes = [];
+  let thunk = (c) => {
+    const n = pageMod.hydrateAt(c, props);
+    nodes.push(n);
+    return n;
+  };
+  for (let i = chain.length - 1; i >= 0; i--) {
+    const layout = layoutMods[i];
+    const inner = thunk;
+    thunk = (c) => {
+      const n = layout.hydrateAt(c, { ...props, children: inner });
+      nodes.push(n);
+      return n;
+    };
+  }
+  thunk(cursor(rootEl)); // outermost adopts at the container; the chain threads inward
+  return { nodes };
+}
+
+/** Resolve a route entry (lazy loader or module namespace) to its module. */
+async function resolveModule(entry) {
+  return typeof entry === "function" ? await entry() : entry;
+}
+
 /**
  * Set the reactive route state directly (no history/render). Used by server render
  * so a page reading `router.pathname`/`params`/`query` resolves to the route being
@@ -284,24 +334,34 @@ export async function navigate(path, replace = false, isPop = false, hydrate = f
   }
 
   // First paint over server-rendered DOM: *adopt* it (hydrate) instead of rebuilding,
-  // when the route module exposes a `hydrate` adopt factory (compiled with the hydrate
-  // target). Only leaf routes (no layout chain) hydrate so far — `{children}`-slot
-  // adoption is a later phase — so anything else falls through to a clean CSR build. A
+  // when the route module exposes a `hydrateAt` adopt factory (compiled with the hydrate
+  // target). `hydrateRouteNode` threads one cursor through the whole layout chain (2.1c);
+  // a route whose page or any layout isn't adoptable returns null → clean CSR build. A
   // hydration mismatch is reported (never silent) and also falls through to a rebuild.
+  //
+  // The hydration flag must be live *before* the route modules are imported: route chunks
+  // are code-split, so `customElements.define` — and the synchronous upgrade of every
+  // server-rendered `<web-*>` host — happens during those imports, before the factories
+  // run. Those upgrading components read `isHydrating()` to adopt their server DOM rather
+  // than build (docs/HYDRATION.md §3.4). `endHydration()` in `finally` makes every
+  // subsequent client navigation build fresh; the CSR fallback below then runs with the
+  // flag cleared, so a rebuilt host builds instead of trying to re-adopt.
   if (hydrate && match) {
+    beginHydration();
     try {
-      const mod = typeof match.entry === "function" ? await match.entry() : match.entry;
-      if (mod && typeof mod.hydrate === "function" && layoutChain(match.route).length === 0) {
-        const query = Object.fromEntries(url.searchParams);
-        const node = mod.hydrate(rootEl, { params: match.params, query });
-        currentNodes = [node];
-        runMount(node);
+      const query = Object.fromEntries(url.searchParams);
+      const adopted = await hydrateRouteNode(match, query, rootEl);
+      if (adopted) {
+        currentNodes = adopted.nodes;
+        for (const n of adopted.nodes) runMount(n); // onMount for page + every layout
         clearError({ phase: "route" });
         return;
       }
     } catch (e) {
       reportError(e, { phase: "hydrate", path: url.pathname });
       // fall through to a clean CSR build below
+    } finally {
+      endHydration();
     }
   }
 

package/server/render.js

@@ -15,14 +15,16 @@ import {
   setRouteState,
 } from "../runtime/router.js";
 import { resolveMetadata } from "./head.js";
+import { beginHydrationCollect, endHydrationCollect } from "./ssg-runtime.js";
 
 /**
- * Render `pathname` to `{ html, metadata, status }`: the markup for inside `#app`,
- * the resolved SEO metadata (for the `<head>`), and an HTTP `status` (200 when the
- * path matched a real route, 404 when it fell back to the registered 404 page — the
- * SSR server uses it; SSG ignores it). `params` (from `getStaticPaths`) override the
- * matched route's params for dynamic routes. Returns `null` if there's no match and
- * no 404 page.
+ * Render `pathname` to `{ html, metadata, status, hydration }`: the markup for inside
+ * `#app`, the resolved SEO metadata (for the `<head>`), an HTTP `status` (200 when the
+ * path matched a real route, 404 when it fell back to the registered 404 page — the SSR
+ * server uses it; SSG ignores it), and `hydration` — the JSON island-props payload the
+ * toolchain embeds so the client resumes from rich data (`""` when nothing needs it).
+ * `params` (from `getStaticPaths`) override the matched route's params for dynamic
+ * routes. Returns `null` if there's no match and no 404 page.
  */
 export async function renderRoute(pathname, params = null, search = "") {
   const real = matchRoute(pathname);
@@ -36,6 +38,10 @@ export async function renderRoute(pathname, params = null, search = "") {
 
   const query = Object.fromEntries(new URLSearchParams(search));
   const props = { params: match.params, query };
+
+  // Collect each island's rich props while the tree renders (ssgComponent records them
+  // and stamps `data-h` ids), then serialize the payload for the shell.
+  beginHydrationCollect();
   let html = (await resolveFactory(match.entry))(props);
 
   // Wrap with layouts, most-specific inward to root outermost.
@@ -44,6 +50,7 @@ export async function renderRoute(pathname, params = null, search = "") {
     const layout = await resolveFactory(chain[i]);
     html = layout({ ...props, children: html });
   }
+  const hydration = endHydrationCollect();
 
   const metadata = await resolveMetadata({
     route: match.route,
@@ -51,7 +58,7 @@ export async function renderRoute(pathname, params = null, search = "") {
     params: match.params,
     query,
   });
-  return { html, metadata, status: real ? 200 : 404 };
+  return { html, metadata, status: real ? 200 : 404, hydration };
 }
 
 /** Back-compat / convenience: render just the `#app` markup for `pathname`. */

package/server/ssg-runtime.js

@@ -20,6 +20,53 @@ export function defineSSG(tag, render) {
   registry[tag] = render;
 }
 
+// ── hydration props collector (compiler-driven data hydration) ────────────────
+// The lossy path is passing rich props through string attributes. Instead, each
+// server-rendered island gets a `data-h` id and its JSON-safe props are recorded into a
+// single payload the shell embeds as `<script type="application/json">`. At upgrade the
+// client component initializes its prop *signals* from those real JS values (objects,
+// arrays, numbers) — not from `getAttribute` — so islands resume with correct data, with
+// no flash and no dependence on a parent walk re-applying props. `renderRoute` brackets a
+// render with `beginHydrationCollect()` / `endHydrationCollect()`.
+let _collect = null;
+
+/** Start collecting per-island hydration props for one render. */
+export function beginHydrationCollect() {
+  _collect = [];
+}
+
+/**
+ * Finish collecting and return the payload as a JSON string ("" when nothing needs
+ * hydration). `<` is escaped so a prop value can never break out of the surrounding
+ * `<script>` (a `</script>` / `<!--` injection).
+ */
+export function endHydrationCollect() {
+  const data = _collect;
+  _collect = null;
+  if (!data || data.length === 0) return "";
+  return JSON.stringify(data).replace(/</g, "\\u003c");
+}
+
+/**
+ * Record an island's JSON-safe props, returning its hydration id — or `null` when not
+ * collecting, or when nothing serializes. A JSON round-trip drops functions (event
+ * callbacks are client-only — applied by the parent walk, invisible so no flash),
+ * `undefined`, and anything cyclic/DOM/signal-shaped, so only plain data crosses.
+ */
+function collectHydrationProps(props) {
+  if (!_collect || props == null || typeof props !== "object") return null;
+  let safe;
+  try {
+    safe = JSON.parse(JSON.stringify(props));
+  } catch {
+    return null; // cyclic / non-serializable → client falls back to attributes/defaults
+  }
+  if (!safe || typeof safe !== "object" || Object.keys(safe).length === 0) return null;
+  const id = _collect.length;
+  _collect.push(safe);
+  return id;
+}
+
 /** Escape text content for HTML. */
 export function escapeHtml(s) {
   return String(s).replace(/[&<>]/g, (c) => (c === "&" ? "&amp;" : c === "<" ? "&lt;" : "&gt;"));
@@ -104,9 +151,13 @@ export function ssgComponent(tag, props, children) {
     inner = ""; // fail soft (client renders/handles it)
   }
   // Stamp the stable styling hook on the host (mirrors CSR's `classList.add`) so
-  // tag-hashed components are still styleable by a readable class name.
+  // tag-hashed components are still styleable by a readable class name, plus the
+  // hydration id (`data-h`) keying this island's rich props in the payload (if any).
   const cls = render && render.hostClass;
-  return cls ? `<${tag} class="${cls}">${inner}</${tag}>` : `<${tag}>${inner}</${tag}>`;
+  const id = collectHydrationProps(props);
+  let attrs = cls ? ` class="${cls}"` : "";
+  if (id != null) attrs += ` data-h="${id}"`;
+  return `<${tag}${attrs}>${inner}</${tag}>`;
 }
 
 export { VOID };