@vesk/runtime 0.2.25 → 0.2.27

package/dist/hydrate.js

@@ -51,11 +51,34 @@ const CLAIMED_ATTR = 'data-vsk-claimed';
 export function setHydrateDevMode(enabled) {
     __hydrateDevMode = enabled;
 }
+let __hydrateStrict = false;
+let __mismatchHandler = null;
+export function setHydrateStrict(enabled) {
+    __hydrateStrict = enabled;
+}
+export function isHydrateStrict() {
+    return __hydrateStrict;
+}
+export function onHydrationMismatch(handler) {
+    __mismatchHandler = handler;
+}
 function devWarn(message) {
     if (__hydrateDevMode && typeof console !== 'undefined') {
         console.warn('[vesk-hydrate] ' + message);
     }
 }
+function reportMiss(kind, detail, loud) {
+    if (__mismatchHandler) {
+        try {
+            __mismatchHandler({ kind, detail });
+        }
+        catch {
+            // Telemetry must never break rendering.
+        }
+    }
+    if (loud)
+        devWarn(`${kind}: ${detail}`);
+}
 function stampClaimed(el) {
     if (__hydrateDevMode) {
         try {
@@ -69,38 +92,206 @@ function stampClaimed(el) {
 }
 // Strip the direct text children of a claimed element. Static text inside a
 // claimed subtree is re-created client-side as fresh text nodes, so the
-// SSR-serialized text nodes are dropped to avoid duplicates.
+// SSR-serialized text nodes are dropped to avoid duplicates. Before dropping,
+// stash the concatenated text as `__vsk_ssrText`: hydrate-mode codegen
+// initializes a sole dynamic text child from this snapshot, so a missed effect
+// degrades to stale (visible) text instead of an empty element (Hydrate-Todo
+// A5). Always set ('' when none) so consumers never branch on presence.
 function stripDirectTextNodes(el) {
+    let text = '';
     for (let i = el.childNodes.length - 1; i >= 0; i--) {
-        if (el.childNodes[i].nodeType === 3)
-            el.childNodes[i].remove();
+        const c = el.childNodes[i];
+        if (c.nodeType === 3) {
+            try {
+                text = String(c.textContent ?? '') + text;
+            }
+            catch {
+                // ignore unreadable nodes, still remove below
+            }
+            c.remove();
+        }
     }
+    el.__vsk_ssrText = text;
+}
+// After a claim, a claimed element may still contain direct SSR element
+// children: component-boundary wrappers (`display:contents` spans) and static
+// markup that hydration skips. Fresh text/dynamic nodes re-created client-side
+// must be inserted BEFORE these residues at their SSR positions — appending at
+// the end would reorder mixed text + component children (e.g. a label that
+// reads `<span>compiler-first framework · <VersionBadge /></span>`). Store the
+// residue list (in DOM order) on the element so codegen can address it.
+function captureSsrElementChildren(el) {
+    el.__vsk_ssrEls = Array.prototype.slice.call(el.children);
+}
+function normText(el) {
+    try {
+        return (el.textContent || '').replace(/\s+/g, ' ').trim();
+    }
+    catch {
+        return '';
+    }
+}
+function collectElements(rootEl) {
+    const out = [];
+    (function walk(n) {
+        const kids = n.childNodes;
+        for (let i = 0; i < kids.length; i++) {
+            const c = kids[i];
+            if (c.nodeType === 1) {
+                out.push(c);
+                walk(c);
+            }
+        }
+    })(rootEl);
+    return out;
 }
 /**
- * Dev-mode check that every `<!--vsk-->` marker in `container` has been
- * claimed by the most recent full hydration pass. Markers that remain belong
- * to SSR regions the client never rendered (or rendered differently) — orphaned
- * phantom content that will never be cleaned up. Returns `false` and warns when
- * any such marker survives. Runs automatically at the end of `hydrate`,
- * `hydrateInitial`, and every hydration strategy's completion.
+ * Twin scan (heuristic): an adopted element sitting directly beside an
+ * unadopted same-tag element with identical non-empty text is the signature of
+ * a claim miss that twinned — the SSR node survived next to its fresh copy.
+ * Either order (SSR-then-fresh or fresh-then-SSR) counts. Purely static
+ * identical siblings (both unclaimed) are NOT twins; neither are two adopted
+ * nodes.
  */
-export function assertFullyHydrated(container) {
+function scanTwins(container) {
+    let count = 0;
+    const samples = [];
+    for (const el of collectElements(container)) {
+        const prev = el.previousElementSibling;
+        if (!prev || prev.tagName !== el.tagName)
+            continue;
+        const t = normText(el);
+        if (!t || t !== normText(prev))
+            continue;
+        let a = false;
+        let b = false;
+        try {
+            a = el.hasAttribute(CLAIMED_ATTR);
+            b = prev.hasAttribute(CLAIMED_ATTR);
+        }
+        catch {
+            continue;
+        }
+        if (a !== b) {
+            count++;
+            if (samples.length < 3) {
+                try {
+                    samples.push(`<${el.tagName.toLowerCase()}> "${t.slice(0, 60)}"`);
+                }
+                catch {
+                    // ignore sample failures
+                }
+            }
+        }
+    }
+    return { count, samples };
+}
+/**
+ * Structured audit of the most recent full hydration pass over `container`.
+ * Counts unclaimed `<!--vsk-->` markers (SSR regions the client never
+ * rendered) and twin elements (SSR node surviving beside its fresh copy).
+ * In strict mode, removes genuine orphans — marker plus its SSR element — now
+ * that every owner had its chance to claim. Claim-time backoff is untouched:
+ * mid-walk removal would steal elements from their real owners.
+ */
+export function auditHydration(container) {
     let unclaimed = 0;
     let sample = '';
+    const orphans = [];
+    const orphanNames = [];
     const walker = document.createTreeWalker(container, _SHOW_COMMENT, {
-        acceptNode: (node) => (node.textContent === 'vsk' ? _FILTER_ACCEPT : _FILTER_SKIP),
+        acceptNode: (node) => (isVskMarkerText(node.textContent) ? _FILTER_ACCEPT : _FILTER_SKIP),
     });
     while (walker.nextNode()) {
-        const el = walker.currentNode.nextElementSibling;
+        const c = walker.currentNode;
+        const el = c.nextElementSibling;
         if (el && underClaimedAncestor(el, container))
             continue;
         unclaimed++;
+        orphans.push(c);
+        // B1: name the orphan — typed component identity from the marker, or
+        // the live element tag for bare markers.
+        if (orphanNames.length < 5) {
+            const parsed = parseVskMarker(c.textContent);
+            const id = parsed && parsed.identity ? `<!--vsk:${parsed.identity}-->` : null;
+            let tag = '';
+            try {
+                tag = el && el.tagName ? `<${el.tagName.toLowerCase()}>` : '(no element)';
+            }
+            catch {
+                tag = '(unreadable)';
+            }
+            orphanNames.push(id ? `${id} before ${tag}` : `bare <!--vsk--> before ${tag} (untyped)`);
+        }
         if (!sample && container.outerHTML)
             sample = String(container.outerHTML).slice(0, 800);
     }
+    const twinRes = scanTwins(container);
+    const issues = [];
     if (unclaimed > 0) {
-        devWarn(`${unclaimed} hydration marker${unclaimed === 1 ? '' : 's'} never claimed; ` +
-            `SSR and client markup diverge. Container fragment:\n${sample}`);
+        issues.push({
+            kind: 'leftover-marker',
+            detail: `${unclaimed} hydration marker${unclaimed === 1 ? '' : 's'} never claimed; ` +
+                `SSR and client markup diverge. Orphans: ${orphanNames.join(', ')}.`,
+        });
+    }
+    for (const s of twinRes.samples) {
+        issues.push({ kind: 'twin', detail: `possible hydration twin: ${s}` });
+    }
+    if (twinRes.count > twinRes.samples.length) {
+        issues.push({
+            kind: 'twin',
+            detail: `${twinRes.count - twinRes.samples.length} further possible twin(s) (samples capped)`,
+        });
+    }
+    if (__hydrateStrict) {
+        for (const c of orphans) {
+            try {
+                const el = c.nextElementSibling;
+                if (el && underClaimedAncestor(el, container))
+                    continue;
+                if (el)
+                    el.remove();
+                c.remove();
+            }
+            catch {
+                // Best-effort repair; the report above already recorded it.
+            }
+        }
+    }
+    if (__mismatchHandler) {
+        for (const issue of issues) {
+            try {
+                __mismatchHandler(issue);
+            }
+            catch {
+                // Telemetry must never break rendering.
+            }
+        }
+    }
+    return {
+        ok: unclaimed === 0 && twinRes.count === 0,
+        unclaimed,
+        twins: twinRes.count,
+        issues,
+        sample,
+    };
+}
+/**
+ * Dev-mode check that every `<!--vsk-->` marker in `container` has been
+ * claimed by the most recent full hydration pass. Markers that remain belong
+ * to SSR regions the client never rendered (or rendered differently) — orphaned
+ * phantom content that will never be cleaned up. Returns `false` and warns when
+ * any such marker survives. Runs automatically at the end of `hydrate`,
+ * `hydrateInitial`, and every hydration strategy's completion.
+ */
+export function assertFullyHydrated(container) {
+    const report = auditHydration(container);
+    if (!report.ok) {
+        devWarn(`${report.unclaimed} hydration marker${report.unclaimed === 1 ? '' : 's'} never claimed; ` +
+            `SSR and client markup diverge.` +
+            (report.twins > 0 ? ` ${report.twins} possible twin(s) detected.` : '') +
+            ` Container fragment:\n${report.sample}`);
         return false;
     }
     return true;
@@ -112,18 +303,77 @@ function underClaimedAncestor(el, container) {
     }
     return false;
 }
+function markerIdentity(comment) {
+    try {
+        const parsed = parseVskMarker(comment.textContent);
+        return parsed ? parsed.identity : null;
+    }
+    catch {
+        return null;
+    }
+}
+function describeMarker(tm) {
+    return tm.identity ? `<!--vsk:${tm.identity}-->` : '<!--vsk-->';
+}
 const _SHOW_COMMENT = 128;
 export const _FILTER_ACCEPT = 1;
 export const _FILTER_SKIP = 2;
+// Keyed marker identity (Hydrate-Todo B1 + keyed markers). Server codegen
+// types every boundary: components (`<!--vsk:c:Name-->`), static subtrees
+// (`<!--vsk:t:tag-->`). No regex here either (runtime text-processing rule):
+// exact match or the `vsk:` prefix. Bare `<!--vsk-->` still adopts
+// positionally but is reported as `untyped-marker` — no exceptions.
+export function isVskMarkerText(text) {
+    if (text === 'vsk')
+        return true;
+    if (typeof text !== 'string' || text.length < 4)
+        return false;
+    return text.charAt(0) === 'v' && text.charAt(1) === 's' && text.charAt(2) === 'k' && text.charAt(3) === ':';
+}
+export function parseVskMarker(text) {
+    if (text === 'vsk')
+        return { identity: null };
+    if (!isVskMarkerText(text))
+        return null;
+    const rest = text.slice(4);
+    return { identity: rest === '' ? null : rest };
+}
 export function collectVskMarkers(container) {
     const markers = [];
     const walker = document.createTreeWalker(container, _SHOW_COMMENT, {
-        acceptNode: (node) => (node.textContent === 'vsk' ? _FILTER_ACCEPT : _FILTER_SKIP),
+        acceptNode: (node) => (isVskMarkerText(node.textContent) ? _FILTER_ACCEPT : _FILTER_SKIP),
     });
     while (walker.nextNode())
         markers.push(walker.currentNode);
     return markers;
 }
+/**
+ * Keyed-marker verification at adopt time. A `t:tag` marker must precede that
+ * tag — anything else is SSR/HTML-parser skew (e.g. a `<p>` auto-close moving
+ * the marker), reported deterministically instead of drifting. A bare marker
+ * still adopts positionally but is reported: every emission site types its
+ * markers, so bare means a missed site or stale output. No exceptions.
+ */
+function checkMarkerIdentity(marker, el) {
+    let identity = null;
+    try {
+        const parsed = parseVskMarker(marker.textContent);
+        identity = parsed ? parsed.identity : null;
+    }
+    catch {
+        identity = null;
+    }
+    if (identity === null) {
+        reportMiss('untyped-marker', `adopted a bare <!--vsk--> marker before <${el.tagName.toLowerCase()}>; all emission sites must type their markers.`, __hydrateDevMode);
+        return;
+    }
+    if (identity.charAt(0) === 't' && identity.charAt(1) === ':') {
+        const expected = identity.slice(2).toLowerCase();
+        if (expected !== '' && expected !== el.tagName.toLowerCase()) {
+            reportMiss('marker-skew', `marker <!--vsk:${identity}--> precedes <${el.tagName.toLowerCase()}> — SSR/HTML-parser skew; adopting the live element.`, __hydrateDevMode);
+        }
+    }
+}
 function adoptElement(marker, tag) {
     const el = marker.nextElementSibling;
     if (!el) {
@@ -137,8 +387,26 @@ function adoptElement(marker, tag) {
     // defect: the layout's missing conditional span claim stole the h1 marker).
     if (tag && el.tagName.toLowerCase() !== tag)
         return null;
+    checkMarkerIdentity(marker, el);
     marker.remove();
     stripDirectTextNodes(el);
+    captureSsrElementChildren(el);
+    stampClaimed(el);
+    return el;
+}
+// Like adoptElement but preserves direct text children. Used by static-component
+// stubs whose SSR content is kept as-is (no client-side re-rendering).
+function adoptElementRaw(marker, tag) {
+    const el = marker.nextElementSibling;
+    if (!el) {
+        marker.remove();
+        return null;
+    }
+    if (tag && el.tagName.toLowerCase() !== tag)
+        return null;
+    checkMarkerIdentity(marker, el);
+    marker.remove();
+    captureSsrElementChildren(el);
     stampClaimed(el);
     return el;
 }
@@ -146,13 +414,59 @@ class WalkerEngine {
     root;
     markers;
     idx = 0;
+    // Elements already adopted by an earlier claim in this walk. Marker-only SSR
+    // can leave TWO keyed marks on the same element (the call-site marker and
+    // the callee's own root marker — e.g. Link self-prefixes `<!--vsk:c:Link-->`
+    // and the shared walker claims its call-site marker), and a claim must never
+    // adopt the same node twice: double-adoption strips its SSR text a second
+    // time and shells the cursor so every later claim misses its element.
+    adopted = new WeakSet();
     constructor(root, markers) {
         this.root = root;
-        this.markers = markers.map((c) => ({ comment: c, state: 'unclaimed' }));
+        this.markers = markers.map((c) => ({ comment: c, state: 'unclaimed', identity: markerIdentity(c) }));
     }
     done() {
         return this.idx >= this.markers.length;
     }
+    // A marker whose `nextElementSibling` was already adopted is a dead alias of
+    // a live claim point (double-marker collision). Retire it and move on so the
+    // cursor never claims a node twice.
+    isAlreadyAdopted(tm, el) {
+        if (el !== null && this.adopted.has(el)) {
+            tm.state = 'claimed';
+            this.idx++;
+            // Physically retire the alias too: like `adoptElement`, a spent
+            // marker never stays in the live DOM.
+            tm.comment.remove();
+            return true;
+        }
+        return false;
+    }
+    recordAdopted(el) {
+        this.adopted.add(el);
+    }
+    // Marker-only SSR can stack several keyed marks before ONE element
+    // (call-site marker + the callee's own root marker). The FIRST claim adopts
+    // the element; the alias markers that immediately follow it are dead — they
+    // point at an already-claimed node and must be physically retired so the
+    // canary never counts them and a trailing alias never lingers in the DOM.
+    retireAliases(el) {
+        let i = this.idx;
+        while (i < this.markers.length) {
+            const tm = this.markers[i];
+            if (tm.state === 'claimed') {
+                i++;
+                continue;
+            }
+            if (tm.comment.nextElementSibling === el) {
+                tm.state = 'claimed';
+                tm.comment.remove();
+                i++;
+                continue;
+            }
+            break;
+        }
+    }
     nextElement(tag) {
         while (this.idx < this.markers.length) {
             const tm = this.markers[this.idx];
@@ -161,6 +475,8 @@ class WalkerEngine {
                 continue;
             }
             const el = tm.comment.nextElementSibling;
+            if (this.isAlreadyAdopted(tm, el))
+                continue;
             if (tag && el && el.tagName.toLowerCase() !== tag) {
                 // SSR rendered a different tag than this claim wants. Leave the
                 // marker AND the element untouched and back off without moving
@@ -168,6 +484,8 @@ class WalkerEngine {
                 // consuming it here would strip its SSR text, stamp a claim on
                 // a node this render does not own, and drift every later claim
                 // into fresh-node fallback (the empty `/store/widget` h1).
+                // The skipped marker's B1 identity names the divergence point.
+                reportMiss('tag-mismatch', `claim wanted <${tag}> but the cursor holds ${describeMarker(tm)} before <${el.tagName.toLowerCase()}>; backing off for its real owner.`, false);
                 break;
             }
             this.idx++;
@@ -182,81 +500,211 @@ class WalkerEngine {
                 tm.state = 'claimed';
                 break;
             }
+            this.recordAdopted(adopted);
+            this.retireAliases(adopted);
             tm.state = 'claimed';
             return adopted;
         }
         // Every claim parked itself — either because the render asked for more
         // elements than SSR provided, or because the SSR element tag did not
-        // match the claim. Best effort: build a fresh element and warn in dev.
+        // match the claim. Best effort: build a fresh element and report.
         //
-        // The warning is scoped to walks that still hold unconsumed markers
+        // The report is scoped to walks that still hold unconsumed markers
         // (`this.idx < this.markers.length`): that is the signature of a real
         // SSR/client structural divergence — a marker is ahead of the cursor but
         // the claim could not adopt it (wrong tag). Once the walker is exhausted
         // every further `nextElement` is a post-hydration re-render (reactive
         // loop/if blocks re-running after the interval or an event) legitimately
-        // building fresh nodes — silent, so a typing `for` loop does not spam the
-        // console every tick. SPA/client-only renders keep empty marker lists on
-        // temp roots and never warn.
-        if (__hydrateDevMode && this.root && this.idx < this.markers.length) {
-            devWarn(`hydration claim missed <${tag || 'element'}> (${this.markers.length - this.idx} markers unconsumed); the client rendered more or different content than SSR.` +
-                (this.root.outerHTML ? ` Fragment:\n${String(this.root.outerHTML).slice(0, 800)}` : ''));
+        // building fresh nodes — telemetry-only, so a typing `for` loop does
+        // not spam the console every tick. SPA/client-only renders keep empty
+        // marker lists on temp roots and never warn.
+        const hasUnconsumed = this.root !== null && this.idx < this.markers.length;
+        // Name the skipped cursor marker (B1): the divergence point is no
+        // longer anonymous.
+        let skipped = '';
+        if (hasUnconsumed) {
+            for (let s = this.idx; s < this.markers.length; s++) {
+                if (this.markers[s].state === 'claimed')
+                    continue;
+                skipped = ` skipped ${describeMarker(this.markers[s])}`;
+                break;
+            }
         }
+        reportMiss(hasUnconsumed ? 'tag-mismatch' : 'exhausted', `hydration claim missed <${tag || 'element'}> (${this.markers.length - this.idx} markers unconsumed${skipped}); the client rendered more or different content than SSR.` +
+            (this.root && this.root.outerHTML ? ` Fragment:\n${String(this.root.outerHTML).slice(0, 800)}` : ''), hasUnconsumed && __hydrateDevMode);
         return document.createElement(tag || 'div');
     }
+    claimOnly(tag) {
+        while (this.idx < this.markers.length) {
+            const tm = this.markers[this.idx];
+            if (tm.state === 'claimed') {
+                this.idx++;
+                continue;
+            }
+            const el = tm.comment.nextElementSibling;
+            if (this.isAlreadyAdopted(tm, el))
+                continue;
+            if (tag && el && el.tagName.toLowerCase() !== tag) {
+                reportMiss('tag-mismatch', `static claim wanted <${tag}> but the cursor holds ${describeMarker(tm)} before <${el.tagName.toLowerCase()}>; backing off for its real owner.`, false);
+                break;
+            }
+            this.idx++;
+            const adopted = adoptElementRaw(tm.comment, tag);
+            if (adopted === null) {
+                tm.state = 'claimed';
+                break;
+            }
+            this.recordAdopted(adopted);
+            this.retireAliases(adopted);
+            tm.state = 'claimed';
+            return adopted;
+        }
+        // Static-stub fallback twins exactly like nextElement: the SSR node
+        // stays while a fresh node is built. Same reporting contract.
+        const hasUnconsumed = this.root !== null && this.idx < this.markers.length;
+        reportMiss(hasUnconsumed ? 'tag-mismatch' : 'exhausted', `hydration static claim missed <${tag || 'element'}> (${this.markers.length - this.idx} markers unconsumed); the client rendered more or different content than SSR.`, hasUnconsumed && __hydrateDevMode);
+        return document.createElement(tag || 'div');
+    }
+    retireDetached() {
+        while (this.idx < this.markers.length) {
+            const tm = this.markers[this.idx];
+            if (tm.state === 'claimed') {
+                this.idx++;
+                continue;
+            }
+            const c = tm.comment;
+            // A marker whose comment is no longer attached cannot belong to any
+            // element this walker can claim, so its SSR content was removed by
+            // the render (e.g. Link's replaceChildren). Skip it and keep the
+            // cursor document-ordered for the next live marker.
+            if (!c || !c.parentNode) {
+                tm.state = 'claimed';
+                this.idx++;
+                continue;
+            }
+            break;
+        }
+    }
     subWalker(rootEl) {
-        const subMarkers = this.markers.slice(this.idx).filter((m) => {
-            if (m.state === 'claimed')
-                return false;
-            if (rootEl === m.comment)
-                return true;
-            if (!rootEl || !m.comment)
-                return false;
-            if (typeof rootEl.contains === 'function')
-                return rootEl.contains(m.comment);
-            return false;
-        });
-        this.idx += subMarkers.length;
-        for (const m of subMarkers)
-            m.state = 'claimed';
-        // A component's SSR content always carries interior `<!--vsk-->` markers
-        // that the child's own hydrator claims. Exception: plain JS components
-        // (lucide icons etc.) render inside the compiler's boundary wrapper
-        // (`<!--vsk--><span style="display:contents">`) with NO interior markers.
-        // An empty marker list would send the child to `nextElement`'s fresh-node
-        // fallback, orphaning the SSR root inside the claimed wrapper (duplicate
-        // icons, non-reactive if/else blocks after hydration). Fall back to
-        // positional claiming of the wrapper's element children so those
-        // components adopt their SSR root in place, exactly like `.vsk` roots do.
-        if (subMarkers.length === 0 && rootEl && rootEl.tagName === 'SPAN' && rootEl.style && rootEl.style.display === 'contents') {
-            return createHydrateChildWalker(rootEl);
+        // Ownership TRANSFER (Hydrate-Todo B3): the child's markers are
+        // spliced out of this walk — exactly one engine owns each marker, so
+        // no cursor arithmetic can drift and no shared refs can double-claim.
+        // The old `idx += count` assumed document order == marker order.
+        const owned = [];
+        const kept = [];
+        for (const m of this.markers) {
+            let mine = false;
+            if (m.state !== 'claimed') {
+                if (rootEl === m.comment)
+                    mine = true;
+                else if (rootEl && m.comment && typeof rootEl.contains === 'function')
+                    mine = rootEl.contains(m.comment);
+            }
+            if (mine) {
+                m.state = 'claimed';
+                owned.push(m);
+            }
+            else {
+                kept.push(m);
+            }
+        }
+        this.markers = kept;
+        if (this.idx > this.markers.length)
+            this.idx = this.markers.length;
+        return new WalkerEngine(rootEl, owned.map((m) => m.comment));
+    }
+    // Retire every unclaimed marker in the whole walk that points at `el`.
+    // Used after a cross-position adopt (relocate): the adopted node moves to
+    // the cursor, so alias markers stacked at its old station would otherwise
+    // dangle — pointing at its successor and misaligning later claims.
+    retireAliasesOf(el) {
+        for (const tm of this.markers) {
+            if (tm.state !== 'claimed' && tm.comment.nextElementSibling === el) {
+                tm.state = 'claimed';
+                tm.comment.remove();
+            }
         }
-        return new WalkerEngine(rootEl, subMarkers.map((m) => m.comment));
     }
-    claimByKey(key) {
+    adoptKeyedElement(tm, el) {
+        tm.state = 'claimed';
+        this.recordAdopted(el);
+        checkMarkerIdentity(tm.comment, el);
+        tm.comment.remove();
+        stripDirectTextNodes(el);
+        captureSsrElementChildren(el);
+        stampClaimed(el);
+        return { el };
+    }
+    claimByKey(key, options) {
         const strKey = String(key);
         // Strict positional claim: the item claims the cursor's marker. Interior
         // markers of the previously-claimed item are consumed by that item's own
         // render, so by the time we get here the cursor points at this item's
         // SSR root. Only EXACT ordering SSR == client is claimed; divergence
-        // renders the item fresh at the region tail (canary reports the ghost).
+        // renders the item fresh at the region tail (canary reports the ghost)
+        // unless `relocate` upgrades the miss to adopt+move (Hydrate-Todo A4).
         for (let i = this.idx; i < this.markers.length; i++) {
             const tm = this.markers[i];
             if (tm.state === 'claimed')
                 continue;
             const el = tm.comment.nextElementSibling;
+            if (this.isAlreadyAdopted(tm, el))
+                continue;
             if (el && el.getAttribute('data-vsk-key') === strKey) {
-                tm.state = 'claimed';
-                tm.comment.remove();
-                stripDirectTextNodes(el);
-                stampClaimed(el);
-                return { el };
+                const claim = this.adoptKeyedElement(tm, el);
+                this.retireAliases(el);
+                return claim;
             }
             // First unclaimed marker is not this item — don't scan past it.
+            if (options && options.relocate) {
+                const moved = this.relocateByKey(strKey, tm);
+                if (moved)
+                    return moved;
+            }
+            // If the key exists later in the region this is a genuine SSR↔client
+            // reorder; without relocate the item renders fresh at the tail
+            // while its SSR twin rots. Report it so reorder divergence is
+            // visible instead of silent.
+            if (this.peekKey(strKey) !== null) {
+                reportMiss('key-reorder', `keyed item "${strKey}" is not at the cursor; SSR order and client order diverge — item renders fresh, SSR twin orphaned.`, __hydrateDevMode);
+            }
             return null;
         }
         return null;
     }
+    // A4 adopt+move: find `key` anywhere later in the walk, adopt it in place,
+    // then move it to the cursor (`anchor`, the mismatching marker) so region
+    // order converges to client order with node identity preserved. The cursor
+    // itself does not advance — skipped markers still belong to their owners.
+    // Returns null when the key has no live SSR node (genuinely new item).
+    relocateByKey(strKey, anchor) {
+        for (let j = this.idx; j < this.markers.length; j++) {
+            const tm = this.markers[j];
+            if (tm.state === 'claimed')
+                continue;
+            const el = tm.comment.nextElementSibling;
+            if (!el || this.adopted.has(el))
+                continue;
+            if (el.getAttribute('data-vsk-key') !== strKey)
+                continue;
+            const parent = el.parentNode;
+            const anchorParent = anchor.comment.parentNode;
+            if (!parent || parent !== anchorParent)
+                continue;
+            const claim = this.adoptKeyedElement(tm, el);
+            this.retireAliasesOf(el);
+            try {
+                parent.insertBefore(el, anchor.comment);
+            }
+            catch {
+                // A failed move must not strand an adopted node: the claim
+                // stands (identity preserved) and order falls back to markers.
+            }
+            reportMiss('key-reorder', `keyed item "${strKey}" adopted out of position and moved into place; SSR order and client order diverged.`, false);
+            return claim;
+        }
+        return null;
+    }
     peekKey(key) {
         const strKey = String(key);
         // Non-consuming scan across EVERY remaining unclaimed marker: used to
@@ -267,6 +715,8 @@ class WalkerEngine {
             if (tm.state === 'claimed')
                 continue;
             const el = tm.comment.nextElementSibling;
+            if (el && this.adopted.has(el))
+                continue;
             if (el && el.getAttribute('data-vsk-key') === strKey)
                 return el;
         }
@@ -290,6 +740,18 @@ export function createHydrateChildWalker(parentEl) {
                 const child = children[childIdx++];
                 if (!tag || child.tagName.toLowerCase() === tag) {
                     stripDirectTextNodes(child);
+                    captureSsrElementChildren(child);
+                    stampClaimed(child);
+                    return child;
+                }
+            }
+            return document.createElement(tag || 'div');
+        },
+        claimOnly(tag) {
+            while (childIdx < children.length) {
+                const child = children[childIdx++];
+                if (!tag || child.tagName.toLowerCase() === tag) {
+                    captureSsrElementChildren(child);
                     stampClaimed(child);
                     return child;
                 }
@@ -299,6 +761,9 @@ export function createHydrateChildWalker(parentEl) {
         subWalker(rootEl) {
             return createHydrateChildWalker(rootEl);
         },
+        retireDetached() {
+            // Child-walkers hold no marker list; nothing to sweep.
+        },
     };
 }
 export function hydrate(container, componentFn, props) {
@@ -307,45 +772,103 @@ export function hydrate(container, componentFn, props) {
     assertFullyHydrated(container);
     return result;
 }
-// ---------------------------------------------------------------------------
-// Viewport viewport hydration: markers below the fold are held until the
-// observer reports them intersecting. The hold is tracked explicitly (no
-// `vsk-hold` text mutation, no `_observed` monkey-patch) so the marker state
-// machine stays unambiguous and `assertFullyHydrated` can count held markers.
-// ---------------------------------------------------------------------------
-export function hydrateViewport(container, componentFn, props, rootMargin = 500) {
-    if (document.readyState !== 'complete') {
-        return new Promise((resolve) => {
-            const onLoad = () => {
-                window.removeEventListener('load', onLoad);
-                resolve(hydrateViewport(container, componentFn, props, rootMargin));
-            };
-            window.addEventListener('load', onLoad);
-        });
+export function bumpNavEpoch() {
+    try {
+        const g = globalThis;
+        const next = (g.__vesk_nav_epoch || 0) + 1;
+        g.__vesk_nav_epoch = next;
+        return next;
     }
-    const allMarkers = collectVskMarkers(container);
-    const viewportMarkers = [];
-    const deferredMarkers = [];
-    for (const marker of allMarkers) {
-        const el = marker.nextElementSibling;
-        if (!el) {
-            deferredMarkers.push(marker);
-            continue;
-        }
-        const rect = el.getBoundingClientRect();
-        if (rect.bottom < -rootMargin || rect.top > window.innerHeight + rootMargin) {
-            deferredMarkers.push(marker);
+    catch {
+        return 0;
+    }
+}
+function navEpoch() {
+    try {
+        return globalThis.__vesk_nav_epoch || 0;
+    }
+    catch {
+        return 0;
+    }
+}
+function batchAlive(container, epoch, isCurrent) {
+    try {
+        if (!container.isConnected)
+            return false;
+    }
+    catch {
+        return false;
+    }
+    if (isCurrent) {
+        try {
+            return isCurrent() !== false;
         }
-        else {
-            viewportMarkers.push(marker);
+        catch {
+            return false;
         }
     }
-    const held = new Set(deferredMarkers);
-    const viewportWalker = createHydrateWalker(container, viewportMarkers);
-    runInHydrateBlock(() => componentFn(props || {}, new Map(), viewportWalker));
-    if (deferredMarkers.length > 0) {
-        return new Promise((resolve) => {
+    return navEpoch() === epoch;
+}
+export function hydrateViewport(container, componentFn, props, rootMargin = 500, options = {}) {
+    const epoch = navEpoch();
+    const isCurrent = options.isCurrent;
+    let cancelled = false;
+    let cancelFn = () => { };
+    const promise = new Promise((resolve) => {
+        const finish = () => {
+            cancelled = true;
+            cancelFn = () => { };
+            resolve();
+        };
+        cancelFn = finish;
+        if (!batchAlive(container, epoch, isCurrent))
+            return finish();
+        start();
+        function start() {
+            if (cancelled)
+                return finish();
+            if (document.readyState !== 'complete') {
+                const onLoad = () => {
+                    window.removeEventListener('load', onLoad);
+                    if (cancelled || !batchAlive(container, epoch, isCurrent))
+                        return finish();
+                    begin();
+                };
+                window.addEventListener('load', onLoad);
+                return;
+            }
+            begin();
+        }
+        function begin() {
+            const allMarkers = collectVskMarkers(container);
+            const viewportMarkers = [];
+            const deferredMarkers = [];
+            for (const marker of allMarkers) {
+                const el = marker.nextElementSibling;
+                if (!el) {
+                    deferredMarkers.push(marker);
+                    continue;
+                }
+                const rect = el.getBoundingClientRect();
+                if (rect.bottom < -rootMargin || rect.top > window.innerHeight + rootMargin) {
+                    deferredMarkers.push(marker);
+                }
+                else {
+                    viewportMarkers.push(marker);
+                }
+            }
+            const held = new Set(deferredMarkers);
+            const viewportWalker = createHydrateWalker(container, viewportMarkers);
+            runInHydrateBlock(() => componentFn(props || {}, new Map(), viewportWalker));
+            if (deferredMarkers.length === 0) {
+                assertFullyHydrated(container);
+                return finish();
+            }
             const observer = new IntersectionObserver((entries) => {
+                if (!batchAlive(container, epoch, isCurrent)) {
+                    observer.disconnect();
+                    return finish();
+                }
                 const toHydrate = [];
                 for (const entry of entries) {
                     if (entry.isIntersecting) {
@@ -360,52 +883,70 @@ export function hydrateViewport(container, componentFn, props, rootMargin = 500)
                     }
                 }
                 if (toHydrate.length > 0) {
+                    if (!batchAlive(container, epoch, isCurrent)) {
+                        observer.disconnect();
+                        return finish();
+                    }
                     const w = createHydrateWalker(container, toHydrate);
                     runInHydrateBlock(() => componentFn(props || {}, new Map(), w));
                 }
                 if (held.size === 0) {
                     observer.disconnect();
                     assertFullyHydrated(container);
-                    resolve();
+                    return finish();
                 }
             }, { rootMargin: `${rootMargin}px` });
+            cancelFn = () => {
+                try {
+                    observer.disconnect();
+                }
+                catch {
+                    // ignore disconnect failures
+                }
+                finish();
+            };
             for (const marker of deferredMarkers) {
                 const el = marker.nextElementSibling;
                 if (el)
                     observer.observe(el);
             }
-        });
-    }
-    assertFullyHydrated(container);
-    return Promise.resolve();
+        }
+    });
+    return Object.assign(promise, { cancel: () => cancelFn() });
 }
+/**
+ * Idle hydration (Hydrate-Todo B2): waits for the first idle window, then
+ * hydrates the whole container in ONE full run and stops.
+ *
+ * A previous design re-invoked the component once per marker chunk. That is
+ * irreparably unsafe without codegen yield points: every run claims its own
+ * chunk but misses everything else, so each run twins out-of-chunk SSR content
+ * with fresh nodes AND double-registers effects. Single-shot keeps the RULE
+ * (no duplication); true intra-render time-slicing needs compiler support and
+ * `chunkSize` is reserved for it (accepted, currently no effect).
+ */
 export function hydrateIdle(container, componentFn, props, options = {}) {
-    const allMarkers = collectVskMarkers(container);
-    const chunkSize = options.chunkSize || 10;
+    const epoch = navEpoch();
+    const isCurrent = options.isCurrent;
     const timeout = options.timeout || 3000;
-    let idx = 0;
     const rIC = window.requestIdleCallback || ((cb) => setTimeout(cb, 50));
     const cIC = window.cancelIdleCallback || clearTimeout;
     let rafId = null;
     let cancelled = false;
-    function processChunk(deadline) {
-        if (cancelled)
+    let ran = false;
+    function runOnce() {
+        if (cancelled || ran)
             return;
-        const end = Math.min(idx + chunkSize, allMarkers.length);
-        const chunk = allMarkers.slice(idx, end);
-        idx = end;
-        if (chunk.length > 0) {
-            const walker = createHydrateWalker(container, chunk);
-            runInHydrateBlock(() => componentFn(props || {}, new Map(), walker));
-        }
-        if (idx < allMarkers.length && (!deadline || deadline.timeRemaining() > 0 || deadline.didTimeout)) {
-            rafId = rIC(processChunk, { timeout });
-        }
-        else if (idx >= allMarkers.length) {
-            assertFullyHydrated(container);
-        }
+        ran = true;
+        // Liveness at fire time: an idle callback landing after navigation
+        // must not hydrate replaced DOM.
+        if (!batchAlive(container, epoch, isCurrent))
+            return;
+        const walker = createHydrateWalker(container);
+        runInHydrateBlock(() => componentFn(props || {}, new Map(), walker));
+        assertFullyHydrated(container);
     }
-    rafId = rIC(processChunk, { timeout });
+    rafId = rIC(runOnce, { timeout });
     return {
         cancel() {
             cancelled = true;
@@ -418,11 +959,13 @@ export function hydrateIdle(container, componentFn, props, options = {}) {
 }
 export function needsHydration(container) {
     const walker = document.createTreeWalker(container, _SHOW_COMMENT, {
-        acceptNode: (node) => (node.textContent === 'vsk' ? _FILTER_ACCEPT : _FILTER_SKIP),
+        acceptNode: (node) => (isVskMarkerText(node.textContent) ? _FILTER_ACCEPT : _FILTER_SKIP),
     });
     return walker.nextNode() !== null;
 }
 export function hydrateOnInteraction(container, componentFn, props, options = {}) {
+    const epoch = navEpoch();
+    const isCurrent = options.isCurrent;
     const events = options.events || ['click', 'touchstart', 'focus', 'mouseenter'];
     let hydrated = false;
     function trigger(_eventType) {
@@ -432,6 +975,10 @@ export function hydrateOnInteraction(container, componentFn, props, options = {}
         for (const ev of events) {
             container.removeEventListener(ev, handler);
         }
+        // An interaction that arrives after navigation must not hydrate the
+        // previous page's markers into replaced content.
+        if (!batchAlive(container, epoch, isCurrent))
+            return;
         const markers = collectVskMarkers(container);
         if (markers.length > 0) {
             const walker = createHydrateWalker(container, markers);
@@ -453,7 +1000,7 @@ export function hydrationCount(container) {
     let count = 0;
     const walker = document.createTreeWalker(container, _SHOW_COMMENT, {
         acceptNode: (node) => {
-            if (node.textContent === 'vsk') {
+            if (isVskMarkerText(node.textContent)) {
                 count++;
                 return _FILTER_ACCEPT;
             }