@vesk/compiler 0.2.93 → 0.2.95

package/dist/client-codegen.js

@@ -2,7 +2,7 @@ import { walk } from 'zimmerframe';
 import { print } from 'esrap';
 import ts from 'esrap/languages/ts';
 import tsx from 'esrap/languages/tsx';
-import { StaticNode, TextNode, DynamicBinding, OpaqueDynamicRegion, MapRegion, WhileLoop, SwitchBlock, TryCatch, ForLoop, TrackDecl, RuntimeStatement, BreakSignal, ComponentRef, ComponentCall, ServerBlock, ClientBlock, HeadBlock, SlotNode, PropSlot, PropSlotRender, } from '@vesk/compiler/src/ir';
+import { StaticNode, TextNode, DynamicBinding, OpaqueDynamicRegion, MapRegion, WhileLoop, SwitchBlock, TryCatch, ForLoop, TrackDecl, RuntimeStatement, BreakSignal, ComponentRef, ComponentCall, regionMarkerId, ServerBlock, ClientBlock, HeadBlock, SlotNode, PropSlot, PropSlotRender, } from '@vesk/compiler/src/ir';
 import { parse } from '@vesk/compiler/src/parser';
 import { generateIR } from '@vesk/compiler/src/ir-generator';
 import { transformTopLevelForActions } from '@vesk/compiler/src/actions';
@@ -535,6 +535,10 @@ class Ctx {
     markerless = true;
     inTryBody = false;
     claimStatic = false;
+    // Markerless only: the next real claim carries a compiler-generated static
+    // class descriptor so a same-tag but structurally different SSR slot is
+    // substituted instead of adopted (e.g. an empty-state <div> vs a list <div>).
+    descriptorClaim = false;
     // While set, the next StaticNode claimed in hydrate mode uses `__root` (the
     // item element already claimed by key) instead of walking for a new element.
     rootClaim = false;
@@ -685,6 +689,7 @@ function emitNode(ctx, node, tracked, effectsVar, parentVar, compPrefix = '__com
             ctx.push(`    const __slot = createLayoutSlot(${ctx.walker}, ${parentVar});`);
             ctx.push(`    const __child = props.children(__slot.walker);`);
             ctx.push(`    if (__child && typeof __child.then === 'function') __pendingChild = __slot.track(__child);`);
+            ctx.push(`    else if (__child && __child.nodeType === 11) ${parentVar}.appendChild(__child);`);
             ctx.push(`  } else {`);
             ctx.push(`    ${parentVar}.appendChild(props.children);`);
             ctx.push(`  }`);
@@ -738,6 +743,24 @@ const PROPERTY_ATTRS = {
     option: new Set(['selected']),
     progress: new Set(['value']),
 };
+/**
+ * Build the markerless structural descriptor for a claimed element. Only a
+ * source-authored static class is included: dynamic classes are runtime values
+ * and must never be validated (SSR/client first paint may legitimately differ).
+ * The descriptor is a JS-only argument to the walker; it never reaches SSR HTML.
+ */
+function staticClassDescriptor(node) {
+    const hasDynamicClass = node.children.some((child) => child instanceof DynamicBinding && child.kind === 'attribute' && child.target === 'class');
+    if (hasDynamicClass)
+        return null;
+    const attr = node.attributes.find((a) => a.name === 'class');
+    if (!attr)
+        return null;
+    const value = attr.value.trim();
+    if (!value)
+        return null;
+    return JSON.stringify({ class: value });
+}
 function emitStatic(ctx, node, tracked, effectsVar, skipK = 0, regionBudget) {
     const el = ctx.n();
     if (ctx.hydrate) {
@@ -761,13 +784,21 @@ function emitStatic(ctx, node, tracked, effectsVar, skipK = 0, regionBudget) {
         // are claimed on their own sub-walker and carry their own residue math.
         const skipExpr = regionBudget && ctx.markerless ? markerlessSkipExpr(regionBudget, skipK) : skipK;
         const skipArg = ctx.markerless ? `, ${skipExpr}` : '';
+        // A component root or region branch root may be the slot where the client's
+        // initial branch differs from SSR. Validate its static class so a same-tag
+        // wrong branch is substituted, not adopted. One-shot: only the first real
+        // claim in that root/branch carries the descriptor.
+        const wantsDescriptor = ctx.markerless && ctx.descriptorClaim;
+        ctx.descriptorClaim = false;
+        const descriptor = wantsDescriptor && !rootClaim ? staticClassDescriptor(node) : null;
+        const descriptorArg = descriptor ? `, ${descriptor}` : '';
         // `rootClaim` marks the keyed renderItem root: claimed items supply the
         // SSR element as `__root`, fresh items must CREATE one. The walker is never
         // valid here as a fallback — its cursor doesn't advance past claimByKey, so
         // `nextElement` would steal a neighboring SSR node to render the new item.
         const claimedExpr = rootClaim
             ? `__root || document.createElement(${JSON.stringify(node.tag)})`
-            : `${ctx.walker}.nextElement(${JSON.stringify(node.tag)}${skipArg})`;
+            : `${ctx.walker}.nextElement(${JSON.stringify(node.tag)}${skipArg}${descriptorArg})`;
         ctx.push(`const ${el} = ${claimedExpr};`);
         if (regionBudget && ctx.markerless)
             ctx.push(`${regionBudget} = 0;`);
@@ -1269,6 +1300,65 @@ function emitFragment(ctx, nodes, tracked, effectsVar) {
     ctx.push(`return $f; })();`);
     return frag;
 }
+/**
+ * True when any node in the subtree is a layout `{props.children}` slot.
+ *
+ * A slot must be hydrated on the walker scoped to the element that will
+ * actually contain it. Building the children fragment eagerly on the caller's
+ * walker is only correct when the callee appends that fragment to its own
+ * mount point. A component that forwards children through a scoped container
+ * (e.g. a shell that renders `{props.children}` inside `<main>`) invokes the
+ * child hydrator with a sub-walker; passing an eagerly-built fragment skips
+ * that scope and lets the page claim the shell's own SSR root.
+ */
+function containsSlot(nodes) {
+    for (const node of nodes) {
+        if (node instanceof SlotNode)
+            return true;
+        if (node instanceof StaticNode) {
+            if (containsSlot(node.children))
+                return true;
+        }
+        else if (node instanceof ComponentCall) {
+            if (containsSlot(node.children))
+                return true;
+        }
+        else if (node instanceof OpaqueDynamicRegion) {
+            if (containsSlot(node.consequentNodes) || containsSlot(node.alternateNodes))
+                return true;
+        }
+        else if (node instanceof MapRegion) {
+            if (containsSlot(node.bodyTemplate) || containsSlot(node.alternateNodes))
+                return true;
+        }
+        else if (node instanceof WhileLoop) {
+            if (containsSlot(node.bodyTemplate))
+                return true;
+        }
+        else if (node instanceof ForLoop) {
+            if (containsSlot(node.bodyTemplate))
+                return true;
+        }
+        else if (node instanceof SwitchBlock) {
+            for (const c of node.cases)
+                if (containsSlot(c.body))
+                    return true;
+        }
+        else if (node instanceof TryCatch) {
+            if (containsSlot(node.bodyTemplate) || containsSlot(node.catchBody))
+                return true;
+        }
+        else if (node instanceof ServerBlock || node instanceof ClientBlock || node instanceof HeadBlock) {
+            if (containsSlot(node.children))
+                return true;
+        }
+        else if (node instanceof PropSlot) {
+            if (containsSlot(node.body))
+                return true;
+        }
+    }
+    return false;
+}
 function emitComponentCall(ctx, node, tracked, effectsVar, parentVar, compPrefix = '__components', skipK = 0, regionBudget) {
     const propsEntries = node.props.map((p) => {
         if (typeof p.value === 'string')
@@ -1328,6 +1418,11 @@ function emitComponentCall(ctx, node, tracked, effectsVar, parentVar, compPrefix
         ? `reactiveProps({ ${propsEntries.join(', ')} })`
         : `{ ${propsEntries.join(', ')} }`);
     if (ctx.hydrate) {
+        // A component call is itself the root claim site. A compiled child carries
+        // its own root descriptor; a plain target has no IR root to describe. In
+        // either case the caller's pending branch descriptor must not leak to a
+        // following sibling.
+        ctx.descriptorClaim = false;
         const access = calleeExpr
             ?? (ctx.importedNames.has(node.componentName)
                 ? node.componentName
@@ -1406,20 +1501,56 @@ function emitComponentCall(ctx, node, tracked, effectsVar, parentVar, compPrefix
             // fresh and let the runtime component adopt the existing root.
             if (wipeMount || ctx.selfClaimNames.has(node.componentName))
                 ctx.hydrate = false;
-            ctx.push(`const ${frag} = (() => { const $f = document.createDocumentFragment();`);
-            const savedEffects = ctx.effects;
-            ctx.effects = [];
-            for (const child of regChildren) {
-                const childVar = emitNode(ctx, child, tracked, effectsVar, '$f');
-                if (childVar)
-                    ctx.push(`$f.appendChild(${childVar});`);
+            // A slot nested under a compiled component must be built by that
+            // component's scoped walker, not the caller's. Pass children as a lazy
+            // hydrator so the callee can invoke it with the walker for the element
+            // that actually contains the slot (e.g. `<main>` in a shell). Eagerly
+            // building the fragment here hydrates the page against the shell's own
+            // SSR root, which detaches the shell on hydration.
+            const lazySlotChildren = ctx.hydrate && !plainTarget && !ctx.selfClaimNames.has(node.componentName) && containsSlot(regChildren);
+            if (lazySlotChildren) {
+                const fnVar = ctx.n();
+                const savedLines = ctx.lines;
+                const savedEffects = ctx.effects;
+                const savedWalker = ctx.walker;
+                ctx.lines = [];
+                ctx.effects = [];
+                ctx.walker = '__childWalker';
+                ctx.push(`const $f = document.createDocumentFragment();`);
+                for (const child of regChildren) {
+                    const childVar = emitNode(ctx, child, tracked, effectsVar, '$f');
+                    if (childVar)
+                        ctx.push(`$f.appendChild(${childVar});`);
+                }
+                for (const eff of ctx.effects)
+                    ctx.push(effectsVar ? `${effectsVar}.push(${effectBlockToHandlerExpr(eff)});` : eff);
+                ctx.push(`return $f;`);
+                const body = ctx.lines.join('\n');
+                ctx.lines = savedLines;
+                ctx.effects = savedEffects;
+                ctx.walker = savedWalker;
+                const asyncKw = ctx.isAsyncScope ? 'async ' : '';
+                ctx.push(`const ${fnVar} = ${asyncKw}(__childWalker) => {`);
+                ctx.push(indent(body));
+                ctx.push(`};`);
+                propsEntries.push(`children: ${fnVar}`);
+            }
+            else {
+                ctx.push(`const ${frag} = (() => { const $f = document.createDocumentFragment();`);
+                const savedEffects = ctx.effects;
+                ctx.effects = [];
+                for (const child of regChildren) {
+                    const childVar = emitNode(ctx, child, tracked, effectsVar, '$f');
+                    if (childVar)
+                        ctx.push(`$f.appendChild(${childVar});`);
+                }
+                for (const eff of ctx.effects)
+                    ctx.push(effectsVar ? `${effectsVar}.push(${effectBlockToHandlerExpr(eff)});` : eff);
+                ctx.effects = savedEffects;
+                ctx.push(`return $f; })();`);
+                propsEntries.push(`children: ${frag}`);
             }
-            for (const eff of ctx.effects)
-                ctx.push(effectsVar ? `${effectsVar}.push(${effectBlockToHandlerExpr(eff)});` : eff);
-            ctx.effects = savedEffects;
             ctx.hydrate = savedHydrate;
-            ctx.push(`return $f; })();`);
-            propsEntries.push(`children: ${frag}`);
         }
         // Deposit the residue for the child's first top-level claim (it runs on
         // this same walker with its own zero `topPendingSkip`). A region budget is
@@ -1667,7 +1798,7 @@ function emitTryCatch(ctx, node, tracked, effectsVar, parentVar, skipK = 0, regi
       ${effArr}.length = 0;
       __cleanup(${anchor}, ${endAnchor});
       try { ${asyncKw}${tryRenderComp}(); } catch(${catchParam}) { ${hasCatch ? `${asyncKw}${catchRenderComp}(${catchParam});` : 'throw ${catchParam};'} }
-    });
+    }, true);
   }`);
     return null;
 }
@@ -1675,13 +1806,14 @@ function emitOpaque(ctx, node, tracked, effTarget, parentVar, skipK = 0, regionB
     const hyd = ctx.hydrate;
     const parent = parentVar || '$root';
     const budget = hyd ? regionBudgetVar(ctx, skipK, regionBudget) : null;
+    const rid = regionMarkerId(node);
     const isOpaque = (n) => !!n && typeof n.condition !== 'undefined';
     if (hyd && node.alternateNodes.length === 1 && isOpaque(node.alternateNodes[0])) {
         const chain = [];
         let cur = node;
         let finalElse = null;
         while (cur) {
-            chain.push({ cond: transformTracked(cur.condition, tracked), nodes: cur.consequentNodes });
+            chain.push({ cond: transformTracked(cur.condition, tracked), nodes: cur.consequentNodes, id: regionMarkerId(cur) });
             if (cur.alternateNodes.length === 1 && isOpaque(cur.alternateNodes[0])) {
                 cur = cur.alternateNodes[0];
             }
@@ -1706,6 +1838,9 @@ function emitOpaque(ctx, node, tracked, effTarget, parentVar, skipK = 0, regionB
             ctx.push(`const ${rn} = ${fnOpen}`);
             const cl = ctx.n();
             ctx.push(indent(`const ${cl} = [];`));
+            const savedDescriptor = ctx.descriptorClaim;
+            if (hyd && ctx.markerless)
+                ctx.descriptorClaim = true;
             for (const n of chain[i].nodes) {
                 const savedClaim = ctx.claimStatic;
                 if (hyd)
@@ -1715,6 +1850,7 @@ function emitOpaque(ctx, node, tracked, effTarget, parentVar, skipK = 0, regionB
                 if (v)
                     ctx.push(indent(`${cl}.push(${v});`));
             }
+            ctx.descriptorClaim = savedDescriptor;
             ctx.push(indent(`__place(${anchor}, ${endAnchor}, ${cl}, ${parent});`));
             ctx.push(`};`);
         }
@@ -1724,6 +1860,9 @@ function emitOpaque(ctx, node, tracked, effTarget, parentVar, skipK = 0, regionB
             ctx.push(`const ${finalRender} = ${fnOpen}`);
             const cl2 = ctx.n();
             ctx.push(indent(`const ${cl2} = [];`));
+            const savedDescriptor = ctx.descriptorClaim;
+            if (hyd && ctx.markerless)
+                ctx.descriptorClaim = true;
             for (const n of finalElse) {
                 const savedClaim = ctx.claimStatic;
                 if (hyd)
@@ -1733,15 +1872,10 @@ function emitOpaque(ctx, node, tracked, effTarget, parentVar, skipK = 0, regionB
                 if (v)
                     ctx.push(indent(`${cl2}.push(${v});`));
             }
+            ctx.descriptorClaim = savedDescriptor;
             ctx.push(indent(`__place(${anchor}, ${endAnchor}, ${cl2}, ${parent});`));
             ctx.push(`};`);
         }
-        let init = `if (${chain[0].cond}) { ${asyncKw}${renderNames[0]}(); }`;
-        for (let i = 1; i < chain.length; i++)
-            init += ` else if (${chain[i].cond}) { ${asyncKw}${renderNames[i]}(); }`;
-        if (finalRender)
-            init += ` else { ${asyncKw}${finalRender}(); }`;
-        ctx.push(init);
         // Resolve which branch index the chain is in, for any chain depth. The last
         // fallback is `chain.length` when a final `else` exists, otherwise -1 (no
         // branch renders). Build the nested ternary from the innermost condition
@@ -1751,13 +1885,37 @@ function emitOpaque(ctx, node, tracked, effTarget, parentVar, skipK = 0, regionB
             branchInitFallback = `(${chain[i].cond} ? ${i} : ${branchInitFallback})`;
         }
         const branchInit = `(${branchInitFallback})`;
+        // Snapshot the branch chosen by the INITIAL render before claiming it. The
+        // effect flush runs after the component body, so a tracked cell can change
+        // in between (bootstrap hydration, a child island's body, an inline
+        // statement). Initializing `__iv` at flush time would silently adopt the
+        // new branch while the DOM still held the old one; the first effect run
+        // must compare against the branch that actually rendered.
+        const branchSnapshot = ctx.n();
+        ctx.push(`const ${branchSnapshot} = ${branchInit};`);
+        if (!ctx.markerless) {
+            for (let i = 0; i < chain.length; i++) {
+                ctx.push(`if (__hydrate) __reconcileRegion(${parent}, '${chain[i].id}', ${branchSnapshot} === ${i} ? 0 : 1, ${ctx.walker});`);
+            }
+        }
+        else {
+            const chainBranches = chain.map((c) => c.nodes);
+            if (finalElse)
+                chainBranches.push(finalElse);
+            emitStructuralRegionDiscard(ctx, chainBranches, branchSnapshot, budget);
+        }
+        let init = `if (${branchSnapshot} === 0) { ${asyncKw}${renderNames[0]}(); }`;
+        for (let i = 1; i < chain.length; i++)
+            init += ` else if (${branchSnapshot} === ${i}) { ${asyncKw}${renderNames[i]}(); }`;
+        if (finalRender)
+            init += ` else { ${asyncKw}${finalRender}(); }`;
+        ctx.push(init);
         let effInner = `if (__new === 0) { ${asyncKw}${renderNames[0]}(); }`;
         for (let i = 1; i < chain.length; i++)
             effInner += ` else if (__new === ${i}) { ${asyncKw}${renderNames[i]}(); }`;
         if (finalRender)
             effInner += ` else { ${asyncKw}${finalRender}(); }`;
         const effBody = `effect(${ctx.isAsyncScope ? 'async () => {' : '() => {'}
-        if (__first) { __first = false; __iv = ${branchInit}; return; }
         const __new = ${branchInit};
         if (__new !== __iv) {
           for (const e of ${effectsVar}) destroy_block(e);
@@ -1766,18 +1924,16 @@ function emitOpaque(ctx, node, tracked, effTarget, parentVar, skipK = 0, regionB
           ${effInner}
           __iv = __new;
         }
-      });`;
+      }, true);`;
         if (effTarget) {
             ctx.push(`${effTarget}.push((() => {
-      let __iv = ${branchInit};
-      let __first = true;
+      let __iv = ${branchSnapshot};
       return ${effBody}
     })());`);
         }
         else {
             ctx.effects.push(`{
-      let __iv = ${branchInit};
-      let __first = true;
+      let __iv = ${branchSnapshot};
       ${effBody}
     }`);
         }
@@ -1805,6 +1961,9 @@ function emitOpaque(ctx, node, tracked, effTarget, parentVar, skipK = 0, regionB
         ctx.push(indent(`const ${conFrag} = document.createDocumentFragment();`));
     if (hyd)
         ctx.push(indent(`const __cl = [];`));
+    const savedConDescriptor = ctx.descriptorClaim;
+    if (hyd && ctx.markerless)
+        ctx.descriptorClaim = true;
     for (const n of node.consequentNodes) {
         const savedClaim = ctx.claimStatic;
         if (hyd)
@@ -1818,6 +1977,7 @@ function emitOpaque(ctx, node, tracked, effTarget, parentVar, skipK = 0, regionB
                 ctx.push(indent(`${conFrag}.appendChild(${v});`));
         }
     }
+    ctx.descriptorClaim = savedConDescriptor;
     if (hyd)
         ctx.push(indent(`__place(${anchor}, ${endAnchor}, __cl, ${parent});`));
     else
@@ -1834,6 +1994,9 @@ function emitOpaque(ctx, node, tracked, effTarget, parentVar, skipK = 0, regionB
             ctx.push(indent(`const ${altFrag} = document.createDocumentFragment();`));
         if (hyd)
             ctx.push(indent(`const __cl = [];`));
+        const savedAltDescriptor = ctx.descriptorClaim;
+        if (hyd && ctx.markerless)
+            ctx.descriptorClaim = true;
         for (const n of node.alternateNodes) {
             const savedAltClaim = ctx.claimStatic;
             if (hyd)
@@ -1847,6 +2010,7 @@ function emitOpaque(ctx, node, tracked, effTarget, parentVar, skipK = 0, regionB
                     ctx.push(indent(`${altFrag}.appendChild(${v});`));
             }
         }
+        ctx.descriptorClaim = savedAltDescriptor;
         if (hyd)
             ctx.push(indent(`__place(${anchor}, ${endAnchor}, __cl, ${parent});`));
         else
@@ -1855,10 +2019,19 @@ function emitOpaque(ctx, node, tracked, effTarget, parentVar, skipK = 0, regionB
     }
     if (!hyd)
         ctx.push(`${parent}.appendChild(${endAnchor});`);
-    ctx.push(`if (${condExpr}) { ${asyncKw}${conRenderName}(); }` + (hasElse ? ` else { ${asyncKw}${altRenderName}(); }` : ''));
+    // Snapshot the condition used by the INITIAL render. Effect flush runs after
+    // the body, so tracked data can arrive in between; comparing the first effect
+    // run against a value read at flush time would adopt the new branch without
+    // replacing the DOM that the old branch already claimed.
+    const condSnapshot = ctx.n();
+    ctx.push(`const ${condSnapshot} = ${condExpr};`);
+    if (hyd && !ctx.markerless)
+        ctx.push(`if (__hydrate) __reconcileRegion(${parent}, '${rid}', ${condSnapshot} ? 0 : 1, ${ctx.walker});`);
+    if (hyd && ctx.markerless)
+        emitStructuralRegionDiscard(ctx, [node.consequentNodes, node.alternateNodes], hasElse ? `(${condSnapshot} ? 0 : 1)` : `(${condSnapshot} ? 0 : -1)`, budget);
+    ctx.push(`if (${condSnapshot}) { ${asyncKw}${conRenderName}(); }` + (hasElse ? ` else { ${asyncKw}${altRenderName}(); }` : ''));
     const renderBranch = `if (__nv) { ${asyncKw}${conRenderName}(); }` + (hasElse ? ` else { ${asyncKw}${altRenderName}(); }` : '');
     const effectBody = `effect(${ctx.isAsyncScope ? 'async () => {' : '() => {'}
-      if (__first) { __first = false; __iv = ${condExpr}; return; }
       const __nv = ${condExpr};
       if (__nv !== __iv) {
         for (const e of ${effectsVar}) destroy_block(e);
@@ -1867,7 +2040,7 @@ function emitOpaque(ctx, node, tracked, effTarget, parentVar, skipK = 0, regionB
         ${renderBranch}
         __iv = __nv;
       }
-    });`;
+    }, true);`;
     // A static condition renders once; an effect referencing it would only ever
     // reference statement/loop-local bindings that are out of scope at the flush
     // site (e.g. `const pages = …; if (pages.length > 0)` inside a for-of body).
@@ -1875,15 +2048,13 @@ function emitOpaque(ctx, node, tracked, effTarget, parentVar, skipK = 0, regionB
         return null;
     if (effTarget) {
         ctx.push(`${effTarget}.push((() => {
-    let __iv = ${condExpr};
-    let __first = true;
+    let __iv = ${condSnapshot};
     return ${effectBody}
   })());`);
     }
     else {
         ctx.effects.push(`{
-    let __iv = ${condExpr};
-    let __first = true;
+    let __iv = ${condSnapshot};
     ${effectBody}
   }`);
     }
@@ -1973,7 +2144,7 @@ function emitWhileLoop(ctx, node, tracked, parentVar, skipK = 0, regionBudget) {
       __busy = false;
       __iv = (${condExpr});
     }
-  });
+  }, true);
 }`);
     return null;
 }
@@ -2087,7 +2258,7 @@ function emitForLoop(ctx, node, tracked, parentVar, skipK = 0, regionBudget) {
       __busy = false;
       __iv = (${srcExpr});
     }
-  });
+  }, true);
 }`);
     }
     else {
@@ -2156,7 +2327,7 @@ function emitForLoop(ctx, node, tracked, parentVar, skipK = 0, regionBudget) {
     __cleanup(${anchor}, ${endAnchor});
     ${ctx.isAsyncScope ? 'await ' : ''}${renderLoop}();
     __busy = false;
-  });
+  }, true);
 }`);
         }
     }
@@ -2233,7 +2404,7 @@ function emitSwitchBlock(ctx, node, tracked, parentVar, skipK = 0, regionBudget)
       __busy = false;
       __iv = (${discExpr});
     }
-  });
+  }, true);
 }`);
     return null;
 }
@@ -2380,34 +2551,34 @@ function emitMap(ctx, node, tracked, effTarget, parentVar, skipK = 0, regionBudg
     let emptyRenderName = null;
     if (node.alternateNodes.length > 0) {
         emptyRenderName = ctx.n();
-        const emptySig = !hyd
+        // Hydrated maps (keyed AND non-keyed) claim their #empty fallback
+        // positionally with descriptor checks: an SSR slot that rendered the same
+        // fallback is adopted in place (no duplicate), while an SSR item ghost in
+        // that slot is detached by the walker's mismatch recovery and the fallback
+        // renders fresh. Fresh (SPA) renders keep the fragment + direct-insert
+        // shape — there is no SSR DOM to claim.
+        const emptyClaims = ctx.hydrate;
+        const emptySig = !emptyClaims
             ? (ctx.isAsyncScope ? 'async () => {' : '() => {')
             : (ctx.isAsyncScope ? 'async (__cl) => {' : '(__cl) => {');
         ctx.push(`const ${emptyRenderName} = ${emptySig}`);
         ctx.push(indent(`const __p = ${anchor}.parentNode;`));
         const frag = ctx.n();
-        if (!hyd)
+        if (!emptyClaims)
             ctx.push(indent(`const ${frag} = document.createDocumentFragment();`));
         const savedClaim = ctx.claimStatic;
-        const savedHydrate = ctx.hydrate;
-        // A keyed map hydrating with no matching SSR items renders its empty
-        // fallback fresh — the SSR item ghosts get reported by the canary instead
-        // of being adopted positionally as the fallback (which would be wrong DOM).
-        if (hydKeyed)
-            ctx.hydrate = false;
         for (const n of node.alternateNodes) {
             ctx.claimStatic = true;
-            const v = emitNode(ctx, n, tracked, effectsVar, hyd ? undefined : frag, '__components', 0, budget || undefined);
+            const v = emitNode(ctx, n, tracked, effectsVar, emptyClaims ? undefined : frag, '__components', 0, budget || undefined);
             if (v) {
-                if (hyd)
+                if (emptyClaims)
                     ctx.push(indent(`if (__cl) __cl.push(${v}); else __p.insertBefore(${v}, ${endAnchor});`));
                 else
                     ctx.push(indent(`${frag}.appendChild(${v});`));
             }
         }
         ctx.claimStatic = savedClaim;
-        ctx.hydrate = savedHydrate;
-        if (!hyd)
+        if (!emptyClaims)
             ctx.push(indent(`if (${frag}.childNodes.length > 0) __p.insertBefore(${frag}, ${endAnchor});`));
         ctx.push(`};`);
     }
@@ -2440,8 +2611,19 @@ function emitMap(ctx, node, tracked, effTarget, parentVar, skipK = 0, regionBudg
         }
         if (emptyRenderName) {
             const isEmptyVar = ctx.n();
+            // A hydrated keyed map attaches its region anchors through
+            // `reconcileHydrated` (items branch) or `__place` (empty branch) — the
+            // anchors are created detached and the empty-fallback builder reads
+            // `anchor.parentNode`, so the empty branch must place them too or the
+            // whole hydrator crashes ("insertBefore on null") and every later
+            // reactive update on the page is lost.
+            const collectVar = hydKeyed ? ctx.n() : null;
             ctx.push(`let ${isEmptyVar} = !${hasItems}();`);
-            ctx.push(`if (!${isEmptyVar}) { ${initList}(); } else { ${aw}${emptyRenderName}(); }`);
+            if (collectVar)
+                ctx.push(`const ${collectVar} = [];`);
+            ctx.push(`if (!${isEmptyVar}) { ${initList}(); } else { ${aw}${emptyRenderName}(${collectVar || ''}); }`);
+            if (collectVar)
+                ctx.push(`__place(${anchor}, ${endAnchor}, ${collectVar}, ${parent});`);
             if (!reactiveSource)
                 return null;
             pushEffect(`let __first = true;`, `effect(${effOpen}
@@ -2456,7 +2638,7 @@ function emitMap(ctx, node, tracked, effTarget, parentVar, skipK = 0, regionBudg
     ${effectsVar}.length = 0;
     __cleanup(${anchor}, ${endAnchor});
     if (__new) { ${initList}(); } else { ${aw}${emptyRenderName}(); }
-  })`);
+  }, true)`);
         }
         else {
             ctx.push(`${initList}();`);
@@ -2466,7 +2648,7 @@ function emitMap(ctx, node, tracked, effTarget, parentVar, skipK = 0, regionBudg
     const __nv = ${arrExpr};
     if (__first) { __first = false; __nv; ${breakReset}${reconciler}(${arrExpr}); return; }
     ${breakVar ? `if (${breakVar}) ${breakVar} = false;` : ''}${reconciler}(${arrExpr});
-  })`);
+  }, true)`);
         }
     }
     else {
@@ -2523,8 +2705,8 @@ ${renderAllItems('        ', null)}
     __cleanup(${anchor}, ${endAnchor});
     if (__new) {
 ${renderAllItems('      ', null)}
-    } else { ${aw}${emptyRenderName}(${collectVar ? collectVar : ''}); }
-  })`);
+    } else { ${aw}${emptyRenderName}(); }
+  }, true)`);
         }
         else {
             const collectVar = hyd ? ctx.n() : null;
@@ -2542,7 +2724,7 @@ ${renderAllItems('      ', null)}
     ${effectsVar}.length = 0;
     __cleanup(${anchor}, ${endAnchor});
 ${renderAllItems('    ', null)}
-  })`);
+  }, true)`);
         }
     }
     return null;
@@ -2664,6 +2846,11 @@ function generateComponent(comp, importedNames = new Set(), hydrate = false, asy
             }
         }
     }
+    // The first real claim is this component's root: let it validate the static
+    // class shape against the SSR slot. The flag is consumed by the first claim
+    // and never leaks to nested children.
+    if (ctx.hydrate && ctx.markerless)
+        ctx.descriptorClaim = true;
     for (const node of comp.body) {
         // A TrackDecl that could not be hoisted (its init reads an earlier body
         // binding) is emitted here, in source order, so the binding it reads is
@@ -2804,6 +2991,33 @@ function buildComponentMap(irRoot, hydrate = false, alloc, markerless = true) {
         const code = generateComponent(comp, directNames, hydrate, asyncComps, linkNames, selfClaimNames, alloc, markerless);
         mapLines.push(`${registry}[${JSON.stringify(comp.name)}] = ${code};`);
     }
+    if (hydrate && !markerless) {
+        mapLines.push(`function __reconcileRegion(parent, id, branch, walker) {`);
+        mapLines.push(`\tif (!parent) return;`);
+        mapLines.push(`\tlet start = null;`);
+        mapLines.push(`\tlet end = null;`);
+        mapLines.push(`\tfor (let n = parent.firstChild; n; n = n.nextSibling) {`);
+        mapLines.push(`\t\tif (n.nodeType !== 8) continue;`);
+        mapLines.push(`\t\tconst text = n.textContent || '';`);
+        mapLines.push(`\t\tif (text === 'vesk-r:' + id + ':0' || text === 'vesk-r:' + id + ':1') start = n;`);
+        mapLines.push(`\t\telse if (text === 'vesk-r-end:' + id) end = n;`);
+        mapLines.push(`\t\tif (start && end) break;`);
+        mapLines.push(`\t}`);
+        mapLines.push(`\tif (!start || !end) return;`);
+        mapLines.push(`\tconst ssrBranch = (start.textContent || '').slice(-2) === ':1' ? 1 : 0;`);
+        mapLines.push(`\tif (ssrBranch !== branch) {`);
+        mapLines.push(`\t\tlet n = start.nextSibling;`);
+        mapLines.push(`\t\twhile (n && n !== end) {`);
+        mapLines.push(`\t\t\tconst next = n.nextSibling;`);
+        mapLines.push(`\t\t\tn.remove();`);
+        mapLines.push(`\t\t\tn = next;`);
+        mapLines.push(`\t\t}`);
+        mapLines.push(`\t\tif (walker && walker.retireDetached) walker.retireDetached();`);
+        mapLines.push(`\t}`);
+        mapLines.push(`\tstart.remove();`);
+        mapLines.push(`\tend.remove();`);
+        mapLines.push(`}`);
+    }
     mapLines.push(`function __cleanup(start, end) {`);
     mapLines.push(`\tlet n = start.nextSibling;`);
     mapLines.push(`\twhile (n && n !== end) {`);
@@ -2870,6 +3084,50 @@ function ssrResidueEstimate(node) {
     // ServerBlock, ClientBlock, HeadBlock emit no SSR element residue.
     return 0;
 }
+function firstBranchRoot(nodes) {
+    for (const n of nodes) {
+        if (n instanceof StaticNode)
+            return { tag: n.tag, descriptor: staticClassDescriptor(n) };
+        if (n instanceof ComponentCall || n instanceof ComponentRef)
+            return null;
+        if (n instanceof OpaqueDynamicRegion)
+            return null;
+        if (n instanceof MapRegion || n instanceof ForLoop || n instanceof WhileLoop) {
+            const child = firstBranchRoot(n.bodyTemplate);
+            if (child)
+                return child;
+        }
+        if (n instanceof SwitchBlock) {
+            for (const c of n.cases) {
+                const child = firstBranchRoot(c.body);
+                if (child)
+                    return child;
+            }
+        }
+        if (n instanceof TryCatch) {
+            const child = firstBranchRoot(n.bodyTemplate) || firstBranchRoot(n.catchBody);
+            if (child)
+                return child;
+        }
+    }
+    return null;
+}
+function structuralRegionMetadata(branches) {
+    const parts = branches.map((nodes) => {
+        const first = firstBranchRoot(nodes);
+        const tag = first ? JSON.stringify(first.tag) : 'undefined';
+        const descriptor = first && first.descriptor ? first.descriptor : 'null';
+        return `{ tag: ${tag}, descriptor: ${descriptor}, count: ${ssrResidueEstimate(nodes)} }`;
+    });
+    return `[${parts.join(', ')}]`;
+}
+function emitStructuralRegionDiscard(ctx, branches, selectedExpr, budget) {
+    if (!ctx.hydrate || !ctx.markerless)
+        return;
+    const offset = budget ? `, ${budget}` : '';
+    const consume = budget ? ` ${budget} = 0;` : '';
+    ctx.push(`if (${ctx.walker} && typeof ${ctx.walker}.discardStructuralRegion === 'function' && ${ctx.walker}.discardStructuralRegion(${structuralRegionMetadata(branches)}, ${selectedExpr}${offset})) {${consume}}`);
+}
 function isStaticIR(body) {
     for (const node of body) {
         if (node instanceof StaticNode) {