@vesk/compiler 0.2.25 → 0.2.27

package/dist/client-codegen.js

@@ -2,13 +2,14 @@ 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, ComponentRef, ComponentCall, ServerBlock, ClientBlock, HeadBlock, SlotNode, } from '@vesk/compiler/src/ir';
+import { StaticNode, TextNode, DynamicBinding, OpaqueDynamicRegion, MapRegion, WhileLoop, SwitchBlock, TryCatch, ForLoop, TrackDecl, RuntimeStatement, ComponentRef, ComponentCall, 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';
 import { extractRuntimeNames, extractTopLevelNames } from '@vesk/compiler/src/server-utils';
 import { importBindingPairs, localValueImportNames } from '@vesk/compiler/src/module-imports';
 import { stripTrackGeneric } from '@vesk/compiler/src/scan';
+import { importModuleTarget } from '@vesk/compiler/src/tokens';
 import { inlineMdImportsFrom } from '@vesk/compiler/src/md-inline';
 import { stripTsTypes, hasTsSyntax } from '@vesk/compiler/src/strip-ts';
 function memberExpr(object, property) {
@@ -247,12 +248,36 @@ function indent(code, level = 1) {
     const pad = '\t'.repeat(level);
     return code.split('\n').map((l) => (l ? pad + l : '')).join('\n');
 }
+/**
+ * Allocates a disjoint `$n` name block per source file. esbuild's bundler
+ * renames colliding top-level symbols when it links a chunk, and on 0.25.x
+ * that rename can leave references inside nested closures pointing at the
+ * pre-rename name — surfacing as `$nNN is not defined` at hydration. Seeding
+ * every file from a hash of its path keeps the names globally unique so the
+ * renamer has nothing to rename. Callers without a `sourcePath` keep the
+ * historical `$n0…` numbering.
+ */
+export function nameAllocFor(sourcePath, start = 0) {
+    if (!sourcePath)
+        return { c: start };
+    let h = 0x811c9dc5;
+    for (let i = 0; i < sourcePath.length; i++) {
+        h ^= sourcePath.charCodeAt(i);
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    return { c: h * 1_000_000 + start };
+}
 class Ctx {
     lines = [];
     effects = [];
-    c = 0;
+    alloc;
     importedNames = new Set();
     linkNames = new Set();
+    // Runtime component imports that claim their own SSR root via `nextElement`
+    // (Link/NavLink/Md/Form/Field/LoadingIndicator) and return a DocumentFragment
+    // when claimed. They need no call-site adoption guard — the guard targets
+    // genuinely-plain components that never touch the walker.
+    selfClaimNames = new Set();
     delegatedEvents = new Set();
     directEvents = new Set();
     hydrate = false;
@@ -264,12 +289,15 @@ class Ctx {
     walker = '__hydrate';
     asyncComps = new Set();
     isAsyncScope = false;
+    constructor(alloc) {
+        this.alloc = alloc ?? { c: 0 };
+    }
     push(...args) {
         for (const a of args)
             if (a)
                 this.lines.push(a);
     }
-    n() { return `$n${this.c++}`; }
+    n() { return `$n${this.alloc.c++}`; }
     getCode() { return this.lines.join('\n'); }
     flushEffects() {
         if (this.effects.length === 0)
@@ -286,8 +314,17 @@ class Ctx {
             lines.push(`if (!document.${guard}) {`);
             lines.push(`\tdocument.${guard} = true;`);
             lines.push(`\tdocument.addEventListener(${JSON.stringify(type)}, (e) => {`);
-            lines.push(`\t\tvar el = e.target.closest('[data-vsk-ev]');`);
-            lines.push(`\t\tif (el && el.${prop}) el.${prop}(e);`);
+            // Walk up from the target to the nearest element that actually has a
+            // handler for this event. Using `closest('[data-vsk-ev]')` alone stops at
+            // the nearest event-capable element even when its handler is undefined
+            // (`<Button/>` forwards an optional onClick that was never passed), which
+            // shadows a real handler on an ancestor (e.g. a Popover trigger wrapper).
+            lines.push(`\t\tvar el = e.target;`);
+            lines.push(`\t\tif (el && el.nodeType !== 1) el = el.parentElement;`);
+            lines.push(`\t\twhile (el && el.nodeType === 1) {`);
+            lines.push(`\t\t\tif (el.${prop}) { el.${prop}(e); break; }`);
+            lines.push(`\t\t\tel = el.parentElement;`);
+            lines.push(`\t\t}`);
             lines.push(`\t});`);
             lines.push(`}`);
         }
@@ -319,7 +356,7 @@ function emitNode(ctx, node, tracked, effectsVar, parentVar, compPrefix = '__com
     if (node instanceof OpaqueDynamicRegion)
         return emitOpaque(ctx, node, tracked, effectsVar, parentVar);
     if (node instanceof MapRegion)
-        return emitMap(ctx, node, tracked, parentVar);
+        return emitMap(ctx, node, tracked, effectsVar, parentVar);
     if (node instanceof ServerBlock)
         return null;
     if (node instanceof ClientBlock) {
@@ -347,7 +384,7 @@ function emitNode(ctx, node, tracked, effectsVar, parentVar, compPrefix = '__com
             ctx.push(`if (props.children !== undefined && props.children !== null) {`);
             ctx.push(`  if (typeof props.children === 'function') {`);
             ctx.push(`    const __child = props.children(${ctx.walker});`);
-            ctx.push(`    if (__child && typeof __child.then === 'function') __pendingChild = __child.then(() => $root);`);
+            ctx.push(`    if (__child && typeof __child.then === 'function') __pendingChild = __child.then(() => $mount || $root);`);
             ctx.push(`  } else {`);
             ctx.push(`    ${parentVar}.appendChild(props.children);`);
             ctx.push(`  }`);
@@ -366,6 +403,32 @@ function emitNode(ctx, node, tracked, effectsVar, parentVar, compPrefix = '__com
         return emitForLoop(ctx, node, tracked, parentVar);
     if (node instanceof SwitchBlock)
         return emitSwitchBlock(ctx, node, tracked, parentVar);
+    if (node instanceof PropSlot)
+        return null;
+    if (node instanceof PropSlotRender) {
+        const slotProp = `props.${node.propName}`;
+        if (!parentVar)
+            return null;
+        if (ctx.hydrate) {
+            ctx.push(`if (${slotProp} !== undefined && ${slotProp} !== null) {`);
+            ctx.push(`  if (typeof ${slotProp} === 'function') {`);
+            ctx.push(`    const __child = ${slotProp}(${ctx.walker});`);
+            ctx.push(`    if (__child && typeof __child.then === 'function') __pendingChild = __child.then(() => ${parentVar});`);
+            ctx.push(`  } else if (${slotProp}.nodeType !== undefined) {`);
+            ctx.push(`    ${parentVar}.appendChild(${slotProp});`);
+            ctx.push(`  } else {`);
+            ctx.push(`    ${parentVar}.appendChild(document.createTextNode(String(${slotProp})));`);
+            ctx.push(`  }`);
+            ctx.push(`}`);
+        }
+        else {
+            ctx.push(`if (${slotProp} !== undefined && ${slotProp} !== null) {`);
+            ctx.push(`  if (${slotProp}.nodeType !== undefined) ${parentVar}.appendChild(${slotProp});`);
+            ctx.push(`  else ${parentVar}.appendChild(document.createTextNode(String(${slotProp})));`);
+            ctx.push(`}`);
+        }
+        return null;
+    }
     return null;
 }
 const PROPERTY_ATTRS = {
@@ -402,9 +465,15 @@ function emitStatic(ctx, node, tracked, effectsVar) {
             children.push(child);
         }
     }
+    const dynAttrNames = new Set();
+    for (const d of dynAttrs)
+        if (d.target)
+            dynAttrNames.add(d.target);
     for (const attr of node.attributes) {
         if (attr.name.startsWith('on') && attr.name.length > 2)
             continue;
+        if (dynAttrNames.has(attr.name))
+            continue;
         if (attr.value === '') {
             ctx.push(`${el}.setAttribute(${JSON.stringify(attr.name)}, '');`);
         }
@@ -412,16 +481,48 @@ function emitStatic(ctx, node, tracked, effectsVar) {
             ctx.push(`${el}.setAttribute(${JSON.stringify(attr.name)}, ${JSON.stringify(escapeHtml(attr.value))});`);
         }
     }
+    // Hydrate-mode A5 snapshot: exactly one text-ish child that is a reactive
+    // dynamic binding gets initialized from the claimed parent's SSR text.
+    // Computed only in hydrate mode — normal mode pays zero for this.
+    let singleReactiveText = false;
+    if (ctx.hydrate) {
+        const textKids = children.filter((c) => c instanceof TextNode || (c instanceof DynamicBinding && c.kind === 'text'));
+        singleReactiveText = textKids.length === 1 && textKids[0] instanceof DynamicBinding
+            && isReactiveExpression(textKids[0].expression, tracked);
+    }
+    let residueBefore = 0;
     for (const child of children) {
-        const childVar = emitNode(ctx, child, tracked, effectsVar, el);
+        let childVar;
+        if (singleReactiveText && child instanceof DynamicBinding && child.kind === 'text') {
+            childVar = emitDynamicBinding(ctx, child, tracked, effectsVar, `${el}.__vsk_ssrText`);
+        }
+        else {
+            childVar = emitNode(ctx, child, tracked, effectsVar, el);
+        }
         if (childVar) {
             if (ctx.hydrate) {
-                ctx.push(`if (${childVar}.parentNode !== ${el}) { if (!${el} || ${childVar}.parentNode == null || !${el}.contains(${childVar})) ${el}.appendChild(${childVar}); }`);
+                // Fresh text nodes (static or dynamic) cannot be appended at the end of
+                // a claimed element: its SSR element children (component-boundary
+                // wrappers, skipped static markup) are still in the DOM at their SSR
+                // slots, so appending would move the text AFTER them, reordering
+                // mixed text + component children (the hero "compiler-first framework ·
+                // <VersionBadge />" label). Insert the fresh node at the SSR position
+                // of the text instead: the k-th source text child precedes the residue
+                // elements rendered before it, so it slots in before
+                // `el.__vsk_ssrEls[k]` (the residue list captured by the runtime at
+                // claim time).
+                if (child instanceof TextNode || child instanceof DynamicBinding) {
+                    ctx.push(`if (${childVar}.parentNode !== ${el}) { const __ssr = ${el}.__vsk_ssrEls || []; if (${residueBefore} < __ssr.length) ${el}.insertBefore(${childVar}, __ssr[${residueBefore}]); else ${el}.appendChild(${childVar}); }`);
+                }
+                else {
+                    ctx.push(`if (${childVar}.parentNode !== ${el}) { if (!${el} || ${childVar}.parentNode == null || !${el}.contains(${childVar})) ${el}.appendChild(${childVar}); }`);
+                }
             }
             else {
                 ctx.push(`${el}.appendChild(${childVar});`);
             }
         }
+        residueBefore += ssrResidueEstimate(child);
     }
     for (const attr of dynAttrs) {
         const target = attr.target || '';
@@ -444,12 +545,22 @@ function emitStatic(ctx, node, tracked, effectsVar) {
             }
             ctx.push(`${el}.setAttribute('data-vsk-ev', '');`);
         }
+        else if (target === 'style') {
+            const expr = transformTracked(attr.expression, tracked);
+            const eff = `effect(() => { applyStyle(${el}, ${expr}); })`;
+            if (effectsVar) {
+                ctx.push(`${effectsVar}.push(${eff});`);
+            }
+            else {
+                ctx.effects.push(`${eff};`);
+            }
+        }
         else {
             const expr = transformTracked(attr.expression, tracked);
             const useProp = PROPERTY_ATTRS[node.tag]?.has(target);
             const eff = useProp
                 ? `effect(() => { ${el}.${target} = ${expr}; })`
-                : `effect(() => { ${el}.setAttribute(${JSON.stringify(target)}, String(${expr})); })`;
+                : `effect(() => { const __v = ${expr}; if (__v != null && __v !== false) ${el}.setAttribute(${JSON.stringify(target)}, __v === true ? 'true' : String(__v)); })`;
             if (effectsVar) {
                 ctx.push(`${effectsVar}.push(${eff});`);
             }
@@ -604,7 +715,7 @@ function isReactiveExpression(node, tracked) {
     });
     return reactive;
 }
-function emitDynamicBinding(ctx, node, tracked, effectsVar) {
+function emitDynamicBinding(ctx, node, tracked, effectsVar, ssrTextExpr = null) {
     if (node.kind === 'attribute')
         return null;
     const expr = transformTracked(node.expression, tracked);
@@ -613,7 +724,13 @@ function emitDynamicBinding(ctx, node, tracked, effectsVar) {
         ctx.push(`const ${v} = document.createTextNode(String(${expr}));`);
         return v;
     }
-    ctx.push(`const ${v} = document.createTextNode('');`);
+    // Hydrate-mode sole-dynamic-text snapshot (Hydrate-Todo A5): initialize from
+    // the claimed parent's stashed SSR text so a missed effect degrades to stale
+    // text instead of an empty element. The effect below still overwrites on its
+    // first run, so live values are unaffected. Fresh (unclaimed) parents stash
+    // nothing and the `?? ''` keeps the old empty initial.
+    const init = ssrTextExpr ? `String(${ssrTextExpr} ?? '')` : `''`;
+    ctx.push(`const ${v} = document.createTextNode(${init});`);
     const eff = `effect(() => { ${v}.data = String(${expr}); })`;
     if (effectsVar) {
         ctx.push(`${effectsVar}.push(${eff});`);
@@ -623,6 +740,29 @@ function emitDynamicBinding(ctx, node, tracked, effectsVar) {
     }
     return v;
 }
+/**
+ * Emits a fresh DocumentFragment built from `nodes` (used for both the
+ * `children` of a component call and every named content slot). Children
+ * effects are collected into `effectsVar` (or `ctx.effects`) exactly as the
+ * component-call path does today, so slot bodies inherit identical effects,
+ * claim, and async semantics as regular children.
+ */
+function emitFragment(ctx, nodes, tracked, effectsVar) {
+    const frag = ctx.n();
+    const savedEffects = ctx.effects;
+    ctx.effects = [];
+    ctx.push(`const ${frag} = (() => { const $f = document.createDocumentFragment();`);
+    for (const child of nodes) {
+        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; })();`);
+    return frag;
+}
 function emitComponentCall(ctx, node, tracked, effectsVar, parentVar, compPrefix = '__components') {
     const propsEntries = node.props.map((p) => {
         if (typeof p.value === 'string')
@@ -638,37 +778,60 @@ function emitComponentCall(ctx, node, tracked, effectsVar, parentVar, compPrefix
         const expr = transformTracked(sp, tracked);
         propsEntries.push(`...${expr}`);
     }
-    const propsObj = `{ ${propsEntries.join(', ')} }`;
     const v = ctx.n();
-    const awaitKw = ctx.asyncComps.has(node.componentName) ? 'await ' : '';
+    // Await children whenever the calling scope is async. Async-ness is
+    // parent-driven (mirroring the server side) so that imported async
+    // components from other files — whose names are not in the local
+    // asyncComps set — still resolve to nodes before append/insert.
+    const awaitKw = ctx.isAsyncScope ? 'await ' : '';
     // Member-expression tags (`<it.icon>`) carry the raw component-valued
     // expression — invoke it directly; it is never a registry name.
     const calleeExpr = node.calleeExpr ? `(${node.calleeExpr})` : null;
+    // Named content slots (`trigger={<Button/>}`) thread through the same channel
+    // as `children`: a fresh DocumentFragment per slot hoisted from the IR.
+    const slotChildren = node.children.filter((c) => c instanceof PropSlot);
+    const regChildren = node.children.filter((c) => !(c instanceof PropSlot));
+    const callArgs = () => `{ ${propsEntries.join(', ')} }`;
     if (ctx.hydrate) {
         const access = calleeExpr
             ?? (ctx.importedNames.has(node.componentName)
                 ? node.componentName
                 : `__components[${JSON.stringify(node.componentName)}]`);
-        const subScope = () => ctx.inTryBody
-            ? `${ctx.walker}.subWalker(${parentVar})`
-            : `${ctx.walker}.subWalker(${ctx.walker}.nextElement())`;
-        if (node.children.length > 0) {
-            const walkerVar = ctx.n();
-            ctx.push(`const ${walkerVar} = ${subScope()};`);
+        // SSR for component calls is marker-ONLY (`<!--vsk-->` + the component's
+        // own root; no display:contents wrapper). Compiled `.vsk` components claim
+        // their own root on the SHARED walker. Call targets that are not known
+        // compiled components (imported values, member-expression tags) cannot
+        // claim, so after the call we adopt their SSR root ourselves and replace it
+        // with the fresh node they returned — never a duplicate, never a box.
+        const plainTarget = !!(calleeExpr || ctx.importedNames.has(node.componentName)) && !ctx.selfClaimNames.has(node.componentName);
+        const walkerArg = ctx.walker;
+        const maybeReplace = (v) => {
+            if (!plainTarget)
+                return;
+            // nodeType 11 = DocumentFragment: self-claiming imports (Link/Md/Form)
+            // return a fragment when they adopted their SSR root, so there is nothing
+            // to replace — claiming here would steal the NEXT sibling's root.
+            ctx.push(`if (${v} && ${v}.parentNode == null && ${v}.nodeType !== 11) { const __sr = ${walkerArg}.claimOnly(); if (__sr && __sr.parentNode) __sr.parentNode.replaceChild(${v}, __sr); }`);
+        };
+        const maybeRetire = () => {
+            if (ctx.selfClaimNames.has(node.componentName)) {
+                ctx.push(`${walkerArg}.retireDetached();`);
+            }
+        };
+        for (const slot of slotChildren) {
+            const frag = emitFragment(ctx, slot.body, tracked, effectsVar);
+            propsEntries.push(`${JSON.stringify(slot.propName)}: ${frag}`);
+        }
+        if (regChildren.length > 0) {
             const frag = ctx.n();
-            ctx.push(`const ${frag} = (() => { const $f = document.createDocumentFragment();`);
-            const savedWalker = ctx.walker;
-            const savedEffects = ctx.effects;
-            // Link/NavLink hydrate branches WIPE their SSR anchor (a.replaceChildren())
-            // and remount the children fragment. Suppressed fully-static children would
-            // therefore be lost, so rebuild the whole subtree fresh instead of claiming.
             const wipeMount = ctx.linkNames.has(node.componentName);
             const savedHydrate = ctx.hydrate;
             if (wipeMount)
                 ctx.hydrate = false;
-            ctx.walker = walkerVar;
+            ctx.push(`const ${frag} = (() => { const $f = document.createDocumentFragment();`);
+            const savedEffects = ctx.effects;
             ctx.effects = [];
-            for (const child of node.children) {
+            for (const child of regChildren) {
                 const childVar = emitNode(ctx, child, tracked, effectsVar, '$f');
                 if (childVar)
                     ctx.push(`$f.appendChild(${childVar});`);
@@ -676,23 +839,26 @@ function emitComponentCall(ctx, node, tracked, effectsVar, parentVar, compPrefix
             for (const eff of ctx.effects)
                 ctx.push(effectsVar ? `${effectsVar}.push(${effectBlockToHandlerExpr(eff)});` : eff);
             ctx.effects = savedEffects;
-            ctx.walker = savedWalker;
             ctx.hydrate = savedHydrate;
             ctx.push(`return $f; })();`);
             propsEntries.push(`children: ${frag}`);
-            ctx.push(`const ${v} = ${awaitKw}${access}({ ${propsEntries.join(', ')} }, __registry, ${walkerVar});`);
-            return v;
         }
-        ctx.push(`const ${v} = ${awaitKw}${access}(${propsObj}, __registry, ${subScope()});`);
+        ctx.push(`const ${v} = ${awaitKw}${access}(${callArgs()}, __registry, ${walkerArg});`);
+        maybeReplace(v);
+        maybeRetire();
         return v;
     }
     else {
-        if (node.children.length > 0) {
+        for (const slot of slotChildren) {
+            const frag = emitFragment(ctx, slot.body, tracked, effectsVar);
+            propsEntries.push(`${JSON.stringify(slot.propName)}: ${frag}`);
+        }
+        if (regChildren.length > 0) {
             const frag = ctx.n();
-            ctx.push(`const ${frag} = (() => { const $f = document.createDocumentFragment();`);
             const savedEffects = ctx.effects;
             ctx.effects = [];
-            for (const child of node.children) {
+            ctx.push(`const ${frag} = (() => { const $f = document.createDocumentFragment();`);
+            for (const child of regChildren) {
                 const childVar = emitNode(ctx, child, tracked, effectsVar, '$f');
                 if (childVar)
                     ctx.push(`$f.appendChild(${childVar});`);
@@ -704,13 +870,13 @@ function emitComponentCall(ctx, node, tracked, effectsVar, parentVar, compPrefix
             propsEntries.push(`children: ${frag}`);
         }
         if (calleeExpr) {
-            ctx.push(`const ${v} = ${calleeExpr}({ ${propsEntries.join(', ')} });`);
+            ctx.push(`const ${v} = ${calleeExpr}(${callArgs()});`);
         }
         else if (ctx.importedNames.has(node.componentName)) {
-            ctx.push(`const ${v} = ${awaitKw}${node.componentName}({ ${propsEntries.join(', ')} });`);
+            ctx.push(`const ${v} = ${awaitKw}${node.componentName}(${callArgs()});`);
         }
         else {
-            ctx.push(`const ${v} = ${awaitKw}${compPrefix}[${JSON.stringify(node.componentName)}]({ ${propsEntries.join(', ')} });`);
+            ctx.push(`const ${v} = ${awaitKw}${compPrefix}[${JSON.stringify(node.componentName)}](${callArgs()});`);
         }
     }
     return v;
@@ -1329,7 +1495,7 @@ function emitSwitchBlock(ctx, node, tracked, parentVar) {
 }`);
     return null;
 }
-function emitMap(ctx, node, tracked, parentVar) {
+function emitMap(ctx, node, tracked, effTarget, parentVar) {
     const arrExpr = transformTracked(node.expression, tracked);
     const itemVar = node.itemVariable;
     const anchor = ctx.n();
@@ -1349,6 +1515,26 @@ function emitMap(ctx, node, tracked, parentVar) {
     // emitting a top-level effect there would reference the loop/statement local
     // (`col`, `pages`) which is out of scope — `ReferenceError` at hydrate.
     const reactiveSource = isReactiveExpression(node.expression, tracked);
+    // The re-render effect below closes over the anchors/reconciler declared
+    // inline above. When this map is nested inside a branch/item builder those
+    // bindings live in that nested closure — so the effect must be created in
+    // the same scope (registered on the enclosing effects array), not flushed
+    // to the component top level where the names are out of scope
+    // (`$nNN is not defined` at hydration, plus an esbuild shadowing rename).
+    const pushEffect = (lets, effCall) => {
+        if (effTarget) {
+            ctx.push(`${effTarget}.push((() => {
+    ${lets}
+    return ${effCall};
+  })());`);
+        }
+        else {
+            ctx.effects.push(`{
+  ${lets}
+  ${effCall};
+}`);
+        }
+    };
     ctx.push(`const ${anchor} = document.createComment('map');`);
     if (!hyd && !hydKeyed)
         ctx.push(`${parent}.appendChild(${anchor});`);
@@ -1436,6 +1622,13 @@ function emitMap(ctx, node, tracked, parentVar) {
     ctx.push(`const ${hasItems} = () => { const __l = ${arrExpr}; return __l != null && __l.length > 0; };`);
     if (node.keyExpr) {
         const keyExpr = transformTracked(node.keyExpr, tracked);
+        // A `key` may reference the loop's `index` variable (`for (… ; key i; index i)`).
+        // The key function is evaluated outside the item renderer (where the index is
+        // in scope), so it must receive the index as its own parameter — otherwise the
+        // emitted `item => i` key closes over an undefined `i` (ReferenceError).
+        // Parenthesize the parameters: without them `item, i => …` parses as a comma
+        // sequence expression rather than a two-parameter arrow in argument position.
+        const keyFnSrc = `(${itemVar}${node.indexVariable ? `, ${node.indexVariable}` : ''}) => ${keyExpr}`;
         const reconciler = ctx.n();
         const initList = ctx.n();
         ctx.push(`let ${reconciler} = () => {};`);
@@ -1444,10 +1637,10 @@ function emitMap(ctx, node, tracked, parentVar) {
             // inside `parent` (pre-attach, `anchor.parentNode` is null) and peeks all
             // keys before claim-by-key consumes the walker, so server-rendered items
             // are adopted and wired in place instead of being rebuilt.
-            ctx.push(`const ${initList} = () => { ${reconciler} = reconcileHydrated(${anchor}, ${endAnchor}, ${arrExpr}, ${itemVar} => ${keyExpr}, (${itemVar}, __i, __e, __root) => ${renderItem}(${itemVar}${indexParam ? ', __i, __e' : ', __e'}, null, __root), __hydrate, ${parent}); };`);
+            ctx.push(`const ${initList} = () => { ${reconciler} = reconcileHydrated(${anchor}, ${endAnchor}, ${arrExpr}, ${keyFnSrc}, (${itemVar}, __i, __e, __root) => ${renderItem}(${itemVar}${indexParam ? ', __i, __e' : ', __e'}, null, __root), __hydrate, ${parent}); };`);
         }
         else {
-            ctx.push(`const ${initList} = () => { ${reconciler} = reconcile(${anchor}, ${endAnchor}, ${arrExpr}, ${itemVar} => ${keyExpr}, (${itemVar}, __i, __e) => ${renderItem}(${itemVar}${indexParam ? ', __i, __e' : ', __e'})); };`);
+            ctx.push(`const ${initList} = () => { ${reconciler} = reconcile(${anchor}, ${endAnchor}, ${arrExpr}, ${keyFnSrc}, (${itemVar}, __i, __e) => ${renderItem}(${itemVar}${indexParam ? ', __i, __e' : ', __e'})); };`);
         }
         if (emptyRenderName) {
             const isEmptyVar = ctx.n();
@@ -1455,9 +1648,7 @@ function emitMap(ctx, node, tracked, parentVar) {
             ctx.push(`if (!${isEmptyVar}) { ${initList}(); } else { ${aw}${emptyRenderName}(); }`);
             if (!reactiveSource)
                 return null;
-            ctx.effects.push(`{
-  let __first = true;
-  effect(${effOpen}
+            pushEffect(`let __first = true;`, `effect(${effOpen}
     const __new = ${hasItems}();
     if (__first) { __first = false; __new; return; }
     if (__new !== ${isEmptyVar}) {
@@ -1469,21 +1660,17 @@ function emitMap(ctx, node, tracked, parentVar) {
     ${effectsVar}.length = 0;
     __cleanup(${anchor}, ${endAnchor});
     if (__new) { ${initList}(); } else { ${aw}${emptyRenderName}(); }
-  });
-}`);
+  })`);
         }
         else {
             ctx.push(`${initList}();`);
             if (!reactiveSource)
                 return null;
-            ctx.effects.push(`{
-  let __first = true;
-  effect(() => {
+            pushEffect(`let __first = true;`, `effect(() => {
     const __nv = ${arrExpr};
     if (__first) { __first = false; __nv; ${reconciler}(${arrExpr}); return; }
     ${reconciler}(${arrExpr});
-  });
-}`);
+  })`);
         }
     }
     else {
@@ -1516,9 +1703,7 @@ function emitMap(ctx, node, tracked, parentVar) {
                 ctx.push(`__place(${anchor}, ${endAnchor}, ${collectVar}, ${parent});`);
             if (!reactiveSource)
                 return null;
-            ctx.effects.push(`{
-  let __first = true;
-  effect(${effOpen}
+            pushEffect(`let __first = true;`, `effect(${effOpen}
     const __new = ${hasItems}();
     if (__first) { __first = false; __new; return; }
     if (__new !== ${isEmptyVar}) {
@@ -1537,8 +1722,7 @@ ${renderAllItems('        ', null)}
     if (__new) {
 ${renderAllItems('      ', null)}
     } else { ${aw}${emptyRenderName}(${collectVar ? collectVar : ''}); }
-  });
-}`);
+  })`);
         }
         else {
             const collectVar = hyd ? ctx.n() : null;
@@ -1549,17 +1733,14 @@ ${renderAllItems('      ', null)}
                 ctx.push(`__place(${anchor}, ${endAnchor}, ${collectVar}, ${parent});`);
             if (!reactiveSource)
                 return null;
-            ctx.effects.push(`{
-  let __first = true;
-  effect(${effOpen}
+            pushEffect(`let __first = true;`, `effect(${effOpen}
     const __nv = ${arrExpr};
     if (__first) { __first = false; __nv; return; }
     for (const e of ${effectsVar}) destroy_block(e);
     ${effectsVar}.length = 0;
     __cleanup(${anchor}, ${endAnchor});
 ${renderAllItems('    ', null)}
-  });
-}`);
+  })`);
         }
     }
     return null;
@@ -1567,11 +1748,12 @@ ${renderAllItems('    ', null)}
 function computeAsyncComponents(comps) {
     return new Set(comps.filter((c) => c.isAsync).map((c) => c.name));
 }
-function generateComponent(comp, importedNames = new Set(), hydrate = false, asyncComps = new Set(), linkNames = new Set()) {
+function generateComponent(comp, importedNames = new Set(), hydrate = false, asyncComps = new Set(), linkNames = new Set(), selfClaimNames = new Set(), alloc) {
     const tracked = collectTrackedNames(comp.body);
-    const ctx = new Ctx();
+    const ctx = new Ctx(alloc);
     ctx.importedNames = importedNames;
     ctx.linkNames = linkNames;
+    ctx.selfClaimNames = selfClaimNames;
     ctx.hydrate = hydrate;
     ctx.asyncComps = asyncComps;
     ctx.isAsyncScope = comp.isAsync || asyncComps.has(comp.name);
@@ -1587,7 +1769,16 @@ function generateComponent(comp, importedNames = new Set(), hydrate = false, asy
         ctx.push(indent(`}`));
     }
     if (ctx.hydrate) {
+        // Two distinct roles must not be conflated:
+        //  - `$root` is the shared page container. It is only ever a last-resort
+        //    mount target for detached dynamic regions (`__place`) that could not
+        //    be claimed in place; it must never be handed back to a caller.
+        //  - `$mount` is THIS component's own first top-level node. It is what the
+        //    hydrator returns so the parent can position/guard the component. A
+        //    component's own node is never an ancestor of the caller, so the
+        //    parent's `contains()` guards and `__place` end-anchor bounds are valid.
         ctx.push(indent(`const $root = __hydrate.root;`));
+        ctx.push(indent(`let $mount = null;`));
     }
     else {
         ctx.push(indent(`const $root = document.createDocumentFragment();`));
@@ -1596,11 +1787,23 @@ function generateComponent(comp, importedNames = new Set(), hydrate = false, asy
     const paramInit = buildParamInit(comp.paramNames);
     if (paramInit)
         ctx.push(indent(paramInit));
+    // Hoist TrackDecls to top to avoid TDZ when Head/effects reference them before declaration
     for (const node of comp.body) {
+        if (node instanceof TrackDecl) {
+            emitNode(ctx, node, tracked, null);
+        }
+    }
+    for (const node of comp.body) {
+        if (node instanceof TrackDecl)
+            continue;
         const v = emitNode(ctx, node, tracked, null);
         if (v) {
             if (ctx.hydrate) {
-                ctx.push(indent(`if (${v}.parentNode !== $root) { if (!$root || ${v}.parentNode == null || !$root.contains(${v})) $root.appendChild(${v}); }`));
+                // The first top-level node becomes `$mount`. Late top-level nodes are
+                // already in the DOM when claimed; only a divergent fresh node is
+                // nested onto the mount (matching the pre-marker wrapper behaviour).
+                ctx.push(indent(`if ($mount === null) $mount = ${v};`));
+                ctx.push(indent(`if (${v} !== $mount && ${v}.parentNode == null) $mount.appendChild(${v});`));
             }
             else {
                 ctx.push(indent(`$root.appendChild(${v});`));
@@ -1613,7 +1816,15 @@ function generateComponent(comp, importedNames = new Set(), hydrate = false, asy
     const delCode = ctx.emitDelegates();
     if (delCode)
         ctx.push(indent(delCode.trim()));
-    ctx.push(indent(`return __pendingChild || $root;`));
+    if (ctx.hydrate) {
+        // A hydrator with no claimable nodes must still hand its caller a value the
+        // parent guards can safely inspect (an empty fragment places nothing).
+        ctx.push(indent(`if ($mount === null) $mount = document.createDocumentFragment();`));
+        ctx.push(indent(`return __pendingChild || $mount;`));
+    }
+    else {
+        ctx.push(indent(`return __pendingChild || $root;`));
+    }
     ctx.push(indent(`} finally {`));
     ctx.push(indent(`\tsetActiveComponent(__prev);`));
     ctx.push(indent(`}`));
@@ -1627,7 +1838,7 @@ function buildParamInit(paramNames) {
         return '';
     return `const { ${paramNames.join(', ')} } = props;`;
 }
-function buildComponentMap(irRoot, hydrate = false) {
+function buildComponentMap(irRoot, hydrate = false, alloc) {
     const mapLines = [];
     mapLines.push(`const __components = {};`);
     const asyncComps = computeAsyncComponents(irRoot.components);
@@ -1635,7 +1846,19 @@ function buildComponentMap(irRoot, hydrate = false) {
     // hydration, so their children fragments must be rebuilt in full. Track the
     // file-local binding names regardless of aliasing (`const Nav = NavLink`).
     const linkNames = new Set();
+    // Runtime components that self-claim during hydration (adopt their own SSR
+    // root via nextElement and return a fragment when claimed). Excluded from the
+    // call-site adoption guard; the walker cursor passes them but never a
+    // claimOnly() on their behalf.
+    const selfClaimNames = new Set();
+    const SELF_CLAIM_RUNTIME = new Set(['Link', 'NavLink', 'Md', 'Form', 'Field', 'LoadingIndicator']);
     for (const imp of irRoot.imports) {
+        if (importModuleTarget(imp) !== '@vesk/runtime')
+            continue;
+        for (const pair of importBindingPairs(imp)) {
+            if (SELF_CLAIM_RUNTIME.has(pair.imported))
+                selfClaimNames.add(pair.local);
+        }
         for (const pair of importBindingPairs(imp)) {
             if (pair.imported === 'Link' || pair.imported === 'NavLink')
                 linkNames.add(pair.local);
@@ -1650,11 +1873,13 @@ function buildComponentMap(irRoot, hydrate = false) {
     const directNames = new Set([...extractRuntimeNames(irRoot.imports), ...localValueImportNames(irRoot.imports), ...topValueNames]);
     for (const comp of irRoot.components) {
         if (hydrate && isStaticComponent(comp)) {
-            const stub = `(props, __registry, __hydrate) => { return __hydrate.root; }`;
+            // Static components keep their SSR content untouched: claim the root
+            // WITHOUT stripping its direct text (nothing will re-create it).
+            const stub = `(props, __registry, __hydrate) => { return __hydrate.claimOnly(); }`;
             mapLines.push(`__components[${JSON.stringify(comp.name)}] = ${stub};`);
             continue;
         }
-        const code = generateComponent(comp, directNames, hydrate, asyncComps, linkNames);
+        const code = generateComponent(comp, directNames, hydrate, asyncComps, linkNames, selfClaimNames, alloc);
         mapLines.push(`__components[${JSON.stringify(comp.name)}] = ${code};`);
     }
     mapLines.push(`function __cleanup(start, end) {`);
@@ -1683,6 +1908,40 @@ function buildComponentMap(irRoot, hydrate = false) {
     mapLines.push(`}`);
     return mapLines.join('\n\n');
 }
+function ssrResidueEstimate(node) {
+    if (Array.isArray(node)) {
+        let total = 0;
+        for (const n of node)
+            total += ssrResidueEstimate(n);
+        return total;
+    }
+    if (node instanceof StaticNode)
+        return 1;
+    if (node instanceof ComponentCall)
+        return 1;
+    if (node instanceof OpaqueDynamicRegion) {
+        return Math.max(ssrResidueEstimate(node.consequentNodes), ssrResidueEstimate(node.alternateNodes));
+    }
+    if (node instanceof MapRegion) {
+        return Math.max(ssrResidueEstimate(node.bodyTemplate), ssrResidueEstimate(node.alternateNodes));
+    }
+    if (node instanceof ForLoop)
+        return ssrResidueEstimate(node.bodyTemplate);
+    if (node instanceof WhileLoop)
+        return ssrResidueEstimate(node.bodyTemplate);
+    if (node instanceof SwitchBlock) {
+        let max = 0;
+        for (const c of node.cases)
+            max = Math.max(max, ssrResidueEstimate(c.body));
+        return max;
+    }
+    if (node instanceof TryCatch) {
+        return Math.max(ssrResidueEstimate(node.bodyTemplate), ssrResidueEstimate(node.catchBody));
+    }
+    // TextNode, DynamicBinding, TrackDecl, RuntimeStatement, SlotNode,
+    // ServerBlock, ClientBlock, HeadBlock emit no SSR element residue.
+    return 0;
+}
 function isStaticIR(body) {
     for (const node of body) {
         if (node instanceof StaticNode) {
@@ -1778,6 +2037,10 @@ function findBindingInIR(nodes, names) {
             if (findBindingInIR(node.children, names))
                 return true;
         }
+        else if (node instanceof PropSlot) {
+            if (findBindingInIR(node.body, names))
+                return true;
+        }
         else if (node instanceof RuntimeStatement) {
             if (astHasBinding(node.ast, names))
                 return true;
@@ -1806,6 +2069,10 @@ function findFormNameInIR(nodes, name) {
             if (findFormNameInIR(node.children, name))
                 return true;
         }
+        if (node instanceof PropSlot) {
+            if (findFormNameInIR(node.body, name))
+                return true;
+        }
         if (node instanceof DynamicBinding && node.expression && node.expression.raw) {
             if (node.expression.raw.includes(fnPattern))
                 return true;
@@ -1884,7 +2151,7 @@ function emitClientFromIR(ir, options) {
     if (!options.forceClient && !needsClient) {
         return '';
     }
-    const componentMapCode = buildComponentMap(ir, options.hydrate);
+    const componentMapCode = buildComponentMap(ir, options.hydrate, options.nameAllocator);
     const importLines = ir.imports.length > 0 ? ir.imports.join('\n') + '\n' : '';
     const topCode = (options.includeTopLevel === false ? [] : transformTopLevelForActions(ir.topLevelCode, 'client')).join('\n') + '\n';
     const exportLines = [];
@@ -1899,7 +2166,7 @@ function emitClientFromIR(ir, options) {
         }
     }
     const exportCode = exportLines.join('\n');
-    const runtimeNames = ['track', 'get', 'set', 'destroy_block', 'getActiveComponent', 'setActiveComponent', 'reactiveProps'];
+    const runtimeNames = ['track', 'get', 'set', 'destroy_block', 'getActiveComponent', 'setActiveComponent', 'reactiveProps', 'applyStyle'];
     if (ir.components.some(c => !isStaticIR(c.body)))
         runtimeNames.push('effect');
     for (const name of usedRuntimeBindings(ir))
@@ -1950,7 +2217,7 @@ export function compileClient(source, _componentName, options = {}) {
     }
     const ast = parse(source, options.sourcePath ? { filename: options.sourcePath } : {});
     const ir = generateIR(ast, source, options.sourcePath);
-    return emitClientFromIR(ir, options);
+    return emitClientFromIR(ir, { ...options, nameAllocator: options.nameAllocator ?? nameAllocFor(options.sourcePath) });
 }
 /**
  * Compiles a component source in BOTH client modes (plain + hydrate)
@@ -1979,9 +2246,12 @@ export function compileClientBoth(source, _componentName, sourcePath) {
         if (exportedComp)
             name = exportedComp.name;
     }
+    // Comp and hyd land in the same scoped file block, so they share one
+    // allocator: hyd continues after the names comp already consumed.
+    const alloc = nameAllocFor(sourcePath);
     return {
-        comp: emitClientFromIR(ir, { forceClient: true }),
-        hyd: emitClientFromIR(irHyd, { forceClient: true, hydrate: true, includeTopLevel: false }),
+        comp: emitClientFromIR(ir, { forceClient: true, nameAllocator: alloc }),
+        hyd: emitClientFromIR(irHyd, { forceClient: true, hydrate: true, includeTopLevel: false, nameAllocator: alloc }),
         name,
     };
 }