@jay-framework/compiler-jay-html 0.24.6 → 0.25.0

package/dist/index.js

@@ -1,8 +1,8 @@
-import { camelCase as camelCase$1, JayImportedType, JayString, isObjectType as isObjectType$1, isImportedType, isRecursiveType, JayUnknown, Imports, Import, RenderFragment, WithValidations, isArrayType as isArrayType$1, isAtomicType, isPromiseType, isEnumType, GenerateTarget, hasRefs, JayTypeAlias, JayUnionType, mkRefsTree, equalJayTypes, mkRef, JayComponentType, JayHTMLType, getModeFileExtension, isHtmlStringType, RuntimeMode, nestRefs, mergeRefsTrees, SourceFileFormat, JayEnumType, JayObjectType, JayArrayType, JayPromiseType, resolvePrimitiveType, JayRecursiveType, JAY_CONTRACT_EXTENSION as JAY_CONTRACT_EXTENSION$1, ImportsFor, JAY_FULLSTACK_COMPONENTS, JayErrorType, JayOptionalType, JayRecordType, isOptionalType, isRecordType, resolvePluginManifest, resolvePluginComponent } from "@jay-framework/compiler-shared";
+import { camelCase as camelCase$1, JayImportedType, JayString, JayUnknown, isObjectType as isObjectType$1, isImportedType, isRecursiveType, Imports, Import, RenderFragment, WithValidations, isArrayType as isArrayType$1, isAtomicType, isPromiseType, isEnumType, GenerateTarget, hasRefs, JayTypeAlias, JayUnionType, mkRefsTree, equalJayTypes, mkRef, JayComponentType, JayHTMLType, getModeFileExtension, isHtmlStringType, RuntimeMode, nestRefs, mergeRefsTrees, SourceFileFormat, JayEnumType, JayObjectType, JayArrayType, JayPromiseType, resolvePrimitiveType, JayRecursiveType, JAY_CONTRACT_EXTENSION as JAY_CONTRACT_EXTENSION$1, ImportsFor, JAY_FULLSTACK_COMPONENTS, hoistFreeRefs, freeRefsAugmentedRefType, isComponentType as isComponentType$1, JayErrorType, JayOptionalType, JayRecordType, isOptionalType, isRecordType, resolvePluginManifest, resolvePluginComponent } from "@jay-framework/compiler-shared";
 import path from "path";
 import { getLogger } from "@jay-framework/logger";
-import fs$1 from "fs/promises";
-import fs from "fs";
+import fs from "fs/promises";
+import fs$1 from "fs";
 import { analyzeExportedTypes } from "@jay-framework/compiler-analyze-exported-types";
 import { createRequire } from "module";
 var commonjsGlobal = typeof globalThis !== "undefined" ? globalThis : typeof window !== "undefined" ? window : typeof global !== "undefined" ? global : typeof self !== "undefined" ? self : {};
@@ -5777,6 +5777,7 @@ parse$1.TextNode = text_1.default;
 parse$1.NodeType = type_1.default;
 const COORD_ATTR$1 = "jay-coordinate-base";
 const SCOPE_ATTR = "jay-scope";
+const AUTO_REF_PATTERN = /^AR\d+$/;
 function assignCoordinatesToJayHtml(jayHtml, headlessContractNames) {
   const root = parse_2(jayHtml, {
     comment: true,
@@ -5790,6 +5791,12 @@ function assignCoordinatesToJayHtml(jayHtml, headlessContractNames) {
 function nextScopeId(counter) {
   return `S${counter.next++}`;
 }
+function isScopeAnchorDiv(node2) {
+  if (node2.nodeType !== NodeType.ELEMENT_NODE) return false;
+  const el = node2;
+  if (el.tagName?.toLowerCase() !== "div") return false;
+  return (el.getAttribute("style") ?? "").replace(/\s+/g, "").includes("display:contents");
+}
 function assignCoordinates(body, options) {
   if (!options._refCounters) options._refCounters = /* @__PURE__ */ new Map();
   const rootChildren = body.childNodes.filter(
@@ -5814,6 +5821,7 @@ function walkChildren(parent, parentCoord, scopeId, options, counter) {
       const contractName = tagName.substring(4);
       if (options.headlessContractNames.has(contractName)) {
         let ref = element.getAttribute("ref");
+        const explicitRef = !!ref && !AUTO_REF_PATTERN.test(ref);
         if (!ref) {
           const idx = options._refCounters.get(contractName) ?? 0;
           options._refCounters.set(contractName, idx + 1);
@@ -5825,9 +5833,9 @@ function walkChildren(parent, parentCoord, scopeId, options, counter) {
           contractName,
           ref,
           parentCoord,
-          scopeId,
           options,
-          counter
+          counter,
+          explicitRef
         );
         continue;
       }
@@ -5851,18 +5859,20 @@ function walkChildren(parent, parentCoord, scopeId, options, counter) {
     walkChildren(element, coord, scopeId, options, counter);
   }
 }
-function assignHeadlessInstance(element, contractName, ref, parentCoord, parentScopeId, options, counter) {
+function assignHeadlessInstance(element, contractName, ref, parentCoord, options, counter, explicitRef) {
   const instanceCoord = `${parentCoord}/${contractName}:${ref}`;
   element.setAttribute(COORD_ATTR$1, instanceCoord);
   const childScopeId = nextScopeId(counter);
   element.setAttribute(SCOPE_ATTR, childScopeId);
-  const significantChildren = element.childNodes.filter(
+  const significantTemplateChildren = element.childNodes.filter(
     (n) => n.nodeType === NodeType.ELEMENT_NODE || n.nodeType === NodeType.TEXT_NODE && (n.innerText || "").trim() !== ""
   );
-  if (significantChildren.length > 1) {
+  const alreadyWrapped = significantTemplateChildren.length === 1 && isScopeAnchorDiv(significantTemplateChildren[0]);
+  if (!alreadyWrapped && (explicitRef || significantTemplateChildren.length > 1)) {
     const wrapper = parse_2("<div></div>").querySelector("div");
+    if (explicitRef) wrapper.setAttribute("class", ref);
     wrapper.setAttribute("style", "display: contents");
-    const children = [...element.childNodes];
+    const children = element.childNodes;
     element.innerHTML = "";
     children.forEach((child) => wrapper.appendChild(child));
     element.appendChild(wrapper);
@@ -5879,6 +5889,7 @@ function walkForEachChildren(parent, itemScopeId, options, counter) {
       const contractName = tagName.substring(4);
       if (options.headlessContractNames.has(contractName)) {
         let ref = element.getAttribute("ref");
+        const explicitRef = !!ref && !AUTO_REF_PATTERN.test(ref);
         if (!ref) {
           const counterKey = `forEach/${contractName}`;
           const idx = options._refCounters.get(counterKey) ?? 0;
@@ -5891,9 +5902,9 @@ function walkForEachChildren(parent, itemScopeId, options, counter) {
           contractName,
           ref,
           itemScopeId,
-          itemScopeId,
           options,
-          counter
+          counter,
+          explicitRef
         );
         continue;
       }
@@ -6108,6 +6119,18 @@ function capitalCase(input, options) {
   }
   return noCase(input, __assign({ delimiter: " ", transform: capitalCaseTransform }, options));
 }
+function dotCase(input, options) {
+  if (options === void 0) {
+    options = {};
+  }
+  return noCase(input, __assign({ delimiter: "." }, options));
+}
+function paramCase(input, options) {
+  if (options === void 0) {
+    options = {};
+  }
+  return dotCase(input, __assign({ delimiter: "-" }, options));
+}
 function shouldIncludeInPhase(propertyPhase, targetPhase) {
   if (targetPhase === "slow") {
     return propertyPhase === "slow";
@@ -6588,11 +6611,11 @@ function peg$parse(input, options) {
   }, peg$c1 = function(comment2) {
     return null;
   }, peg$c2 = ":", peg$c3 = peg$literalExpectation(":", false), peg$c4 = ";", peg$c5 = peg$literalExpectation(";", false), peg$c6 = function(prop, value) {
-    const camelProp = prop.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+    const camelProp = prop.startsWith("--") ? prop : prop.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
     const [valueFragment, isDynamic] = value;
     return {
       property: camelProp,
-      valueFragment: isDynamic ? valueFragment.map((_) => `dp(${vars.currentVar} => ${_})`).plusImport(dp) : valueFragment,
+      valueFragment: isDynamic ? valueFragment.map((_) => `dp(${jayParams(valueFragment)} => ${_})`).plusImport(dp) : valueFragment,
       isDynamic
     };
   }, peg$c7 = function() {
@@ -6630,31 +6653,32 @@ function peg$parse(input, options) {
     if (isDynamic) {
       if (tail.length === 0)
         return head.map((_) => `{${_}}`);
-      const mappedClasses = classes.map((cls) => {
-        return cls instanceof RenderFragment2 ? cls.map((_) => `\${${_}}`) : new RenderFragment2(cls, none);
-      });
-      const reduced = mappedClasses.reduce(
-        (result, fragment) => RenderFragment2.merge(result, fragment, " "),
+      const elements = classes.map((cls) => cls instanceof RenderFragment2 ? cls : new RenderFragment2(`'${cls}'`));
+      const reduced = elements.reduce(
+        (result, fragment) => RenderFragment2.merge(result, fragment, ", "),
         RenderFragment2.empty()
       );
-      return reduced.map((_) => `{\`${_}\`}`);
+      return reduced.map((_) => `{cx(${_})}`).plusImport(cx);
     } else
       return new RenderFragment2(classes.join(" "), none).map((_) => `"${_}"`);
   }, peg$c43 = function(head, tail) {
-    let isDynamic = false;
-    const renderClass = (cls) => {
-      isDynamic = isDynamic || cls instanceof RenderFragment2;
-      return cls instanceof RenderFragment2 ? cls.map((_) => "${" + _ + "}") : new RenderFragment2(cls, none);
-    };
-    let classString = tail.reduce((result, tuple) => {
-      const classExp = tuple[1];
-      return RenderFragment2.merge(result, renderClass(classExp), " ");
-    }, renderClass(head));
-    return isDynamic ? classString.map((_) => `da(${vars.currentVar} => \`${_}\`)`) : classString.map((_) => `'${_}'`);
+    const classes = [head, ...tail.map((tuple) => tuple[1])];
+    const isDynamic = classes.some((cls) => cls instanceof RenderFragment2);
+    if (isDynamic) {
+      if (tail.length === 0)
+        return head.map((_) => `da(${jayParams(head)} => ${_})`);
+      const elements = classes.map((cls) => cls instanceof RenderFragment2 ? cls : new RenderFragment2(`'${cls}'`));
+      const arrayContents = elements.reduce(
+        (result, fragment) => RenderFragment2.merge(result, fragment, ", "),
+        RenderFragment2.empty()
+      );
+      return arrayContents.map((_) => `da(${jayParams(arrayContents)} => cx(${_}))`).plusImport(cx);
+    }
+    return new RenderFragment2(classes.join(" "), none).map((_) => `'${_}'`);
   }, peg$c44 = function(cls) {
     return cls.render().plusImport(da);
   }, peg$c45 = /^[{]/, peg$c46 = peg$classExpectation(["{"], false, false), peg$c47 = /^[?]/, peg$c48 = peg$classExpectation(["?"], false, false), peg$c49 = /^[:]/, peg$c50 = peg$classExpectation([":"], false, false), peg$c51 = /^[}]/, peg$c52 = peg$classExpectation(["}"], false, false), peg$c53 = function(acc, classY, classN) {
-    return new RenderFragment2(`${acc.rendered}?'${classY}':'${classN ? classN[3] : ""}'`, da, acc.validations);
+    return new RenderFragment2(`${acc.rendered}?'${classY}':'${classN ? classN[3] : ""}'`, da, acc.validations, void 0, void 0, acc.parentDepth);
   }, peg$c54 = /^[\-]/, peg$c55 = peg$classExpectation(["-"], false, false), peg$c56 = /^[_a-zA-Z]/, peg$c57 = peg$classExpectation(["_", ["a", "z"], ["A", "Z"]], false, false), peg$c58 = /^[_a-zA-Z0-9\-]/, peg$c59 = peg$classExpectation(["_", ["a", "z"], ["A", "Z"], ["0", "9"], "-"], false, false), peg$c60 = function() {
     return text2();
   }, peg$c61 = "as", peg$c62 = peg$literalExpectation("as", false), peg$c63 = ",", peg$c64 = peg$literalExpectation(",", false), peg$c65 = function(head, rename, tail) {
@@ -6669,10 +6693,10 @@ function peg$parse(input, options) {
       return [...acc, val[3]];
     }, [first]);
   }, peg$c78 = function(cond) {
-    return cond.map((_) => `ba(${vars.currentVar} => ${_})`).plusImport(ba);
+    return cond.map((_) => `ba(${jayParams(cond)} => ${_})`).plusImport(ba);
   }, peg$c79 = function(template) {
     let [renderFragment, isDynamic] = template;
-    return isDynamic ? renderFragment.map((_) => `da(${vars.currentVar} => ${_})`).plusImport(da) : renderFragment;
+    return isDynamic ? renderFragment.map((_) => `da(${jayParams(renderFragment)} => ${_})`).plusImport(da) : renderFragment;
   }, peg$c80 = function(num) {
     return new RenderFragment2(num);
   }, peg$c81 = function(template) {
@@ -6680,7 +6704,7 @@ function peg$parse(input, options) {
     return renderFragment;
   }, peg$c82 = function(template) {
     let [renderFragment, isDynamic] = template;
-    return isDynamic ? renderFragment.map((_) => `dp(${vars.currentVar} => ${_})`).plusImport(dp) : renderFragment;
+    return isDynamic ? renderFragment.map((_) => `dp(${jayParams(renderFragment)} => ${_})`).plusImport(dp) : renderFragment;
   }, peg$c83 = function(template) {
     let [renderFragment, isDynamic] = template;
     return isDynamic ? renderFragment.map((_) => `{${_}}`) : renderFragment;
@@ -6705,7 +6729,7 @@ function peg$parse(input, options) {
     }
   }, peg$c86 = function(template) {
     let [renderFragment, isDynamic] = template;
-    return isDynamic ? renderFragment.map((_) => `dt(${vars.currentVar} => ${_})`).plusImport(dt) : renderFragment;
+    return isDynamic ? renderFragment.map((_) => `dt(${jayParams(renderFragment)} => ${_})`).plusImport(dt) : renderFragment;
   }, peg$c87 = function(a, head, tail) {
     const renderText2 = (w2, h) => {
       return h ? h.reduce((acc, str2) => acc + str2[0] + (str2[1].length ? " " : ""), w2.length ? " " : "") : w2.length ? " " : "";
@@ -6730,7 +6754,7 @@ function peg$parse(input, options) {
     const raw = text2();
     return { kind: "binding", value: raw.slice(1, -1).trim() };
   }, peg$c93 = function(cond) {
-    return cond.map((_) => `${vars.currentVar} => ${_}`);
+    return cond.map((_) => `${jayParams(cond)} => ${_}`);
   }, peg$c94 = "||", peg$c95 = peg$literalExpectation("||", false), peg$c96 = function(head, tail) {
     if (tail.length === 0) return head;
     return tail.reduce((acc, curr) => combineOr(acc, curr[3]), head);
@@ -13302,6 +13326,7 @@ function peg$parse(input, options) {
   let da = options.da;
   let dp = options.dp;
   let ba = options.ba;
+  let cx = options.cx;
   let slowContext = options.slowContext;
   function isSlowPhase2(path2) {
     if (!slowContext) return false;
@@ -13420,6 +13445,13 @@ function peg$parse(input, options) {
       expr: `${leftExpr} ${jsOp} ${rightExpr}`
     };
   }
+  function jayParams(renderFragment) {
+    const depth = renderFragment && renderFragment.parentDepth || 0;
+    if (depth === 0) return vars.currentVar;
+    let params = vars.currentVar;
+    for (let i = 1; i <= depth; i++) params += `, _p${i}`;
+    return `(${params})`;
+  }
   function applyStartsWith(left, right) {
     if (left.type === "resolved" && right.type === "resolved") {
       return { type: "resolved", value: String(left.value).startsWith(String(right.value)) };
@@ -13450,18 +13482,37 @@ function peg$parse(input, options) {
 var expressionParser = {
   parse: peg$parse
 };
+const PARENT_TOKEN = "$parent";
+function parentParamName(level) {
+  return `_p${level}`;
+}
 class Accessor {
   rootVar;
   terms;
   validations;
   resolvedType;
-  constructor(rootVar, terms, validations, resolvedType) {
+  /** DL#193: how many scopes a `$parent` access climbs (0 = current scope). */
+  parentLevel;
+  constructor(rootVar, terms, validations, resolvedType, parentLevel = 0) {
     this.rootVar = rootVar;
     this.terms = terms;
     this.validations = validations;
     this.resolvedType = resolvedType;
+    this.parentLevel = parentLevel;
   }
   render() {
+    if (this.parentLevel > 0) {
+      const param = parentParamName(this.parentLevel);
+      const rendered = this.terms.length === 0 ? param : param + "." + this.terms.join("?.");
+      return new RenderFragment(
+        rendered,
+        Imports.none(),
+        this.validations,
+        void 0,
+        void 0,
+        this.parentLevel
+      );
+    }
     let renderedAccessor = this.terms.length === 1 && this.terms[0] === "." ? this.rootVar : this.rootVar + "." + this.terms.join("?.");
     return new RenderFragment(`${renderedAccessor}`, Imports.none(), this.validations);
   }
@@ -13471,20 +13522,76 @@ class Variables {
   currentType;
   currentContext;
   parent;
-  children = {};
+  children;
   depth;
-  constructor(currentTypes, parent = void 0, depth = 0, customVarName) {
+  /**
+   * DL#193 Phase 2c: when true, this scope's `currentVar` is a real variable that is lexically
+   * in scope at every descendant binding site (the server target inlines the whole tree into one
+   * `renderToStream`, so `vs`, forEach item vars, and instance vars are all reachable by name).
+   * In that world a `$parent` climb that lands on this scope must emit `currentVar` directly, not
+   * a `_pN` closure param (which only exists in the client/hydrate per-binding callbacks). The
+   * flag is inherited by every child scope so setting it once on the server root covers the tree.
+   */
+  lexicallyInScope;
+  constructor(currentTypes, parent = void 0, depth = 0, customVarName, children = {}, lexicallyInScope = false) {
     this.currentVar = customVarName || (depth === 0 ? "vs" : "vs" + depth);
     this.currentContext = depth === 0 ? "context" : "cx" + depth;
     this.depth = depth;
     this.parent = parent;
     this.currentType = currentTypes instanceof JayImportedType ? currentTypes.type : currentTypes;
+    this.children = children;
+    this.lexicallyInScope = lexicallyInScope;
+  }
+  /**
+   * DL#193 Phase 2c: return a view of this scope marked lexically-in-scope (see
+   * {@link lexicallyInScope}). Used by the server target on its root scope; child scopes
+   * inherit the flag automatically through {@link childVariableFor} / {@link childVariableForWithData}.
+   */
+  asLexical() {
+    if (this.lexicallyInScope) return this;
+    return new Variables(
+      this.currentType,
+      this.parent,
+      this.depth,
+      this.currentVar,
+      this.children,
+      true
+    );
   }
   resolveAccessor(accessor) {
     if (accessor[0] === "jay") {
       const jayPath = ["__jay", ...accessor.slice(1)];
       return new Accessor(this.currentVar, jayPath, [], JayString);
     }
+    if (accessor[0] === PARENT_TOKEN) {
+      let parentLevel = 0;
+      let scope = this;
+      let terms = accessor;
+      while (terms[0] === PARENT_TOKEN) {
+        parentLevel++;
+        if (!scope.parent) {
+          const message = `${"$parent".repeat(parentLevel)} used but there is no parent scope ${parentLevel} level(s) up`;
+          return new Accessor(
+            this.currentVar,
+            terms.slice(1),
+            [message],
+            JayUnknown,
+            parentLevel
+          );
+        }
+        scope = scope.parent;
+        terms = terms.slice(1);
+      }
+      const resolved = scope.resolveAccessor(terms);
+      const effectiveParentLevel = scope.lexicallyInScope ? resolved.parentLevel : parentLevel + resolved.parentLevel;
+      return new Accessor(
+        scope.currentVar,
+        resolved.terms,
+        resolved.validations,
+        resolved.resolvedType,
+        effectiveParentLevel
+      );
+    }
     let curr = this.currentType;
     let validations = [];
     accessor.forEach((member) => {
@@ -13506,7 +13613,14 @@ class Variables {
     if (this.children[path2]) return this.children[path2];
     else {
       const resolvedForEachType = accessor.resolvedType.itemType;
-      const variables = new Variables(resolvedForEachType, this, this.depth + 1);
+      const variables = new Variables(
+        resolvedForEachType,
+        this,
+        this.depth + 1,
+        void 0,
+        {},
+        this.lexicallyInScope
+      );
       this.children[path2] = variables;
       return variables;
     }
@@ -13522,7 +13636,14 @@ class Variables {
         depth++;
         parent = parent.parent;
       }
-      const variables = new Variables(accessor.resolvedType, this, depth);
+      const variables = new Variables(
+        accessor.resolvedType,
+        this,
+        depth,
+        void 0,
+        {},
+        this.lexicallyInScope
+      );
       this.children[path2] = variables;
       return variables;
     }
@@ -13677,6 +13798,7 @@ function doParse(expression, startRule, vars, throwOnError = false) {
       da: Imports.for(Import.dynamicAttribute),
       dp: Imports.for(Import.dynamicProperty),
       ba: Imports.for(Import.booleanAttribute),
+      cx: Imports.for(Import.classNames),
       startRule
     });
   } catch (e2) {
@@ -13697,8 +13819,19 @@ function parseAccessor(expression, vars) {
 function parseCondition(expression, vars) {
   return doParse(expression, "conditionFunc", vars);
 }
+function guardReactParentBinding(fragment) {
+  if (fragment.parentDepth === 0) return fragment;
+  return new RenderFragment(
+    fragment.rendered,
+    fragment.imports,
+    [...fragment.validations, "$parent bindings are not supported in the React target"],
+    fragment.refs,
+    fragment.recursiveRegions,
+    fragment.parentDepth
+  );
+}
 function parseReactCondition(expression, vars) {
-  return doParse(expression, "condition", vars);
+  return guardReactParentBinding(doParse(expression, "condition", vars));
 }
 function parseTextExpression(expression, vars) {
   return doParse(expression, "dynamicText", vars);
@@ -13721,7 +13854,9 @@ function unescapeBackslash(jsCode) {
   });
 }
 function parseReactTextExpression(expression, vars) {
-  return doParse(expression, "reactDynamicText", vars).map((_) => unescapeBackslash(_));
+  return guardReactParentBinding(
+    doParse(expression, "reactDynamicText", vars).map((_) => unescapeBackslash(_))
+  );
 }
 function parseBooleanAttributeExpression(expression, vars) {
   return doParse(expression, "booleanAttribute", vars);
@@ -13733,7 +13868,7 @@ function parsePropertyExpression(expression, vars) {
   return doParse(expression, "dynamicProperty", vars);
 }
 function parseReactPropertyExpression(expression, vars) {
-  return doParse(expression, "reactDynamicProperty", vars);
+  return guardReactParentBinding(doParse(expression, "reactDynamicProperty", vars));
 }
 function parseComponentPropExpression(expression, vars) {
   return doParse(expression, "dynamicComponentProp", vars);
@@ -13741,23 +13876,34 @@ function parseComponentPropExpression(expression, vars) {
 function parseClassExpression(expression, vars) {
   return doParse(expression, "classExpression", vars);
 }
+const UNSUPPORTED_TARGET_PARENT_MESSAGE = "$parent bindings are not yet supported in the server target";
+class UnsupportedServerParentBindingError extends Error {
+  constructor() {
+    super(UNSUPPORTED_TARGET_PARENT_MESSAGE);
+    this.name = "UnsupportedServerParentBindingError";
+  }
+}
+function guardServerParentBinding(fragment) {
+  if (fragment.parentDepth === 0) return fragment;
+  throw new UnsupportedServerParentBindingError();
+}
 function parseServerTemplateExpression(expression, vars) {
-  return doParse(expression, "template", vars);
+  const [fragment, isDynamic] = doParse(expression, "template", vars);
+  return [guardServerParentBinding(fragment), isDynamic];
 }
 function parseTemplateParts(value) {
   if (!value) return [];
   return doParse(value, "templateParts");
 }
 function parseServerCondition(expression, vars) {
-  return doParse(expression, "condition", vars);
+  return guardServerParentBinding(doParse(expression, "condition", vars));
 }
 function parseReactClassExpression(expression, vars) {
-  const { rendered, validations, refs } = doParse(
-    expression,
-    "reactClassExpression",
-    vars
+  const parsed = doParse(expression, "reactClassExpression", vars);
+  const { rendered, validations, refs } = parsed;
+  return guardReactParentBinding(
+    new RenderFragment(rendered, Imports.none(), validations, refs, [], parsed.parentDepth)
   );
-  return new RenderFragment(rendered, Imports.none(), validations, refs);
 }
 function parseImportNames(expression) {
   return doParse(expression, "importNames", void 0, true);
@@ -14136,7 +14282,7 @@ const isComponentType = (type2) => type2 instanceof JayComponentType || type2 in
 const isComponentRef = (ref) => isComponentType(ref.elementType);
 const isCollectionRef = (ref) => ref.repeated;
 const isComponentCollectionRef = (ref) => isCollectionRef(ref) && isComponentRef(ref);
-function renderRefsType(refs, refsType, generateTarget = GenerateTarget.jay) {
+function renderRefsType(refs, refsType, generateTarget = GenerateTarget.jay, emitComponentRefHelpers = true, emittedHelpers) {
   let renderedRefs;
   let imports = Imports.none();
   const componentRefs = /* @__PURE__ */ new Map();
@@ -14193,7 +14339,7 @@ function renderRefsType(refs, refsType, generateTarget = GenerateTarget.jay) {
         }
         return `${indent.curr}${ref.ref}: ${referenceType}`;
       }).join(",\n");
-      const childTypes = Object.entries(refsTree.children).filter(([_, childRefNode]) => {
+      const childTypes = Object.entries(refsTree.children).filter(([, childRefNode]) => {
         return childRefNode.imported || hasRefs(childRefNode, false);
       }).map(([childName, childRefNode]) => {
         if (childRefNode.imported) {
@@ -14213,20 +14359,28 @@ ${allTypes}
 ${indent.lastLine}}`;
     };
     const mainType = generateTypeForPath(refs, new Indent("", true, true));
-    const renderedComponentRefs = [...componentRefs].map(([componentName, refsNeeded]) => {
+    const renderedComponentRefs = emitComponentRefHelpers ? [...componentRefs].map(([componentName, refsNeeded]) => {
       const elementType = generateTarget === GenerateTarget.jay ? `ReturnType<typeof ${componentName}>` : "any";
-      let refTypes = `export type ${componentName}Ref<ParentVS> = MapEventEmitterViewState<ParentVS, ${elementType}>;`;
-      imports = imports.plus(Import.MapEventEmitterViewState);
-      if (refsNeeded === 1) {
-        refTypes += `
-export type ${componentName}Refs<ParentVS> =
-    ComponentCollectionProxy<ParentVS, ${componentName}Ref<ParentVS>> &
-    OnlyEventEmitters<${componentName}Ref<ParentVS>>
-`;
+      const refId = `${componentName}Ref`;
+      const refsId = `${componentName}Refs`;
+      const parts = [];
+      if (!emittedHelpers?.has(refId)) {
+        parts.push(
+          `export type ${refId}<ParentVS> = MapEventEmitterViewState<ParentVS, ${elementType}>;`
+        );
+        imports = imports.plus(Import.MapEventEmitterViewState);
+        emittedHelpers?.add(refId);
+      }
+      if (refsNeeded === 1 && !emittedHelpers?.has(refsId)) {
+        parts.push(`export type ${refsId}<ParentVS> =
+    ComponentCollectionProxy<ParentVS, ${refId}<ParentVS>> &
+    OnlyEventEmitters<${refId}<ParentVS>>
+`);
         imports = imports.plus(Import.ComponentCollectionProxy).plus(Import.OnlyEventEmitters);
+        emittedHelpers?.add(refsId);
       }
-      return refTypes;
-    });
+      return parts.join("\n");
+    }).filter(Boolean) : [];
     renderedRefs = `${renderedComponentRefs.join("\n")}
 export interface ${refsType} ${mainType}`;
   } else renderedRefs = `export interface ${refsType} {}`;
@@ -14241,16 +14395,6 @@ class RefNameGenerator {
   newAutoRefNameGenerator() {
     return "aR" + this.nextId++;
   }
-  /**
-   * Register a constName as used with the given Variables context.
-   * This is used when an imported ref is used to ensure later refs
-   * with the same name get a different suffix.
-   */
-  registerUsedConstName(constName, variables) {
-    if (!this.constNamesToVariables.has(constName)) {
-      this.constNamesToVariables.set(constName, variables);
-    }
-  }
   newConstantName(refName, variables) {
     let suffix = 2;
     let constName = camelCase$1(`ref ${refName}`);
@@ -14528,6 +14672,8 @@ const REFERENCE_MANAGER_TYPES = {
 function renderReferenceManager(refs, target) {
   const { referenceManagerInit, imports } = REFERENCE_MANAGER_TYPES[target];
   const options = target === 0 ? "options, " : "";
+  let usesComponentRefsImpl = false;
+  let usesComponentCollectionRefsImpl = false;
   const usedRefManagerNames = /* @__PURE__ */ new Set();
   const usedRefConstNames = /* @__PURE__ */ new Set();
   const collectReservedConstNames = (refsTree) => {
@@ -14587,11 +14733,15 @@ function renderReferenceManager(refs, target) {
     const elemCollectionRefsDeclarations = elemCollectionRefs.map((ref) => `'${ref.ref}'`).join(", ");
     const compRefsDeclarations = compRefs.map((ref) => `'${ref.ref}'`).join(", ");
     const compCollectionRefsDeclarations = compCollectionRefs.map((ref) => `'${ref.ref}'`).join(", ");
+    const elemRefVars = elemRefs.map((ref) => getUniqueRefConstName(ref));
+    const elemCollectionRefVars = elemCollectionRefs.map((ref) => getUniqueRefConstName(ref));
+    const compRefVars = compRefs.map((ref) => getUniqueRefConstName(ref));
+    const compCollectionRefVars = compCollectionRefs.map((ref) => getUniqueRefConstName(ref));
     const refVariables = [
-      ...elemRefs.map((ref) => getUniqueRefConstName(ref)),
-      ...elemCollectionRefs.map((ref) => getUniqueRefConstName(ref)),
-      ...compRefs.map((ref) => getUniqueRefConstName(ref)),
-      ...compCollectionRefs.map((ref) => getUniqueRefConstName(ref))
+      ...elemRefVars,
+      ...elemCollectionRefVars,
+      ...compRefVars,
+      ...compCollectionRefVars
     ].join(", ");
     const childRenderedRefManagers = [];
     const childRefManagerMembers = [];
@@ -14606,11 +14756,38 @@ function renderReferenceManager(refs, target) {
 }` : "";
     const renderedRefManager = `    const [${name}, [${refVariables}]] =
         ${referenceManagerInit}(${options}[${elemRefsDeclarations}], [${elemCollectionRefsDeclarations}], [${compRefsDeclarations}], [${compCollectionRefsDeclarations}]${childRefManager});`;
-    return [...childRenderedRefManagers, renderedRefManager].join("\n");
+    const emitFreeRefManager = (ref, constName, regionIsCollection) => {
+      const freeMgrName = `${constName}FreeRefManager`;
+      const asCollection = (free) => regionIsCollection || free.repeated;
+      const elementNames = ref.freeRefs.filter((free) => !asCollection(free)).map((free) => `'${free.name}'`).join(", ");
+      const collectionNames = ref.freeRefs.filter((free) => asCollection(free)).map((free) => `'${free.name}'`).join(", ");
+      const forCall = `${referenceManagerInit}(${options}[${elementNames}], [${collectionNames}], [], [])`;
+      if (regionIsCollection) {
+        usesComponentCollectionRefsImpl = true;
+        return `    const [${freeMgrName}] = ${forCall};
+    (${name}.get('${ref.ref}') as ComponentCollectionRefImpl<any, any>).setFreeRefManager(${freeMgrName});`;
+      } else {
+        usesComponentRefsImpl = true;
+        return `    const [${freeMgrName}] = ${forCall};
+    (${name}.get('${ref.ref}') as ComponentRefsImpl<any, any>).setFreeRefManager(${freeMgrName});`;
+      }
+    };
+    const freeRefManagerLines = target === 0 ? [
+      ...compRefs.map((ref, i) => ({ ref, constName: compRefVars[i] })).filter(({ ref }) => ref.freeRefs && ref.freeRefs.length > 0).map(({ ref, constName }) => emitFreeRefManager(ref, constName, false)),
+      ...compCollectionRefs.map((ref, i) => ({ ref, constName: compCollectionRefVars[i] })).filter(({ ref }) => ref.freeRefs && ref.freeRefs.length > 0).map(({ ref, constName }) => emitFreeRefManager(ref, constName, true))
+    ] : [];
+    return [...childRenderedRefManagers, renderedRefManager, ...freeRefManagerLines].join("\n");
   };
   if (hasRefs(refs, true)) {
     const renderedRefsManager = renderRefManagerNode("refManager", refs);
-    return { renderedRefsManager, refsManagerImport: imports };
+    let refsManagerImport = imports;
+    if (usesComponentRefsImpl)
+      refsManagerImport = refsManagerImport.plus(Imports.for(Import.ComponentRefsImpl));
+    if (usesComponentCollectionRefsImpl)
+      refsManagerImport = refsManagerImport.plus(
+        Imports.for(Import.ComponentCollectionRefImpl)
+      );
+    return { renderedRefsManager, refsManagerImport };
   } else {
     const renderedRefsManager = `const [refManager, []] = ${referenceManagerInit}(${options}[], [], [], []);`;
     return { renderedRefsManager, refsManagerImport: imports };
@@ -14618,16 +14795,27 @@ function renderReferenceManager(refs, target) {
 }
 function renderImports$1(imports, importsFor, componentImports, importerMode) {
   const runtimeImport = imports.render(importsFor);
-  let renderedComponentImports = componentImports.map((importStatement) => {
-    let symbols = importStatement.names.map((symbol) => symbol.as ? `${symbol.name} as ${symbol.as}` : symbol.name).join(", ");
-    let imports2 = [];
-    imports2.push(
-      `import {${symbols}} from "${importStatement.module}${getModeFileExtension(
-        importStatement.sandbox,
-        importerMode
-      )}";`
-    );
-    return imports2.join("\n");
+  const mergedByModule = /* @__PURE__ */ new Map();
+  for (const importStatement of componentImports) {
+    const key = `${importStatement.sandbox ? "sandbox:" : ""}${importStatement.module}`;
+    let entry = mergedByModule.get(key);
+    if (!entry) {
+      entry = { link: { ...importStatement, names: [] }, symbols: /* @__PURE__ */ new Set() };
+      mergedByModule.set(key, entry);
+    }
+    for (const symbol of importStatement.names) {
+      const rendered = symbol.as ? `${symbol.name} as ${symbol.as}` : symbol.name;
+      if (entry.symbols.has(rendered)) continue;
+      entry.symbols.add(rendered);
+      entry.link.names.push(symbol);
+    }
+  }
+  let renderedComponentImports = [...mergedByModule.values()].map(({ link }) => {
+    let symbols = link.names.map((symbol) => symbol.as ? `${symbol.name} as ${symbol.as}` : symbol.name).join(", ");
+    return `import {${symbols}} from "${link.module}${getModeFileExtension(
+      link.sandbox,
+      importerMode
+    )}";`;
   });
   return [runtimeImport, ...renderedComponentImports].join("\n");
 }
@@ -14837,6 +15025,12 @@ const DIRECTIVE_ATTRIBUTES = /* @__PURE__ */ new Set([
   "slow",
   "jay-coordinate-base",
   "jay-scope",
+  // Component provenance marker stamped by the parser on `<jay:Name>` usage tags (DL#123 discovery).
+  // Read by the coordinate/discovery pipeline, never a component prop or a rendered attribute.
+  "jc",
+  // DL#202 — template-side content-slot marker. A pure build-time authoring directive read by the
+  // drift/sync differ; it rides into the flattened page copy (verbatim flatten) but must never render.
+  "jay-content",
   AsyncDirectiveTypes.loading.directive,
   AsyncDirectiveTypes.resolved.directive,
   AsyncDirectiveTypes.rejected.directive
@@ -18960,7 +19154,7 @@ function dedentYaml(text2) {
   const minIndent = Math.min(...lines.map((l) => l.match(/^\s*/)?.[0].length ?? 0));
   return lines.map((l) => l.slice(minIndent)).join("\n");
 }
-async function parseHeadlessImports(elements, validations, filePath, importResolver, projectRoot) {
+async function parseHeadlessImports(elements, validations, filePath, importResolver, projectRoot, options) {
   const result = [];
   for await (const element of elements) {
     const pluginAttr = element.getAttribute("plugin");
@@ -18972,10 +19166,16 @@ async function parseHeadlessImports(elements, validations, filePath, importResol
       );
       continue;
     }
-    if (!pluginAttr) {
-      validations.push("headless import must specify plugin attribute");
+    const asAttr = element.getAttribute("as") ?? void 0;
+    if (asAttr && !/^[a-z][a-z0-9-]*$/.test(asAttr)) {
+      validations.push(
+        `Headless component as="${asAttr}" is not a valid region tag name. Use kebab-case (e.g., as="feature-card").`
+      );
       continue;
     }
+    const srcAttr = element.getAttribute("src") ?? void 0;
+    const templateAttr = element.getAttribute("template") ?? void 0;
+    const suppressedValidations = (element.getAttribute("jay-validations") ?? "").split(/[\s,]+/).map((s) => s.trim().toUpperCase()).filter(Boolean);
     if (!contractAttr) {
       validations.push("headless import must specify contract attribute");
       continue;
@@ -18997,41 +19197,75 @@ async function parseHeadlessImports(elements, validations, filePath, importResol
         );
       }
     }
-    const resolveResult = importResolver.resolvePluginComponent(
-      pluginAttr,
-      contractAttr,
-      projectRoot
-    );
-    validations.push(...resolveResult.validations);
-    if (!resolveResult.val) {
-      continue;
-    }
-    const absoluteComponentPath = resolveResult.val.componentPath;
-    const name = resolveResult.val.componentName;
-    const isNpmPackage = resolveResult.val.isNpmPackage;
-    const packageName = resolveResult.val.packageName;
+    let loadedContract;
+    let contractFile;
+    let contractMetadata = void 0;
     let module;
-    if (isNpmPackage && packageName) {
-      module = packageName;
-    } else {
-      module = path.relative(filePath, absoluteComponentPath);
-      if (!module.startsWith(".")) {
-        module = "./" + module;
-      }
-    }
+    let name;
+    let structural = false;
+    let contractTagName = contractAttr;
     try {
-      const contractResult = importResolver.loadPluginContract(
-        pluginAttr,
-        contractAttr,
-        projectRoot
-      );
-      validations.push(...contractResult.validations);
-      if (!contractResult.val) {
-        continue;
+      if (pluginAttr) {
+        const resolveResult = importResolver.resolvePluginComponent(
+          pluginAttr,
+          contractAttr,
+          projectRoot
+        );
+        validations.push(...resolveResult.validations);
+        if (!resolveResult.val) {
+          continue;
+        }
+        const absoluteComponentPath = resolveResult.val.componentPath;
+        name = resolveResult.val.componentName;
+        const isNpmPackage = resolveResult.val.isNpmPackage;
+        const packageName = resolveResult.val.packageName;
+        if (isNpmPackage && packageName) {
+          module = packageName;
+        } else {
+          module = path.relative(filePath, absoluteComponentPath);
+          if (!module.startsWith(".")) module = "./" + module;
+        }
+        const contractResult = importResolver.loadPluginContract(
+          pluginAttr,
+          contractAttr,
+          projectRoot
+        );
+        validations.push(...contractResult.validations);
+        if (!contractResult.val) {
+          continue;
+        }
+        loadedContract = contractResult.val.contract;
+        contractFile = contractResult.val.contractPath;
+        contractMetadata = contractResult.val.metadata;
+      } else {
+        const contractPath = path.resolve(filePath, contractAttr);
+        const contractResult = importResolver.loadContract(contractPath);
+        validations.push(...contractResult.validations);
+        if (!contractResult.val) {
+          continue;
+        }
+        loadedContract = contractResult.val;
+        contractFile = contractPath;
+        if (srcAttr) {
+          const importedFile = importResolver.resolveLink(filePath, srcAttr);
+          const exportedComponents = importResolver.analyzeExportedTypes(importedFile, options).filter((t) => t instanceof JayComponentType);
+          if (exportedComponents.length !== 1) {
+            validations.push(
+              `headless import src="${srcAttr}" must export exactly one Jay component (found ${exportedComponents.length})`
+            );
+            continue;
+          }
+          name = exportedComponents[0].name;
+          module = path.relative(filePath, importedFile);
+          if (!module.startsWith(".")) module = "./" + module;
+        } else {
+          structural = true;
+          name = pascalCase(loadedContract.name);
+          module = "";
+        }
+        contractTagName = paramCase(loadedContract.name);
       }
-      const loadedContract = contractResult.val.contract;
-      const contractFile = contractResult.val.contractPath;
-      const contractMetadata = contractResult.val.metadata;
+      if (asAttr) contractTagName = asAttr;
       const contractTypes = await contractToImportsViewStateAndRefs(
         loadedContract,
         contractFile,
@@ -19048,13 +19282,17 @@ async function parseHeadlessImports(elements, validations, filePath, importResol
           refsTypeName,
           repeatedRefsTypeName
         );
+        const toRelativeModule = (to) => {
+          const relative = path.relative(filePath, to);
+          return relative.startsWith(".") ? relative : "./" + relative;
+        };
         const enumsToImportRelativeToJayHtml = enumsToImport.map(
           (enumsToImport2) => ({
             type: enumsToImport2.type,
-            declaringModule: path.relative(filePath, enumsToImport2.declaringModule)
+            declaringModule: toRelativeModule(enumsToImport2.declaringModule)
           })
         );
-        const relativeContractPath = path.relative(filePath, contractFile);
+        const relativeContractPath = toRelativeModule(contractFile);
         const enumsFromContract = enumsToImportRelativeToJayHtml.filter((_) => _.declaringModule === relativeContractPath).map((_) => _.type);
         const nestedTypeNames = collectNestedTypeNames(type2);
         const nestedTypeImports = nestedTypeNames.filter((name2) => name2 !== type2.name).map((name2) => ({ name: name2, type: JayUnknown }));
@@ -19098,7 +19336,7 @@ async function parseHeadlessImports(elements, validations, filePath, importResol
         };
         result.push({
           ...key && { key },
-          contractName: contractAttr,
+          contractName: contractTagName,
           refs,
           rootType: type2,
           contractLinks,
@@ -19106,355 +19344,28 @@ async function parseHeadlessImports(elements, validations, filePath, importResol
           contract: loadedContract,
           contractPath: contractFile,
           metadata: contractMetadata,
-          headlessProps
+          headlessProps,
+          ...structural && { structural },
+          ...templateAttr && { template: templateAttr },
+          ...suppressedValidations.length && { suppressedValidations }
         });
       });
     } catch (e2) {
       validations.push(`failed to parse linked contract - ${e2.message}${e2.stack}`);
     }
   }
-  return result;
-}
-function injectHeadfullFSTemplates(html2, sourceDir, importResolver) {
-  const root = parse_2(html2);
-  const allHeadfullElements = root.querySelectorAll('script[type="application/jay-headfull"]');
-  const fsElements = allHeadfullElements.filter((el) => el.getAttribute("contract"));
-  if (fsElements.length === 0) return html2;
-  const body = root.querySelector("body");
-  if (!body) return html2;
-  injectHeadfullFSTemplatesRecursive(fsElements, body, sourceDir, importResolver, /* @__PURE__ */ new Set());
-  return root.toString();
-}
-function injectHeadfullFSTemplatesRecursive(fsElements, body, sourceDir, importResolver, visited) {
-  for (const element of fsElements) {
-    const src = element.getAttribute("src");
-    const rawNames = element.getAttribute("names");
-    if (!src || !rawNames) continue;
-    const names = parseImportNames(rawNames);
-    if (names.length === 0) continue;
-    const contractName = (names[0].as || names[0].name).toLowerCase();
-    const resolvedSrc = path.resolve(sourceDir, src);
-    if (visited.has(resolvedSrc)) continue;
-    visited.add(resolvedSrc);
-    const jayHtmlResult = importResolver.readJayHtml(sourceDir, src);
-    if (!jayHtmlResult) continue;
-    const jayHtmlRoot = parse_2(jayHtmlResult.content);
-    const jayHtmlBody = jayHtmlRoot.querySelector("body");
-    if (!jayHtmlBody) continue;
-    const nestedHeadfullElements = jayHtmlRoot.querySelectorAll('script[type="application/jay-headfull"]').filter((el) => el.getAttribute("contract"));
-    if (nestedHeadfullElements.length > 0) {
-      const childDir = jayHtmlResult.componentDir;
-      injectHeadfullFSTemplatesRecursive(
-        nestedHeadfullElements,
-        jayHtmlBody,
-        childDir,
-        importResolver,
-        visited
-      );
-    }
-    const jayTags = body.querySelectorAll("*").filter((el) => el.tagName?.toLowerCase() === `jay:${contractName}`);
-    for (const jayTag of jayTags) {
-      if (!jayTag.innerHTML.trim()) {
-        jayTag.set_content(jayHtmlBody.innerHTML);
-        jayTag.setAttribute("style", "display: contents");
-        jayTag.setAttribute("jc", contractName);
-      }
-    }
+  const tagCounts = /* @__PURE__ */ new Map();
+  for (const imp of result) {
+    tagCounts.set(imp.contractName, (tagCounts.get(imp.contractName) ?? 0) + 1);
   }
-}
-async function parseHeadfullFSImports(elements, validations, filePath, importResolver, body, projectRoot, visited = /* @__PURE__ */ new Set(), sourceDir, pageLinkedCssPaths) {
-  const headlessImports = [];
-  const cssParts = [];
-  const linkedCssFiles = [];
-  const linkedComponentFiles = [];
-  for (const element of elements) {
-    const src = element.getAttribute("src");
-    const contractAttr = element.getAttribute("contract");
-    const rawNames = element.getAttribute("names");
-    if (!src) {
-      validations.push("headfull FS import must specify src attribute");
-      continue;
-    }
-    if (!contractAttr) {
-      continue;
-    }
-    if (!rawNames) {
-      validations.push(`headfull FS import for module ${src} must specify names attribute`);
-      continue;
-    }
-    const names = parseImportNames(rawNames);
-    if (names.length === 0) {
-      validations.push(
-        `headfull FS import for module ${src} does not specify what to import`
-      );
-      continue;
-    }
-    const componentExportName = names[0].name;
-    const contractName = (names[0].as || componentExportName).toLowerCase();
-    const resolvedSrc = path.resolve(filePath, src);
-    if (visited.has(resolvedSrc)) {
-      validations.push(
-        `Circular headfull FS import detected: ${src} has already been processed`
-      );
-      continue;
-    }
-    visited.add(resolvedSrc);
-    const resolveDir = sourceDir || filePath;
-    let jayHtmlResult = importResolver.readJayHtml(resolveDir, src);
-    let moduleResolveDir = resolveDir;
-    if (jayHtmlResult === null && resolveDir !== filePath) {
-      jayHtmlResult = importResolver.readJayHtml(filePath, src);
-      if (jayHtmlResult !== null) {
-        moduleResolveDir = filePath;
-      }
-    }
-    if (jayHtmlResult === null && projectRoot && projectRoot !== filePath && projectRoot !== resolveDir) {
-      jayHtmlResult = importResolver.readJayHtml(projectRoot, src);
-      if (jayHtmlResult !== null) {
-        moduleResolveDir = projectRoot;
-      }
-    }
-    if (jayHtmlResult === null) {
-      validations.push(
-        `jay-html file not found for headfull FS component ${src} (expected ${src}.jay-html)`
-      );
-      continue;
-    }
-    linkedComponentFiles.push(jayHtmlResult.filePath);
-    let contractPath = path.resolve(resolveDir, contractAttr);
-    let loadedContract;
-    try {
-      const contractResult = importResolver.loadContract(contractPath);
-      validations.push(...contractResult.validations);
-      if (!contractResult.val) {
-        continue;
-      }
-      loadedContract = contractResult.val;
-    } catch (e2) {
-      let resolved = false;
-      if (projectRoot && projectRoot !== filePath) {
-        try {
-          contractPath = path.resolve(projectRoot, contractAttr);
-          const fallbackResult = importResolver.loadContract(contractPath);
-          validations.push(...fallbackResult.validations);
-          if (!fallbackResult.val) {
-            continue;
-          }
-          loadedContract = fallbackResult.val;
-          resolved = true;
-        } catch {
-        }
-      }
-      if (!resolved) {
-        try {
-          contractPath = path.resolve(
-            jayHtmlResult.componentDir,
-            path.basename(contractAttr)
-          );
-          const fallbackResult = importResolver.loadContract(contractPath);
-          validations.push(...fallbackResult.validations);
-          if (!fallbackResult.val) {
-            continue;
-          }
-          loadedContract = fallbackResult.val;
-        } catch (e3) {
-          validations.push(
-            `Failed to load contract for headfull FS component ${src}: ${e3.message}`
-          );
-          continue;
-        }
-      }
-    }
-    const jayHtmlRoot = parse_2(jayHtmlResult.content);
-    const jayHtmlBody = jayHtmlRoot.querySelector("body");
-    if (!jayHtmlBody) {
-      validations.push(`headfull FS component ${src} jay-html must have a body tag`);
-      continue;
-    }
-    const componentDir = jayHtmlResult.componentDir;
-    const componentCssResult = await extractCss(jayHtmlRoot, componentDir, pageLinkedCssPaths);
-    validations.push(...componentCssResult.validations);
-    if (componentCssResult.val?.css) {
-      cssParts.push(`/* Component: ${contractName} */
-${componentCssResult.val.css}`);
-    }
-    if (componentCssResult.val?.linkedCssFiles) {
-      linkedCssFiles.push(...componentCssResult.val.linkedCssFiles);
-    }
-    const nestedHeadlessElements = jayHtmlRoot.querySelectorAll(
-      'script[type="application/jay-headless"]'
-    );
-    if (nestedHeadlessElements.length > 0) {
-      const nestedHeadless = await parseHeadlessImports(
-        nestedHeadlessElements,
-        validations,
-        filePath,
-        importResolver,
-        projectRoot
-      );
-      headlessImports.push(...nestedHeadless);
-    }
-    const nestedHeadfullFSElements = jayHtmlRoot.querySelectorAll('script[type="application/jay-headfull"]').filter((el) => el.getAttribute("contract"));
-    if (nestedHeadfullFSElements.length > 0) {
-      for (const nestedEl of nestedHeadfullFSElements) {
-        const nestedSrc = nestedEl.getAttribute("src");
-        if (nestedSrc) {
-          const absoluteSrc = path.resolve(componentDir, nestedSrc);
-          let relativeSrc = path.relative(filePath, absoluteSrc);
-          if (!relativeSrc.startsWith(".")) relativeSrc = "./" + relativeSrc;
-          nestedEl.setAttribute("src", relativeSrc);
-        }
-        const nestedContract = nestedEl.getAttribute("contract");
-        if (nestedContract) {
-          const absoluteContract = path.resolve(componentDir, nestedContract);
-          let relativeContract = path.relative(filePath, absoluteContract);
-          if (!relativeContract.startsWith("."))
-            relativeContract = "./" + relativeContract;
-          nestedEl.setAttribute("contract", relativeContract);
-        }
-      }
-      const nestedResult = await parseHeadfullFSImports(
-        nestedHeadfullFSElements,
-        validations,
-        filePath,
-        importResolver,
-        jayHtmlBody,
-        projectRoot,
-        visited,
-        void 0,
-        pageLinkedCssPaths
-      );
-      headlessImports.push(...nestedResult.headlessImports);
-      if (nestedResult.css) {
-        cssParts.push(nestedResult.css);
-      }
-      linkedCssFiles.push(...nestedResult.linkedCssFiles);
-      linkedComponentFiles.push(...nestedResult.linkedComponentFiles);
-    }
-    const jayTags = body.querySelectorAll("*").filter((el) => el.tagName?.toLowerCase() === `jay:${contractName}`);
-    for (const jayTag of jayTags) {
-      const existingContent = jayTag.innerHTML.trim();
-      if (existingContent) {
-        continue;
-      }
-      jayTag.set_content(jayHtmlBody.innerHTML);
-      jayTag.setAttribute("jc", contractName);
-    }
-    let resolvedSrcPath;
-    try {
-      resolvedSrcPath = importResolver.resolveLink(moduleResolveDir, src);
-    } catch {
-      resolvedSrcPath = path.resolve(moduleResolveDir, src);
-    }
-    const hasCodeFile = fs.existsSync(resolvedSrcPath + ".ts") || fs.existsSync(resolvedSrcPath + ".js") || fs.existsSync(path.join(resolvedSrcPath, "index.ts")) || fs.existsSync(path.join(resolvedSrcPath, "index.js"));
-    if (!hasCodeFile) {
-      for (const jayTag of jayTags) {
-        jayTag.replaceWith(jayTag.innerHTML);
-      }
-      continue;
-    }
-    try {
-      const contractTypes = await contractToImportsViewStateAndRefs(
-        loadedContract,
-        contractPath,
-        importResolver
-      );
-      contractTypes.map(({ type: type2, refs: subContractRefsTree, enumsToImport }) => {
-        const contractInternalName = loadedContract.name;
-        const refsTypeName = `${pascalCase(contractInternalName)}Refs`;
-        const repeatedRefsTypeName = `${pascalCase(contractInternalName)}RepeatedRefs`;
-        const refs = mkRefsTree(
-          subContractRefsTree.refs,
-          subContractRefsTree.children,
-          subContractRefsTree.repeated,
-          refsTypeName,
-          repeatedRefsTypeName
-        );
-        const relativeContractPath = path.relative(filePath, contractPath);
-        const enumsToImportRelativeToJayHtml = enumsToImport.map(
-          (enumToImport) => ({
-            type: enumToImport.type,
-            declaringModule: path.relative(filePath, enumToImport.declaringModule)
-          })
-        );
-        const enumsFromContract = enumsToImportRelativeToJayHtml.filter((_) => _.declaringModule === relativeContractPath).map((_) => _.type);
-        const nestedTypeNames = collectNestedTypeNames(type2);
-        const nestedTypeImports = nestedTypeNames.filter((name) => name !== type2.name).map((name) => ({ name, type: JayUnknown }));
-        const contractLink = {
-          module: relativeContractPath,
-          names: [
-            { name: type2.name, type: type2 },
-            { name: refsTypeName, type: JayUnknown },
-            ...nestedTypeImports,
-            ...enumsFromContract.map((_) => ({ name: _.name, type: _ }))
-          ]
-        };
-        const enumsFromOtherContracts = deduplicateEnums(
-          enumsToImportRelativeToJayHtml.filter(
-            (_) => _.declaringModule !== relativeContractPath
-          )
-        );
-        const enumImportLinks = Object.entries(
-          enumsFromOtherContracts.reduce(
-            (acc, enumToImport) => {
-              const module = enumToImport.declaringModule;
-              if (!acc[module]) {
-                acc[module] = [];
-              }
-              acc[module].push(enumToImport);
-              return acc;
-            },
-            {}
-          )
-        ).map(([module, enums]) => ({
-          module,
-          names: enums.map((enumToImport) => ({
-            name: enumToImport.type.name,
-            type: enumToImport.type
-          }))
-        }));
-        const contractLinks = [contractLink, ...enumImportLinks];
-        let resolvedModulePath;
-        try {
-          resolvedModulePath = importResolver.resolveLink(moduleResolveDir, src);
-        } catch {
-          resolvedModulePath = path.resolve(moduleResolveDir, src);
-        }
-        let relativeModule = path.relative(filePath, resolvedModulePath);
-        if (!relativeModule.startsWith(".")) {
-          relativeModule = "./" + relativeModule;
-        }
-        const codeLink = {
-          module: relativeModule,
-          names: [
-            {
-              name: componentExportName,
-              type: new JayComponentType(componentExportName, [])
-            }
-          ]
-        };
-        headlessImports.push({
-          contractName,
-          refs,
-          rootType: type2,
-          contractLinks,
-          codeLink,
-          contract: loadedContract,
-          contractPath
-        });
-      });
-    } catch (e2) {
+  for (const [tag, count] of tagCounts) {
+    if (count > 1) {
       validations.push(
-        `failed to parse contract for headfull FS component ${src} - ${e2.message}${e2.stack}`
+        `Two headless imports back the same <jay:${tag}> region tag. Add as="<alias>" to one of them to flatten them as distinct design variants (e.g. as="feature-${tag}" → <jay:feature-${tag}>).`
       );
     }
   }
-  return {
-    headlessImports,
-    css: cssParts.length > 0 ? cssParts.join("\n\n") : void 0,
-    linkedCssFiles,
-    linkedComponentFiles
-  };
+  return result;
 }
 function normalizeFilename(filename) {
   return filename.replace(".jay-html", "");
@@ -19588,7 +19499,7 @@ function resolveNestedCssImports(css, cssDir, visited) {
     if (seen.has(resolved)) return `/* circular import: ${importPath} */`;
     seen.add(resolved);
     try {
-      const imported = fs.readFileSync(resolved, "utf-8");
+      const imported = fs$1.readFileSync(resolved, "utf-8");
       return `/* @import ${importPath} */
 ${resolveNestedCssImports(imported, path.dirname(resolved), seen)}`;
     } catch {
@@ -19610,9 +19521,8 @@ async function extractCss(root, filePath, skipPaths) {
       if (filePath) {
         const cssFilePath = path.resolve(filePath, href);
         linkedCssFiles.push(cssFilePath);
-        if (skipPaths?.has(cssFilePath)) continue;
         try {
-          const cssContent = await fs$1.readFile(cssFilePath, "utf-8");
+          const cssContent = await fs.readFile(cssFilePath, "utf-8");
           const resolvedCss = resolveNestedCssImports(
             cssContent,
             path.dirname(cssFilePath)
@@ -19707,10 +19617,16 @@ async function parseJayFile(html2, filename, filePath, options, linkedContractRe
   const { val: jayYaml, validations } = parseYaml(root);
   if (validations.length > 0) return new WithValidations(void 0, validations);
   const allHeadfullElements = root.querySelectorAll('script[type="application/jay-headfull"]');
+  for (const el of allHeadfullElements) {
+    if (el.getAttribute("contract")) {
+      validations.push(
+        `application/jay-headfull with a contract attribute is no longer supported (DL#196). Declare the component with application/jay-headless and flatten it into a <jay:X> region (run \`jay-stack sync\`).`
+      );
+    }
+  }
   const regularHeadfullElements = allHeadfullElements.filter(
     (el) => !el.getAttribute("contract")
   );
-  const fsHeadfullElements = allHeadfullElements.filter((el) => el.getAttribute("contract"));
   const headfullImports = parseHeadfullImports(
     regularHeadfullElements,
     validations,
@@ -19723,33 +19639,15 @@ async function parseJayFile(html2, filename, filePath, options, linkedContractRe
     validations.push(`jay file must have exactly a body tag`);
     return new WithValidations(void 0, validations);
   }
-  const pageLinkedCssPaths = /* @__PURE__ */ new Set();
-  for (const link of root.querySelectorAll('head link[rel="stylesheet"]')) {
-    const href = link.getAttribute("href");
-    if (href && !href.startsWith("http://") && !href.startsWith("https://") && !href.startsWith("//")) {
-      pageLinkedCssPaths.add(path.resolve(filePath, href));
-    }
-  }
-  const headfullFSResult = await parseHeadfullFSImports(
-    fsHeadfullElements,
-    validations,
-    filePath,
-    linkedContractResolver,
-    body,
-    projectRoot,
-    void 0,
-    // visited
-    sourceDir,
-    pageLinkedCssPaths
-  );
   const headlessImports = await parseHeadlessImports(
     root.querySelectorAll('script[type="application/jay-headless"]'),
     validations,
     filePath,
     linkedContractResolver,
-    projectRoot
+    projectRoot,
+    options
   );
-  const allHeadlessImports = [...headlessImports, ...headfullFSResult.headlessImports];
+  const allHeadlessImports = [...headlessImports];
   resolveEnumCollisions(allHeadlessImports);
   const importNames = headfullImports.flatMap((_) => _.names);
   const types2 = await parseTypes(
@@ -19780,17 +19678,11 @@ async function parseJayFile(html2, filename, filePath, options, linkedContractRe
   validations.push(...cssResult.validations);
   if (validations.length > 0) return new WithValidations(void 0, validations);
   let css = cssResult.val?.css;
-  if (headfullFSResult.css) {
-    css = css ? css + "\n\n" + headfullFSResult.css : headfullFSResult.css;
-  }
   if (css) {
     detectCssNameCollisions(css, validations);
   }
-  let allLinkedCssFiles = cssResult.val?.linkedCssFiles || [];
-  if (headfullFSResult.linkedCssFiles.length > 0) {
-    allLinkedCssFiles = [...allLinkedCssFiles, ...headfullFSResult.linkedCssFiles];
-  }
-  const allLinkedComponentFiles = headfullFSResult.linkedComponentFiles;
+  const allLinkedCssFiles = cssResult.val?.linkedCssFiles || [];
+  const allLinkedComponentFiles = [];
   const { serverTrackByMap, clientTrackByMap } = extractTrackByMaps(
     jayYaml.parsedContract,
     allHeadlessImports
@@ -20117,7 +20009,15 @@ function generateRefsInterface(contract, refs) {
 ${repeatedRefsRendered}`;
   return { imports: imports.plus(imports2), renderedRefs };
 }
-function generatePropsInterface(contractName, props) {
+function collectViewStateEnumNames(type2, acc = /* @__PURE__ */ new Set()) {
+  if (isEnumType(type2)) acc.add(type2.name);
+  else if (isObjectType$1(type2))
+    for (const key of Object.keys(type2.props)) collectViewStateEnumNames(type2.props[key], acc);
+  else if (isArrayType$1(type2) || isPromiseType(type2))
+    collectViewStateEnumNames(type2.itemType, acc);
+  return acc;
+}
+function generatePropsInterface(contractName, props, existingEnumNames = /* @__PURE__ */ new Set()) {
   const propsTypeName = `${contractName}Props`;
   const enums = [];
   if (props.length === 0) {
@@ -20129,10 +20029,13 @@ function generatePropsInterface(contractName, props) {
     let typeName;
     if (isEnumType(prop.dataType)) {
       typeName = prop.dataType.name;
-      const genEnum = `export enum ${prop.dataType.name} {
+      if (!existingEnumNames.has(prop.dataType.name)) {
+        const genEnum = `export enum ${prop.dataType.name} {
 ${prop.dataType.values.map((_) => "  " + _).join(",\n")}
 }`;
-      enums.push(genEnum);
+        enums.push(genEnum);
+        existingEnumNames.add(prop.dataType.name);
+      }
     } else if (isAtomicType(prop.dataType)) {
       typeName = prop.dataType.name;
     } else {
@@ -20198,9 +20101,11 @@ async function compileContract(contractWithValidations, contractFilePath, jayImp
       const propsTypeName = `${contractName}Props`;
       let renderedProps = "";
       if (hasProps) {
+        const existingEnumNames = collectViewStateEnumNames(type2);
         const { propsInterface, propsEnums } = generatePropsInterface(
           contractName,
-          contract.props
+          contract.props,
+          existingEnumNames
         );
         renderedProps = propsEnums ? `${propsEnums}
 
@@ -20876,10 +20781,13 @@ ${indent.firstLine}    }`;
       allImports = allImports.plus(Import.adoptElement);
     }
     const itemRootCoordForEach = element.getAttribute(COORD_ATTR) || "0";
+    const bodyParentDepth = Math.max(itemContent.parentDepth, createChildren.parentDepth);
+    const dependsOnParent = bodyParentDepth > 0;
     const hydrateForEachFragment = new RenderFragment(
       `${indent.firstLine}hydrateForEach(${forEachFragment.rendered}, '${trackBy}', '${itemRootCoordForEach}',
 ${indent.firstLine}    ${adoptBody},
-${indent.firstLine}    ${createBody},
+${indent.firstLine}    ${createBody},${dependsOnParent ? `
+${indent.firstLine}    true,` : ""}
 ${indent.firstLine})`,
       allImports,
       [
@@ -20887,7 +20795,9 @@ ${indent.firstLine})`,
         ...itemContent.validations,
         ...createChildren.validations
       ],
-      mergeRefsTrees(itemContent.refs, itemRefFragment.refs)
+      mergeRefsTrees(itemContent.refs, itemRefFragment.refs),
+      [],
+      Math.max(forEachFragment.parentDepth, Math.max(0, bodyParentDepth - 1))
     );
     return nestRefs(forEachAccessor.terms, hydrateForEachFragment);
   }
@@ -20937,7 +20847,7 @@ function renderHydrateHeadlessInstance(element, context, renderContext, contract
   } else {
     coordinateKey2 = instanceCoord;
   }
-  const componentVariables = new Variables(headlessImport.rootType);
+  const componentVariables = new Variables(headlessImport.rootType, renderContext.variables);
   const childNodes = filterContentNodes(element.childNodes);
   if (childNodes.length === 0) {
     return new RenderFragment("", Imports.none(), [
@@ -20987,14 +20897,50 @@ ${adoptChildren.rendered}
 ${adoptChildIndent.firstLine}])`,
       adoptChildren.imports.plus(Import.adoptElement),
       adoptChildren.validations,
-      adoptChildren.refs
+      adoptChildren.refs,
+      adoptChildren.recursiveRegions,
+      // DL#193 Capability A: preserve the deepest `$parent` climb so the usage site
+      // still weakens gates when instance content spans multiple root children.
+      adoptChildren.parentDepth
     );
   }
-  const adoptMergedRefs = mergeContractStubRefs(adoptInlineBody.refs, headlessImport.refs);
+  const contractRefNames = /* @__PURE__ */ new Set();
+  const collectContractRefNames = (tree) => {
+    for (const r of tree.refs) contractRefNames.add(camelCase$1(r.ref));
+    for (const child of Object.values(tree.children)) collectContractRefNames(child);
+  };
+  collectContractRefNames(headlessImport.refs);
+  const freeRefDecls = [];
+  const seenFreeRefNames = /* @__PURE__ */ new Set();
+  const collectFreeRefs = (tree) => {
+    for (const r of tree.refs) {
+      if (isComponentType$1(r.elementType)) continue;
+      if (contractRefNames.has(camelCase$1(r.ref))) continue;
+      if (seenFreeRefNames.has(r.ref)) continue;
+      seenFreeRefNames.add(r.ref);
+      freeRefDecls.push({
+        name: r.ref,
+        repeated: r.repeated,
+        viewStateType: r.viewStateType.name,
+        elementType: r.elementType.name
+      });
+    }
+    for (const child of Object.values(tree.children)) collectFreeRefs(child);
+  };
+  collectFreeRefs(adoptInlineBody.refs);
+  const freeRefNames = freeRefDecls.map((f) => f.name);
+  const freeRefsArg = freeRefNames.length > 0 ? `
+    [${freeRefNames.map((r) => `'${r}'`).join(", ")}],` : "";
+  const adoptMergedRefs = hoistFreeRefs(
+    mergeContractStubRefs(adoptInlineBody.refs, headlessImport.refs),
+    new Set(freeRefNames)
+  );
   const { renderedRefsManager, refsManagerImport } = renderReferenceManager(
     adoptMergedRefs,
     ReferenceManagerTarget.element
   );
+  const refOriginalName = element.attributes.ref || context.refNameGenerator.newAutoRefNameGenerator();
+  const refRefName = camelCase$1(refOriginalName);
   const adoptRenderFnCode = `
 // Hydrate inline template for headless component: ${contractName} #${idx}
 type ${elementType} = JayElement<${interactiveViewStateType}, ${refsTypeName}>;
@@ -21011,22 +20957,31 @@ ${adoptInlineBody.rendered}
 }`;
   let adoptComponentSymbol;
   let adoptComponentDef;
-  if (isInsideForEach) {
+  const coordinateArg = isInsideForEach ? `(dataIds) => [...dataIds, '${coordinateSuffix}'].toString()` : `'${coordinateKey2}'`;
+  if (headlessImport.structural) {
+    adoptComponentSymbol = `_Headless${pascal}${idx}`;
+    adoptComponentDef = `const ${adoptComponentSymbol} = makePassthroughHeadlessInstanceComponent(
+    ${renderFnName},
+    ${coordinateArg},${freeRefsArg}
+);`;
+  } else if (isInsideForEach) {
     adoptComponentSymbol = `_Headless${pascal}${idx}Adopt`;
     adoptComponentDef = `const ${adoptComponentSymbol} = makeHeadlessInstanceComponent(
     ${renderFnName},
     ${pluginComponentName},
-    (dataIds) => [...dataIds, '${coordinateSuffix}'].toString(),
+    (dataIds) => [...dataIds, '${coordinateSuffix}'].toString(),${freeRefsArg}
 );`;
   } else {
     adoptComponentSymbol = `_Headless${pascal}${idx}`;
     adoptComponentDef = `const ${adoptComponentSymbol} = makeHeadlessInstanceComponent(
     ${renderFnName},
     ${pluginComponentName},
-    '${coordinateKey2}',
+    '${coordinateKey2}',${freeRefsArg}
 );`;
   }
-  let adoptImports = adoptInlineBody.imports.plus(refsManagerImport).plus(Import.ConstructContext).plus(Import.makeHeadlessInstanceComponent);
+  let adoptImports = adoptInlineBody.imports.plus(refsManagerImport).plus(Import.ConstructContext).plus(
+    headlessImport.structural ? Import.makePassthroughHeadlessInstanceComponent : Import.makeHeadlessInstanceComponent
+  );
   const ifCondition = element.attributes.if;
   const needsCreateVersion = !!ifCondition;
   let createComponentSymbol;
@@ -21067,7 +21022,10 @@ ${createRenderedChildren.rendered}
     } else {
       createInlineBody = createRenderedChildren;
     }
-    const createMergedRefs = mergeContractStubRefs(createInlineBody.refs, headlessImport.refs);
+    const createMergedRefs = hoistFreeRefs(
+      mergeContractStubRefs(createInlineBody.refs, headlessImport.refs),
+      new Set(freeRefNames)
+    );
     const { renderedRefsManager: createRefsManager, refsManagerImport: createRefsImport } = renderReferenceManager(createMergedRefs, ReferenceManagerTarget.element);
     createRenderFnCode = `
 function ${createRenderFnName}(options?: RenderElementOptions): ${preRenderType} {
@@ -21079,10 +21037,10 @@ ${createInlineBody.rendered}
     return [refManager.getPublicAPI() as ${refsTypeName}, render];
 }
 
-const ${createComponentSymbol} = makeHeadlessInstanceComponent(
-    ${createRenderFnName},
-    ${pluginComponentName},
-    ${isInsideForEach ? `(dataIds) => [...dataIds, '${coordinateSuffix}'].toString()` : `'${coordinateKey2}'`},
+const ${createComponentSymbol} = ${headlessImport.structural ? "makePassthroughHeadlessInstanceComponent" : "makeHeadlessInstanceComponent"}(
+    ${createRenderFnName},${headlessImport.structural ? "" : `
+    ${pluginComponentName},`}
+    ${isInsideForEach ? `(dataIds) => [...dataIds, '${coordinateSuffix}'].toString()` : `'${coordinateKey2}'`},${freeRefsArg}
 );`;
     createImports = createInlineBody.imports.plus(createRefsImport);
   }
@@ -21090,7 +21048,7 @@ const ${createComponentSymbol} = makeHeadlessInstanceComponent(
     componentSymbol: adoptComponentSymbol,
     renderFnName,
     renderFnCode: adoptRenderFnCode + "\n" + adoptComponentDef + (createRenderFnCode ? "\n" + createRenderFnCode : ""),
-    pluginComponentName,
+    pluginComponentName: headlessImport.structural ? void 0 : pluginComponentName,
     imports: adoptImports.plus(createImports)
   });
   const propsGetterAndRefs = renderChildCompProps$1(
@@ -21099,8 +21057,6 @@ const ${createComponentSymbol} = makeHeadlessInstanceComponent(
     headlessImport.contract?.props
   );
   const getProps = `(${context.variables.currentVar}: ${context.variables.currentType.name}) => ${propsGetterAndRefs.rendered}`;
-  const refOriginalName = element.attributes.ref || context.refNameGenerator.newAutoRefNameGenerator();
-  const refRefName = camelCase$1(refOriginalName);
   const refConstName = context.refNameGenerator.newConstantName(refRefName, context.variables);
   const isRepeated = context.dynamicRef;
   const contractRefType = isRepeated ? `${pascal}RepeatedRefs` : `${pascal}Refs`;
@@ -21109,6 +21065,22 @@ const ${createComponentSymbol} = makeHeadlessInstanceComponent(
       link.names.push({ name: contractRefType, type: JayUnknown });
     }
   }
+  const augmented = freeRefsAugmentedRefType(contractRefType, freeRefDecls, isRepeated);
+  if (freeRefDecls.length > 0) {
+    for (const f of freeRefDecls) {
+      if (!f.viewStateType) continue;
+      for (const link of headlessImport.contractLinks) {
+        if (!link.names.some((n) => n.name === f.viewStateType)) {
+          link.names.push({ name: f.viewStateType, type: JayUnknown });
+        }
+      }
+    }
+  }
+  let freeRefProxyImports = Imports.for();
+  if (augmented.needsElementProxy)
+    freeRefProxyImports = freeRefProxyImports.plus(Import.HTMLElementProxy);
+  if (augmented.needsCollectionProxy)
+    freeRefProxyImports = freeRefProxyImports.plus(Import.HTMLElementCollectionProxy);
   const instanceRef = mkRef(
     refRefName,
     refOriginalName,
@@ -21116,25 +21088,25 @@ const ${createComponentSymbol} = makeHeadlessInstanceComponent(
     isRepeated,
     !element.attributes.ref,
     context.variables.currentType,
-    new JayTypeAlias(contractRefType)
-  );
-  let renderedRef = new RenderFragment(
-    `${refConstName}()`,
-    Imports.for(),
-    [],
-    mkRefsTree([instanceRef], {})
+    new JayTypeAlias(augmented.type),
+    // DL#198 — declare free refs on the page-side region ref so the page-level renderReferenceManager
+    // emits the per-region FreeReferenceManager (`${refConstName}FreeRefManager`) + setFreeRefManager.
+    freeRefDecls.length > 0 ? freeRefDecls : void 0
   );
+  const instanceRefsTree = mkRefsTree([instanceRef], {});
+  let renderedRef = new RenderFragment(`${refConstName}()`, Imports.for(), [], instanceRefsTree);
   if (renderedRef.rendered !== "") renderedRef = renderedRef.map((_) => ", " + _);
+  const freeRefManagerArg = freeRefNames.length > 0 ? `, ${refConstName}FreeRefManager` : "";
   const scopeRootCoord = childScopeId ? `'${childScopeId}/0'` : "undefined";
   if (ifCondition) {
     const renderedCondition = parseCondition(ifCondition, context.variables);
-    const adoptCall = `() => childCompHydrate(${adoptComponentSymbol}, ${getProps}, ${scopeRootCoord}${renderedRef.rendered})`;
-    const createCall = `() => childComp(${createComponentSymbol}, ${getProps}${renderedRef.rendered})`;
+    const adoptCall = `() => childCompHydrate(${adoptComponentSymbol}, ${getProps}, ${scopeRootCoord}${renderedRef.rendered}${freeRefManagerArg})`;
+    const createCall = `() => childComp(${createComponentSymbol}, ${getProps}${renderedRef.rendered}${freeRefManagerArg})`;
     const callExpr = `${context.indent.firstLine}hydrateConditional(${renderedCondition.rendered}, ${adoptCall},
 ${context.indent.firstLine}    ${createCall})`;
     return new RenderFragment(
       callExpr,
-      Imports.for(Import.childCompHydrate, Import.hydrateConditional, Import.childComp).plus(propsGetterAndRefs.imports).plus(renderedRef.imports).plus(renderedCondition.imports),
+      Imports.for(Import.childCompHydrate, Import.hydrateConditional, Import.childComp).plus(propsGetterAndRefs.imports).plus(renderedRef.imports).plus(renderedCondition.imports).plus(freeRefProxyImports),
       [
         ...propsGetterAndRefs.validations,
         ...adoptInlineBody.validations,
@@ -21144,8 +21116,8 @@ ${context.indent.firstLine}    ${createCall})`;
     );
   }
   return new RenderFragment(
-    `${context.indent.firstLine}childCompHydrate(${adoptComponentSymbol}, ${getProps}, ${scopeRootCoord}${renderedRef.rendered})`,
-    Imports.for(Import.childCompHydrate).plus(propsGetterAndRefs.imports).plus(renderedRef.imports),
+    `${context.indent.firstLine}childCompHydrate(${adoptComponentSymbol}, ${getProps}, ${scopeRootCoord}${renderedRef.rendered}${freeRefManagerArg})`,
+    Imports.for(Import.childCompHydrate).plus(propsGetterAndRefs.imports).plus(renderedRef.imports).plus(freeRefProxyImports),
     [
       ...propsGetterAndRefs.validations,
       ...adoptInlineBody.validations,
@@ -21221,6 +21193,7 @@ function renderHydrateElementContent(element, context, renderContext, coordinate
     let childImports = Imports.none();
     const childValidations = [];
     const childRefs = [];
+    let childParentDepth = 0;
     for (const child of childNodes) {
       if (child.nodeType !== NodeType.ELEMENT_NODE) continue;
       const htmlChild = child;
@@ -21234,6 +21207,7 @@ function renderHydrateElementContent(element, context, renderContext, coordinate
           childImports = childImports.plus(frag.imports);
           childValidations.push(...frag.validations);
           if (frag.refs) childRefs.push(frag.refs);
+          childParentDepth = Math.max(childParentDepth, frag.parentDepth);
         }
       } else {
         const htmlChild2 = child;
@@ -21256,6 +21230,7 @@ function renderHydrateElementContent(element, context, renderContext, coordinate
           childImports = childImports.plus(frag.imports);
           childValidations.push(...frag.validations);
           if (frag.refs) childRefs.push(frag.refs);
+          childParentDepth = Math.max(childParentDepth, frag.parentDepth);
         } else {
           childParts.push(`${indent.firstLine}STATIC`);
           childImports = childImports.plus(Import.STATIC);
@@ -21263,12 +21238,16 @@ function renderHydrateElementContent(element, context, renderContext, coordinate
       }
     }
     const refSuffix2 = renderedRef.rendered ? `, ${renderedRef.rendered}` : "";
-    const childrenArr2 = childParts.length ? `[${childParts.join(",\n")}]` : "[]";
+    const childrenArr2 = childParts.length ? `[
+${childParts.join(",\n")}
+${indent.firstLine}]` : "[]";
     return new RenderFragment(
       `${indent.firstLine}adoptDynamicElement("${coordinate}", ${attributes2.rendered}, ${childrenArr2}${refSuffix2})`,
       Imports.for(Import.adoptDynamicElement).plus(attributes2.imports).plus(childImports).plus(renderedRef.imports),
       [...attributes2.validations, ...childValidations, ...renderedRef.validations],
-      mergeRefsTrees(...childRefs, renderedRef.refs)
+      mergeRefsTrees(...childRefs, renderedRef.refs),
+      [],
+      Math.max(childParentDepth, attributes2.parentDepth)
     );
   }
   if (hasMixedContentDynamicText2 && !hasDynamicAttrs) {
@@ -21276,6 +21255,7 @@ function renderHydrateElementContent(element, context, renderContext, coordinate
     let childImports = Imports.none();
     const childValidations = [];
     const childRefs = [];
+    let childParentDepth = 0;
     childNodes.forEach((child) => {
       if (child.nodeType === NodeType.ELEMENT_NODE) {
         const frag = renderHydrateNode(child, context);
@@ -21284,6 +21264,7 @@ function renderHydrateElementContent(element, context, renderContext, coordinate
           childImports = childImports.plus(frag.imports);
           childValidations.push(...frag.validations);
           if (frag.refs) childRefs.push(frag.refs);
+          childParentDepth = Math.max(childParentDepth, frag.parentDepth);
         }
       }
     });
@@ -21299,6 +21280,7 @@ function renderHydrateElementContent(element, context, renderContext, coordinate
             );
             childImports = childImports.plus(Import.adoptText).plus(rendered.imports.minus(Import.dynamicText));
             childValidations.push(...rendered.validations);
+            childParentDepth = Math.max(childParentDepth, rendered.parentDepth);
           }
         }
       }
@@ -21309,7 +21291,9 @@ function renderHydrateElementContent(element, context, renderContext, coordinate
       `${indent.firstLine}adoptElement("${coordinate}", ${attributes2.rendered}, ${childrenArr2}${refSuffix2})`,
       Imports.for(Import.adoptElement).plus(attributes2.imports).plus(childImports).plus(renderedRef.imports),
       [...attributes2.validations, ...childValidations, ...renderedRef.validations],
-      mergeRefsTrees(...childRefs, renderedRef.refs)
+      mergeRefsTrees(...childRefs, renderedRef.refs),
+      [],
+      childParentDepth
     );
   }
   if (isHtmlStringChild && textFragment && !hasDynamicAttrs) {
@@ -21319,7 +21303,9 @@ function renderHydrateElementContent(element, context, renderContext, coordinate
       `${indent.firstLine}adoptElement("${coordinate}", ${attributes2.rendered}, [dh(${accessor})]${refSuffix2})`,
       Imports.for(Import.adoptElement).plus(Import.dynamicHtml).plus(textFragment.imports.minus(Import.dynamicText)).plus(renderedRef.imports).plus(attributes2.imports),
       [...textFragment.validations, ...renderedRef.validations, ...attributes2.validations],
-      renderedRef.refs
+      renderedRef.refs,
+      [],
+      textFragment.parentDepth
     );
   }
   if (textFragment && !hasDynamicAttrs) {
@@ -21334,13 +21320,19 @@ function renderHydrateElementContent(element, context, renderContext, coordinate
           ...renderedRef.validations,
           ...attributes2.validations
         ],
-        renderedRef.refs
+        renderedRef.refs,
+        [],
+        // DL#193 Capability A: carry the `$parent` climb up so enclosing forEach gates weaken.
+        textFragment.parentDepth
       );
     }
     return new RenderFragment(
       `${indent.firstLine}adoptText("${coordinate}", ${accessor})`,
       Imports.for(Import.adoptText).plus(textFragment.imports.minus(Import.dynamicText)),
-      [...textFragment.validations]
+      [...textFragment.validations],
+      mkRefsTree([], {}),
+      [],
+      textFragment.parentDepth
     );
   }
   if (hasDynamicAttrs) {
@@ -21348,6 +21340,7 @@ function renderHydrateElementContent(element, context, renderContext, coordinate
     let childImports = Imports.none();
     let childValidations = [];
     let childRefs;
+    let childParentDepth = 0;
     if (textFragment) {
       const accessor = textFragment.rendered.replace(/^dt\(/, "").replace(/\)$/, "");
       childrenRendered = `[adoptText("${coordinate}", ${accessor})]`;
@@ -21355,6 +21348,7 @@ function renderHydrateElementContent(element, context, renderContext, coordinate
         textFragment.imports.minus(Import.dynamicText)
       );
       childValidations = textFragment.validations;
+      childParentDepth = textFragment.parentDepth;
     } else {
       const children = mergeHydrateFragments(
         childNodes.map((child) => renderHydrateNode(child, context)),
@@ -21365,6 +21359,7 @@ function renderHydrateElementContent(element, context, renderContext, coordinate
         childImports = children.imports;
         childValidations = children.validations;
         childRefs = children.refs;
+        childParentDepth = children.parentDepth;
       }
     }
     const refSuffix2 = renderedRef.rendered ? `, ${renderedRef.rendered}` : "";
@@ -21372,7 +21367,11 @@ function renderHydrateElementContent(element, context, renderContext, coordinate
       `${indent.firstLine}adoptElement("${coordinate}", ${attributes2.rendered}, ${childrenRendered}${refSuffix2})`,
       Imports.for(Import.adoptElement).plus(attributes2.imports).plus(childImports).plus(renderedRef.imports),
       [...attributes2.validations, ...childValidations, ...renderedRef.validations],
-      mergeRefsTrees(...[childRefs, renderedRef.refs].filter(Boolean))
+      mergeRefsTrees(...[childRefs, renderedRef.refs].filter(Boolean)),
+      [],
+      // DL#193 Phase 2a: carry the override binding's `$parent` climb up (attributes may
+      // themselves be `$parent`-bound; a wrapping element adds no scope).
+      Math.max(childParentDepth, attributes2.parentDepth)
     );
   }
   const childFragments = mergeHydrateFragments(
@@ -21385,7 +21384,11 @@ function renderHydrateElementContent(element, context, renderContext, coordinate
     `${indent.firstLine}adoptElement("${coordinate}", {}, ${childrenArr}${refSuffix})`,
     Imports.for(Import.adoptElement).plus(childFragments.imports).plus(renderedRef.imports),
     [...childFragments.validations, ...renderedRef.validations],
-    mergeRefsTrees(childFragments.refs, renderedRef.refs)
+    mergeRefsTrees(childFragments.refs, renderedRef.refs),
+    [],
+    // DL#193 Capability A: a wrapping element adds no scope, so carry children's `$parent`
+    // climb up unchanged so enclosing forEach gates weaken.
+    childFragments.parentDepth
   );
 }
 function renderHydrate(types2, body, importStatements, elementType, preRenderType, refsType, headlessImports, contract) {
@@ -21411,7 +21414,9 @@ function renderHydrate(types2, body, importStatements, elementType, preRenderTyp
   };
   const rootElement = ensureSingleChildElement(body);
   if (!rootElement.val) {
-    return new RenderFragment("", Imports.none(), rootElement.validations);
+    return {
+      fragment: new RenderFragment("", Imports.none(), rootElement.validations)
+    };
   }
   const rootComponentMatch = getComponentName(
     rootElement.val.rawTagName,
@@ -21437,8 +21442,8 @@ function renderHydrate(types2, body, importStatements, elementType, preRenderTyp
     ReferenceManagerTarget.element
   );
   const hasAdoptCalls = renderedHydrate.rendered.trim().length > 0;
-  const hydrateBody = hasAdoptCalls ? `() =>
-${renderedHydrate.rendered}` : `() => ({ dom: rootElement, update: () => {}, mount: () => {}, unmount: () => {} })`;
+  const hydrateBody = !hasAdoptCalls ? `() => ({ dom: rootElement, update: () => {}, mount: () => {}, unmount: () => {} })` : `() =>
+${renderedHydrate.rendered}`;
   const headlessDefsCode = context.headlessInstanceDefs.map((def) => def.renderFnCode).join("\n");
   let headlessImportsAll = Imports.none();
   for (const def of context.headlessInstanceDefs) {
@@ -21453,12 +21458,14 @@ ${renderedRefsManager}
   const fullOutput = headlessDefsCode ? `${headlessDefsCode}
 
 ${hydrateFunction}` : hydrateFunction;
-  return new RenderFragment(
-    fullOutput,
-    Imports.for(Import.ConstructContext, Import.RenderElementOptions).plus(renderedHydrate.imports).plus(refsManagerImport).plus(headlessImportsAll),
-    renderedHydrate.validations,
-    renderedHydrate.refs
-  );
+  return {
+    fragment: new RenderFragment(
+      fullOutput,
+      Imports.for(Import.ConstructContext, Import.RenderElementOptions).plus(renderedHydrate.imports).plus(refsManagerImport).plus(headlessImportsAll),
+      renderedHydrate.validations,
+      renderedHydrate.refs
+    )
+  };
 }
 function renderFunctionDeclaration(preRenderType) {
   return `export declare function render(options?: RenderElementOptions): ${preRenderType}`;
@@ -21549,7 +21556,7 @@ function renderDynamicAttributes(element, { variables }) {
     if (isDirectiveAttribute(attrCanonical)) return;
     if (attrCanonical === "style") {
       const styleFragment = renderStyleAttribute(attributes2[attrName], variables);
-      if (styleFragment.imports.has(Import.dynamicAttribute)) {
+      if (styleFragment.imports.has(Import.dynamicAttribute) || styleFragment.imports.has(Import.dynamicProperty)) {
         renderedAttributes.push(styleFragment);
       }
     } else if (attrCanonical === "class") {
@@ -21640,6 +21647,21 @@ function renderElementRef$1(element, { dynamicRef, variables, importedRefNameToR
     return new RenderFragment(`${constName}()`, Imports.none(), [], refs);
   } else return RenderFragment.empty();
 }
+function coerceStaticComponentProp(value, expectedType) {
+  if (!expectedType) return void 0;
+  if (isEnumType(expectedType)) {
+    return expectedType.values.includes(value) ? `${expectedType.alias ?? expectedType.name}.${value}` : void 0;
+  }
+  if (expectedType.name === "number") {
+    return /^-?\d+(\.\d+)?$/.test(value) ? value : void 0;
+  }
+  if (expectedType.name === "boolean") {
+    if (value === "true") return "true";
+    if (value === "false") return "false";
+    return void 0;
+  }
+  return void 0;
+}
 function renderChildCompProps$1(element, { variables }, contractProps) {
   let attributes2 = element.attributes;
   let props = [];
@@ -21657,10 +21679,15 @@ function renderChildCompProps$1(element, { variables }, contractProps) {
     if (attrCanonical === "ref") {
       return;
     } else {
-      let prop = parseComponentPropExpression(attributes2[attrName], variables);
+      const rawValue = attributes2[attrName];
+      const isStatic = !rawValue.includes("{");
+      let prop = parseComponentPropExpression(rawValue, variables);
       const outputKey = contractProps?.find((p) => p.name.toLowerCase() === attrCanonical)?.name ?? attrKey;
       const expectedType = propTypeMap?.get(attrName) ?? propTypeMap?.get(outputKey);
-      if (expectedType && expectedType.name === "string" && /^\d+$/.test(prop.rendered)) {
+      const coerced = isStatic ? coerceStaticComponentProp(rawValue.trim(), expectedType) : void 0;
+      if (coerced !== void 0) {
+        prop = prop.map(() => coerced);
+      } else if (expectedType && expectedType.name === "string" && /^\d+$/.test(prop.rendered)) {
         prop = prop.map((_) => `'${_}'`);
       }
       props.push(prop.map((_) => `${outputKey}: ${_}`));
@@ -21733,7 +21760,9 @@ function renderNode(node2, context) {
       children.imports.plus(Import.dynamicElement).plus(attributes2.imports).plus(ref.imports).plus(tagFunc.import),
       [...attributes2.validations, ...children.validations, ...ref.validations],
       mergeRefsTrees(attributes2.refs, children.refs, ref.refs),
-      [...attributes2.recursiveRegions, ...children.recursiveRegions, ...ref.recursiveRegions]
+      [...attributes2.recursiveRegions, ...children.recursiveRegions, ...ref.recursiveRegions],
+      // DL#193: carry the deepest `$parent` climb up so scope-switch rules can force it.
+      Math.max(attributes2.parentDepth, children.parentDepth, ref.parentDepth)
     );
   }
   function e2(tagName, attributes2, children, ref, currIndent = indent) {
@@ -21744,7 +21773,9 @@ function renderNode(node2, context) {
       children.imports.plus(Import.element).plus(attributes2.imports).plus(ref.imports).plus(tagFunc.import),
       [...attributes2.validations, ...children.validations, ...ref.validations],
       mergeRefsTrees(attributes2.refs, children.refs, ref.refs),
-      [...attributes2.recursiveRegions, ...children.recursiveRegions, ...ref.recursiveRegions]
+      [...attributes2.recursiveRegions, ...children.recursiveRegions, ...ref.recursiveRegions],
+      // DL#193: carry the deepest `$parent` climb up so scope-switch rules can force it.
+      Math.max(attributes2.parentDepth, children.parentDepth, ref.parentDepth)
     );
   }
   function renderHtmlElement(htmlElement, newContext) {
@@ -21857,7 +21888,8 @@ ${contextForChildren.indent.firstLine}` : children
         result.imports.plus(Import.baseJayElement),
         result.validations,
         result.refs,
-        [...result.recursiveRegions, recursiveRegion]
+        [...result.recursiveRegions, recursiveRegion],
+        result.parentDepth
       );
     }
     return result;
@@ -21870,17 +21902,26 @@ ${indent.firstLine})`,
       Imports.merge(childElement.imports, renderedCondition.imports).plus(Import.conditional),
       [...renderedCondition.validations, ...childElement.validations],
       mergeRefsTrees(renderedCondition.refs, childElement.refs),
-      [...renderedCondition.recursiveRegions, ...childElement.recursiveRegions]
+      [...renderedCondition.recursiveRegions, ...childElement.recursiveRegions],
+      // DL#193: `if` is not a data-scope switch — it re-runs its body on every parent
+      // update at runtime, so the residual `$parent` depth passes through unchanged.
+      Math.max(renderedCondition.parentDepth, childElement.parentDepth)
     );
   }
   function renderForEach(renderedForEach, collectionVariables, trackBy, childElement) {
+    const dependsOnParent = childElement.parentDepth > 0;
+    const residualParentDepth = Math.max(
+      renderedForEach.parentDepth,
+      Math.max(0, childElement.parentDepth - 1)
+    );
     return new RenderFragment(
       `${indent.firstLine}forEach(${renderedForEach.rendered}, (${collectionVariables.currentVar}: ${collectionVariables.currentType.name}) => {
-${indent.curr}return ${childElement.rendered}}, '${trackBy}')`,
+${indent.curr}return ${childElement.rendered}}, '${trackBy}'${dependsOnParent ? ", true" : ""})`,
       childElement.imports.plus(Import.forEach),
       [...renderedForEach.validations, ...childElement.validations],
       childElement.refs,
-      [...renderedForEach.recursiveRegions, ...childElement.recursiveRegions]
+      [...renderedForEach.recursiveRegions, ...childElement.recursiveRegions],
+      residualParentDepth
     );
   }
   function renderAsync(asyncType, getPromiseFragment, childElement, resolvedGenericTypes) {
@@ -21889,7 +21930,10 @@ ${indent.curr}return ${childElement.rendered}}, '${trackBy}')`,
       childElement.imports.plus(asyncType.import),
       [...getPromiseFragment.validations, ...childElement.validations],
       childElement.refs,
-      [...getPromiseFragment.recursiveRegions, ...childElement.recursiveRegions]
+      [...getPromiseFragment.recursiveRegions, ...childElement.recursiveRegions],
+      // DL#193: `when`/async is a data-scope switch; it re-runs its body on every parent
+      // update at runtime (no flag needed), and the residual `$parent` depth drops by one.
+      Math.max(getPromiseFragment.parentDepth, Math.max(0, childElement.parentDepth - 1))
     );
   }
   function renderNestedComponent(htmlElement, newContext, componentName) {
@@ -21932,7 +21976,7 @@ ${indent.curr}return ${childElement.rendered}}, '${trackBy}')`,
         link.names.push({ name: interactiveViewStateType, type: JayUnknown });
       }
     }
-    const componentVariables = new Variables(headlessImport.rootType);
+    const componentVariables = new Variables(headlessImport.rootType, newContext.variables);
     const childIndent = newContext.indent.child(false);
     const childNodes = filterContentNodes(htmlElement.childNodes);
     let inlineBody;
@@ -21958,6 +22002,18 @@ ${indent.curr}return ${childElement.rendered}}, '${trackBy}')`,
         recursiveRegions: [],
         isInsideGuard: false,
         insideFastForEach: false,
+        // Each inline template compiles into its OWN `_headless…Render` function, so its ref
+        // const names (`refCardAction`) are function-local. Give it a fresh generator so two
+        // instances of the same contract don't dedup across the boundary (`refCardAction` in
+        // both, not `refCardAction` / `refCardAction2`).
+        refNameGenerator: new RefNameGenerator(),
+        // DL#193 Phase 3: an instance's OWN template refs are always single — the instance is
+        // one unit. When the instance is repeated at the usage site (inside a forEach), that
+        // collection-ness is captured by the page-level ref manager collecting the instances,
+        // not by the instance's inner refs. Reset `dynamicRef` so forwarded inner refs (e.g.
+        // `<jay:Counter ref="cta">`) stay single here; contract-declared refs already use the
+        // stub's `repeated` flag via importedRefNameToRef, so they are unaffected.
+        dynamicRef: false,
         // Pass headless contract names through so nested headless instances
         // inside headfull FS component templates can be detected (DL#123)
         headlessContractNames: newContext.headlessContractNames
@@ -21974,13 +22030,46 @@ ${renderedChildren.rendered}
           renderedChildren.imports.plus(Import.dynamicElement),
           renderedChildren.validations,
           renderedChildren.refs,
-          renderedChildren.recursiveRegions
+          renderedChildren.recursiveRegions,
+          // DL#193 Capability A: preserve the deepest `$parent` climb so the usage site
+          // still weakens gates when instance content spans multiple root children.
+          renderedChildren.parentDepth
         );
       } else {
         inlineBody = renderedChildren;
       }
     }
-    const mergedRefs = mergeContractStubRefs(inlineBody.refs, headlessImport.refs);
+    const refOriginalName = htmlElement.attributes.ref || newContext.refNameGenerator.newAutoRefNameGenerator();
+    const refRefName = camelCase$1(refOriginalName);
+    const contractRefNames = /* @__PURE__ */ new Set();
+    const collectContractRefNames = (tree) => {
+      for (const r of tree.refs) contractRefNames.add(camelCase$1(r.ref));
+      for (const child of Object.values(tree.children)) collectContractRefNames(child);
+    };
+    collectContractRefNames(headlessImport.refs);
+    const freeRefDecls = [];
+    const seenFreeRefNames = /* @__PURE__ */ new Set();
+    const collectFreeRefs = (tree) => {
+      for (const r of tree.refs) {
+        if (isComponentType$1(r.elementType)) continue;
+        if (contractRefNames.has(camelCase$1(r.ref))) continue;
+        if (seenFreeRefNames.has(r.ref)) continue;
+        seenFreeRefNames.add(r.ref);
+        freeRefDecls.push({
+          name: r.ref,
+          repeated: r.repeated,
+          viewStateType: r.viewStateType.name,
+          elementType: r.elementType.name
+        });
+      }
+      for (const child of Object.values(tree.children)) collectFreeRefs(child);
+    };
+    collectFreeRefs(inlineBody.refs);
+    const freeRefNames = freeRefDecls.map((f) => f.name);
+    const mergedRefs = hoistFreeRefs(
+      mergeContractStubRefs(inlineBody.refs, headlessImport.refs),
+      new Set(freeRefNames)
+    );
     const { renderedRefsManager, refsManagerImport } = renderReferenceManager(
       mergedRefs,
       ReferenceManagerTarget.element
@@ -21999,6 +22088,17 @@ ${renderedChildren.rendered}
     const coordinateSuffix = `${contractName}:${coordinateRef}`;
     const instanceCoordBase = htmlElement.getAttribute("jay-coordinate-base");
     const coordinateKey2 = isInsideForEach ? void 0 : instanceCoordBase || coordinateSuffix;
+    const coordinateArg = isInsideForEach ? `(dataIds) => [...dataIds, '${coordinateSuffix}'].toString()` : `'${coordinateKey2}'`;
+    const freeRefsArg = freeRefNames.length > 0 ? `
+    [${freeRefNames.map((r) => `'${r}'`).join(", ")}],` : "";
+    const componentDefCode = headlessImport.structural ? `const ${componentSymbol} = makePassthroughHeadlessInstanceComponent(
+    ${renderFnName},
+    ${coordinateArg},${freeRefsArg}
+);` : `const ${componentSymbol} = makeHeadlessInstanceComponent(
+    ${renderFnName},
+    ${pluginComponentName},
+    ${coordinateArg},${freeRefsArg}
+);`;
     const renderFnCode = `
 // Inline template for headless component: ${contractName} #${idx}
 type ${elementType} = JayElement<${interactiveViewStateType}, ${refsTypeName}>;
@@ -22014,11 +22114,7 @@ ${inlineBody.rendered}
     return [refManager.getPublicAPI() as ${refsTypeName}, render];
 }
 
-const ${componentSymbol} = makeHeadlessInstanceComponent(
-    ${renderFnName},
-    ${headlessImport.structural ? `{ comp: (_props, _refs) => ({ render: () => _props }) }` : pluginComponentName},
-    ${isInsideForEach ? `(dataIds) => [...dataIds, '${coordinateSuffix}'].toString()` : `'${coordinateKey2}'`},
-);`;
+${componentDefCode}`;
     newContext.headlessInstanceDefs.push({
       componentSymbol,
       renderFnName,
@@ -22031,9 +22127,8 @@ const ${componentSymbol} = makeHeadlessInstanceComponent(
       newContext,
       headlessImport.contract?.props
     );
-    let getProps = `(${newContext.variables.currentVar}: ${newContext.variables.currentType.name}) => ${propsGetterAndRefs.rendered}`;
-    const refOriginalName = htmlElement.attributes.ref || newContext.refNameGenerator.newAutoRefNameGenerator();
-    const refRefName = camelCase$1(refOriginalName);
+    const outerVar = newContext.variables.currentVar;
+    let getProps = `(${outerVar}: ${newContext.variables.currentType.name}) => ${propsGetterAndRefs.rendered}`;
     const refConstName = newContext.refNameGenerator.newConstantName(
       refRefName,
       newContext.variables
@@ -22046,6 +22141,18 @@ const ${componentSymbol} = makeHeadlessInstanceComponent(
       }
     }
     newContext.usedComponentImports.add(contractRefType);
+    const augmented = freeRefsAugmentedRefType(contractRefType, freeRefDecls, isRepeated);
+    if (freeRefDecls.length > 0) {
+      for (const f of freeRefDecls) {
+        if (!f.viewStateType) continue;
+        for (const link of headlessImport.contractLinks) {
+          if (!link.names.some((n) => n.name === f.viewStateType)) {
+            link.names.push({ name: f.viewStateType, type: JayUnknown });
+          }
+        }
+        newContext.usedComponentImports.add(f.viewStateType);
+      }
+    }
     const instanceRef = mkRef(
       refRefName,
       refOriginalName,
@@ -22053,18 +22160,30 @@ const ${componentSymbol} = makeHeadlessInstanceComponent(
       isRepeated,
       !htmlElement.attributes.ref,
       newContext.variables.currentType,
-      new JayTypeAlias(contractRefType)
+      new JayTypeAlias(augmented.type),
+      // DL#198 — declare free refs on the page-side region ref so renderReferenceManager emits the
+      // per-region FreeReferenceManager (with per-free-ref `repeated` driving element vs collection).
+      freeRefDecls.length > 0 ? freeRefDecls : void 0
     );
+    const instanceRefsTree = mkRefsTree([instanceRef], {});
     let renderedRef = new RenderFragment(
       `${refConstName}()`,
       Imports.for(),
       [],
-      mkRefsTree([instanceRef], {})
+      instanceRefsTree
     );
     if (renderedRef.rendered !== "") renderedRef = renderedRef.map((_) => ", " + _);
+    const freeRefManagerArg = freeRefNames.length > 0 ? `, ${refConstName}FreeRefManager` : "";
+    let childCompImports = Imports.for(Import.childComp).plus(propsGetterAndRefs.imports).plus(renderedRef.imports).plus(Import.ConstructContext).plus(
+      headlessImport.structural ? Import.makePassthroughHeadlessInstanceComponent : Import.makeHeadlessInstanceComponent
+    );
+    if (augmented.needsElementProxy)
+      childCompImports = childCompImports.plus(Import.HTMLElementProxy);
+    if (augmented.needsCollectionProxy)
+      childCompImports = childCompImports.plus(Import.HTMLElementCollectionProxy);
     return new RenderFragment(
-      `${newContext.indent.firstLine}childComp(${componentSymbol}, ${getProps}${renderedRef.rendered})`,
-      Imports.for(Import.childComp).plus(propsGetterAndRefs.imports).plus(renderedRef.imports).plus(Import.ConstructContext).plus(Import.makeHeadlessInstanceComponent),
+      `${newContext.indent.firstLine}childComp(${componentSymbol}, ${getProps}${renderedRef.rendered}${freeRefManagerArg})`,
+      childCompImports,
       [
         ...propsGetterAndRefs.validations,
         ...inlineBody.validations,
@@ -22113,7 +22232,11 @@ const ${componentSymbol} = makeHeadlessInstanceComponent(
           nestedChildElement.imports.plus(Import.withData).plus(accessorExpr.render().imports),
           [...accessorExpr.validations, ...nestedChildElement.validations],
           nestedChildElement.refs,
-          nestedChildElement.recursiveRegions
+          nestedChildElement.recursiveRegions,
+          // DL#193: `with-data` is a data-scope switch; it re-runs its body on every
+          // parent update at runtime (no flag needed), and the residual `$parent`
+          // depth drops by one.
+          Math.max(0, nestedChildElement.parentDepth - 1)
         );
       } else if (isRecurse(htmlElement)) {
         const refAttr = htmlElement.getAttribute("ref");
@@ -22187,7 +22310,6 @@ const ${componentSymbol} = makeHeadlessInstanceComponent(
           isInsideGuard: true,
           // Mark that we're inside a guard
           insideFastForEach: true
-          // Fast-phase forEach — headless instances not supported
         };
         let childElement = renderHtmlElement(htmlElement, newContext);
         return nestRefs(
@@ -22295,9 +22417,7 @@ function renderFunctionImplementation$1(types2, rootBodyElement, importStatement
   const variables = new Variables(types2);
   const { importedSymbols, importedSandboxedSymbols } = processImportedComponents(importStatements);
   const importedRefNameToRef = processImportedHeadless(headlessImports);
-  const headlessContractNames = new Set(
-    headlessImports.filter((h) => !h.structural).map((h) => h.contractName)
-  );
+  const headlessContractNames = new Set(headlessImports.map((h) => h.contractName));
   assignCoordinates(rootBodyElement, { headlessContractNames });
   const rootElement = ensureSingleChildElement(rootBodyElement);
   let renderedRoot;
@@ -22359,8 +22479,12 @@ ${renderedRoot.rendered}
   if (headLinks.length > 0) {
     imports = imports.plus(Import.injectHeadLinks);
   }
-  const { imports: refImports, renderedRefs } = renderRefsType(renderedRoot.refs, refsType);
+  const { imports: refImports, renderedRefs: renderedPageRefs } = renderRefsType(
+    renderedRoot.refs,
+    refsType
+  );
   imports = imports.plus(refImports);
+  const renderedRefs = renderedPageRefs;
   let renderedElement = `export type ${elementType} = JayElement<${viewStateType}, ${refsType}>
 export type ${renderType2} = RenderElement<${viewStateType}, ${refsType}, ${elementType}>
 export type ${preRenderType} = [${refsType}, ${renderType2}]
@@ -22374,10 +22498,11 @@ ${Indent.forceIndent(code, 4)},
         funcRepository)`
     );
   }
-  const { renderedRefsManager } = renderReferenceManager(
+  const { renderedRefsManager, refsManagerImport } = renderReferenceManager(
     renderedRoot.refs,
     ReferenceManagerTarget.element
   );
+  imports = imports.plus(refsManagerImport);
   const headLinksInjection = headLinks.length > 0 ? `    injectHeadLinks(${renderHeadLinksArray(headLinks)});
     ` : "";
   const recursiveFunctions = generateRecursiveFunctions(renderedRoot.recursiveRegions);
@@ -22389,11 +22514,12 @@ ${recursiveFunctions}
   for (const def of headlessInstanceDefs) {
     imports = imports.plus(def.imports);
   }
+  const rootCallback = `() => ${renderedRoot.rendered.trim()}`;
   const body = `${headlessDefsCode}export function render(options?: RenderElementOptions): ${preRenderType} {
-${renderedRefsManager}    
+${renderedRefsManager}
 ${headLinksInjection}${recursiveFunctionsSection}    const render = (viewState: ${viewStateType}) => ConstructContext.withRootContext(
         viewState, refManager,
-        () => ${renderedRoot.rendered.trim()}
+        ${rootCallback}
     ) as ${elementType};
     return [refManager.getPublicAPI() as ${refsType}, render];
 }`;
@@ -22498,11 +22624,15 @@ function generateElementFile(jayFile, importerMode) {
   const usedHeadlessTypeNames = new Set(usedComponentImports);
   const headlessModules = /* @__PURE__ */ new Set();
   for (const headless of jayFile.headlessImports) {
-    usedHeadlessTypeNames.add(headless.rootType.name);
+    if (!headless.structural) {
+      usedHeadlessTypeNames.add(headless.rootType.name);
+    }
     for (const link of headless.contractLinks) {
       headlessModules.add(link.module);
       for (const name of link.names) {
-        if (name.name.endsWith("Refs") || isEnumType(name.type)) {
+        if (isEnumType(name.type)) {
+          usedHeadlessTypeNames.add(name.name);
+        } else if (!headless.structural && name.name.endsWith("Refs")) {
           usedHeadlessTypeNames.add(name.name);
         }
       }
@@ -22584,7 +22714,7 @@ function generateElementBridgeFile(jayFile) {
 }
 function generateElementHydrateFile(jayFile, importerMode) {
   const types2 = generateTypes(jayFile.types);
-  const headlessImports = jayFile.headlessImports?.filter((h) => !h.key && !h.structural) ?? [];
+  const headlessImports = jayFile.headlessImports?.filter((h) => !h.key) ?? [];
   const headlessContractNames = new Set(headlessImports.map((h) => h.contractName));
   assignCoordinates(jayFile.body, { headlessContractNames });
   const {
@@ -22605,7 +22735,7 @@ function generateElementHydrateFile(jayFile, importerMode) {
     jayFile.headLinks
   );
   const phaseTypes = generatePhaseSpecificTypes(jayFile);
-  const renderedHydrate = renderHydrate(
+  const { fragment: renderedHydrate } = renderHydrate(
     jayFile.types,
     jayFile.body,
     jayFile.imports,
@@ -22615,16 +22745,43 @@ function generateElementHydrateFile(jayFile, importerMode) {
     jayFile.headlessImports,
     jayFile.contract
   );
+  const allRenderedRefs = renderedRefs;
   let finalRenderedElement = renderedElement;
   if (jayFile.contract || jayFile.hasInlineData) {
     finalRenderedElement = expandContractType(finalRenderedElement, jayFile.baseElementName);
   }
   const typeOnlyImports = renderedImplementation.imports.minus(renderedHydrate.imports).minus(Import.element).minus(Import.dynamicText).minus(Import.dynamicElement).minus(Import.conditional).minus(Import.forEach);
   const hydrateImports = typeOnlyImports.plus(Import.jayElement).plus(renderedHydrate.imports);
+  const structuralHeadless = (jayFile.headlessImports ?? []).filter((h) => h.structural);
+  let filteredHydrateImports = jayFile.imports;
+  if (structuralHeadless.length > 0) {
+    const structuralModules = new Set(
+      structuralHeadless.flatMap((h) => h.contractLinks.map((l) => l.module))
+    );
+    const dropNames = /* @__PURE__ */ new Set();
+    for (const headless of structuralHeadless) {
+      dropNames.add(headless.rootType.name);
+    }
+    for (const headless of (jayFile.headlessImports ?? []).filter((h) => !h.structural)) {
+      dropNames.delete(headless.rootType.name);
+      for (const link of headless.contractLinks)
+        for (const name of link.names) dropNames.delete(name.name);
+    }
+    filteredHydrateImports = jayFile.imports.map((importLink) => {
+      if (!structuralModules.has(importLink.module)) return importLink;
+      const names = importLink.names.filter((n) => !dropNames.has(n.as || n.name));
+      return names.length === 0 ? null : { ...importLink, names };
+    }).filter((imp) => imp !== null);
+  }
   const renderedFile = [
-    renderImports$1(hydrateImports, ImportsFor.implementation, jayFile.imports, importerMode),
+    renderImports$1(
+      hydrateImports,
+      ImportsFor.implementation,
+      filteredHydrateImports,
+      importerMode
+    ),
     types2,
-    renderedRefs,
+    allRenderedRefs,
     phaseTypes,
     finalRenderedElement,
     renderedHydrate.rendered
@@ -22863,7 +23020,10 @@ function renderAttributes(element, { variables }) {
       );
     else if (attrName === "class") {
       let classExpression = parseReactClassExpression(attributes2[attrName], variables);
-      renderedAttributes.push(classExpression.map((_) => `className=${_}`));
+      let classFragment = classExpression.map((_) => `className=${_}`);
+      if (classExpression.rendered.includes("cx("))
+        classFragment = classFragment.plusImport(Imports.for(Import.classNamesReact));
+      renderedAttributes.push(classFragment);
     } else if (booleanAttributes.has(attrCanonical)) {
       const attrValue = attributes2[attrName];
       if (attrValue === "") {
@@ -23198,6 +23358,24 @@ function generateElementFileReactTarget(jayFile, importerMode) {
   ].filter((_) => _ !== null && _ !== "").join("\n\n");
   return new WithValidations(renderedFile, renderedImplementation.validations);
 }
+function buildStructuralCoercions(rawVar, tags) {
+  const coercions = [];
+  for (const tag of tags) {
+    const dt = tag.dataType;
+    if (!dt) continue;
+    const field = `${rawVar}.${tag.tag}`;
+    if (isEnumType(dt)) {
+      coercions.push(
+        `${tag.tag}: typeof (${dt.name} as any)[${field}] === 'number' ? (${dt.name} as any)[${field}] : Number(${field})`
+      );
+    } else if (dt.name === "number") {
+      coercions.push(`${tag.tag}: Number(${field})`);
+    } else if (dt.name === "boolean") {
+      coercions.push(`${tag.tag}: ${field} === true || ${field} === 'true'`);
+    }
+  }
+  return coercions;
+}
 function w(indent, code, imports = Imports.none()) {
   return new RenderFragment(`${indent.firstLine}w(${code});`, imports);
 }
@@ -23314,7 +23492,12 @@ function renderServerHeadlessInstance(element, context, contractName) {
     instanceKeyExpr = `'${instanceCoord}'`;
   }
   const ifCondition = element.attributes.if;
-  const componentVariables = new Variables(headlessImport.rootType, void 0, 0, varName);
+  const componentVariables = new Variables(
+    headlessImport.rootType,
+    context.variables,
+    0,
+    varName
+  ).asLexical();
   const childNodes = filterContentNodes(element.childNodes);
   if (childNodes.length === 0) {
     return new RenderFragment("", Imports.none(), [
@@ -23346,8 +23529,15 @@ function renderServerHeadlessInstance(element, context, contractName) {
     })
   );
   const guardIndent = ifCondition ? new Indent(indent.curr + "    ") : indent;
+  const coercions = headlessImport.structural ? buildStructuralCoercions(`${varName}_raw`, headlessImport.contract?.tags ?? []) : [];
+  const extractionLines = coercions.length > 0 ? [
+    `${guardIndent.firstLine}const ${varName}_raw = (vs as any).__headlessInstances?.[${instanceKeyExpr}] as any;`,
+    `${guardIndent.firstLine}const ${varName} = ${varName}_raw ? ({ ...${varName}_raw, ${coercions.join(", ")} } as ${viewStateTypeName}) : undefined;`
+  ] : [
+    `${guardIndent.firstLine}const ${varName} = (vs as any).__headlessInstances?.[${instanceKeyExpr}] as ${viewStateTypeName} | undefined;`
+  ];
   const guardedBlock = [
-    `${guardIndent.firstLine}const ${varName} = (vs as any).__headlessInstances?.[${instanceKeyExpr}] as ${viewStateTypeName} | undefined;`,
+    ...extractionLines,
     `${guardIndent.firstLine}if (${varName}) {`,
     renderedChildren.rendered,
     `${guardIndent.firstLine}}`
@@ -23419,12 +23609,9 @@ function renderServerAttributes(element, context) {
       const classExpr = parseClassExpression(attrValue, variables);
       if (classExpr.imports.has(Import.dynamicAttribute)) {
         const rawExpr = classExpr.rendered.replace(/^da\(\w+ => /, "").replace(/\)$/, "");
+        const classImports = classExpr.imports.has(Import.classNames) ? Imports.for(Import.escapeAttr, Import.classNamesServer) : Imports.for(Import.escapeAttr);
         parts.push(
-          w(
-            indent,
-            `' class="' + escapeAttr(String(${rawExpr})) + '"'`,
-            Imports.for(Import.escapeAttr)
-          )
+          w(indent, `' class="' + escapeAttr(String(${rawExpr})) + '"'`, classImports)
         );
       } else {
         const escaped = escapeForJsString(attrValue);
@@ -23614,10 +23801,11 @@ function renderServerAttributesAsString(element, context) {
       const classExpr = parseClassExpression(attrValue, variables);
       if (classExpr.imports.has(Import.dynamicAttribute)) {
         const rawExpr = classExpr.rendered.replace(/^da\(\w+ => /, "").replace(/\)$/, "");
+        const classImports = classExpr.imports.has(Import.classNames) ? Imports.for(Import.escapeAttr, Import.classNamesServer) : Imports.for(Import.escapeAttr);
         parts.push(
           new RenderFragment(
             `' class="' + escapeAttr(String(${rawExpr})) + '"'`,
-            Imports.for(Import.escapeAttr)
+            classImports
           )
         );
       } else {
@@ -23807,7 +23995,14 @@ function renderServerAsyncGroup(group, context) {
   const templateValidations = [];
   if (group.resolvedElement) {
     const promiseResolvedType = asyncAccessor.resolvedType.itemType;
-    const resolvedVariables = new Variables(promiseResolvedType, variables, 1);
+    const resolvedVariables = new Variables(
+      promiseResolvedType,
+      variables,
+      1,
+      void 0,
+      {},
+      variables.lexicallyInScope
+    );
     const resolvedContext = {
       ...context,
       variables: resolvedVariables
@@ -23824,7 +24019,14 @@ function renderServerAsyncGroup(group, context) {
     templateValidations.push(...resolvedString.validations);
   }
   if (group.rejectedElement) {
-    const rejectedVariables = new Variables(JayErrorType, variables, 1);
+    const rejectedVariables = new Variables(
+      JayErrorType,
+      variables,
+      1,
+      void 0,
+      {},
+      variables.lexicallyInScope
+    );
     const rejectedContext = {
       ...context,
       variables: rejectedVariables
@@ -23884,7 +24086,7 @@ function hasMixedContentDynamicTextInteractive(childNodes, interactivePaths) {
 }
 function generateServerElementFile(jayFile, _options) {
   const types2 = generateTypes(jayFile.types);
-  const variables = new Variables(jayFile.types);
+  const variables = new Variables(jayFile.types).asLexical();
   const rootElement = ensureSingleChildElement(jayFile.body);
   if (!rootElement.val) {
     return new WithValidations("", rootElement.validations);
@@ -23903,14 +24105,29 @@ function generateServerElementFile(jayFile, _options) {
     interactivePaths: buildInteractivePaths(jayFile.contract),
     parentHasInteractiveChildren: false
   };
-  const rendered = renderServerElementContent(rootElement.val, context, {
-    isRoot: true
-  });
+  const rootComponentMatch = getComponentName(
+    rootElement.val.rawTagName,
+    /* @__PURE__ */ new Set(),
+    // No headful component imports in server-element target
+    headlessContractNames
+  );
+  let rendered;
+  try {
+    rendered = rootComponentMatch !== null && rootComponentMatch.kind === "headless-instance" ? renderServerElement(rootElement.val, context) : renderServerElementContent(rootElement.val, context, {
+      isRoot: true
+    });
+  } catch (e2) {
+    if (e2 instanceof UnsupportedServerParentBindingError) {
+      return new WithValidations("", [UNSUPPORTED_TARGET_PARENT_MESSAGE]);
+    }
+    throw e2;
+  }
   const viewStateType = jayFile.types.name;
   const hasAsync = rendered.rendered.includes("onAsync(");
   const importParts = [];
   if (rendered.imports.has(Import.escapeHtml)) importParts.push("escapeHtml");
   if (rendered.imports.has(Import.escapeAttr)) importParts.push("escapeAttr");
+  if (rendered.imports.has(Import.classNamesServer)) importParts.push("classNames as cx");
   importParts.push("type ServerRenderContext");
   const importStatement = `import {${importParts.join(", ")}} from "@jay-framework/ssr-runtime";`;
   const usedTypeNames = /* @__PURE__ */ new Set();
@@ -23920,17 +24137,35 @@ function generateServerElementFile(jayFile, _options) {
     for (const link of headless.contractLinks) {
       headlessModules.add(link.module);
       for (const name of link.names) {
-        if (!name.name.endsWith("Refs")) {
+        if (isEnumType(name.type)) {
+          usedTypeNames.add(name.name);
+        } else if (!name.name.endsWith("Refs")) {
           usedTypeNames.add(name.name);
         }
       }
     }
   }
-  const contractImports = jayFile.imports.filter((imp) => headlessModules.has(imp.module)).map((imp) => {
-    const typeNames = imp.names.filter((n) => usedTypeNames.has(n.as || n.name)).map((n) => n.as ? `${n.name} as ${n.as}` : n.name);
-    if (typeNames.length === 0) return null;
-    return `import {${typeNames.join(", ")}} from "${imp.module}";`;
-  }).filter((_) => _ !== null);
+  const typeNamesByModule = /* @__PURE__ */ new Map();
+  const typeNamesSeen = /* @__PURE__ */ new Map();
+  for (const imp of jayFile.imports) {
+    if (!headlessModules.has(imp.module)) continue;
+    let names = typeNamesByModule.get(imp.module);
+    let seen = typeNamesSeen.get(imp.module);
+    if (!names) {
+      names = [];
+      seen = /* @__PURE__ */ new Set();
+      typeNamesByModule.set(imp.module, names);
+      typeNamesSeen.set(imp.module, seen);
+    }
+    for (const n of imp.names) {
+      if (!usedTypeNames.has(n.as || n.name)) continue;
+      const rendered2 = n.as ? `${n.name} as ${n.as}` : n.name;
+      if (seen.has(rendered2)) continue;
+      seen.add(rendered2);
+      names.push(rendered2);
+    }
+  }
+  const contractImports = [...typeNamesByModule.entries()].filter(([, typeNames]) => typeNames.length > 0).map(([module, typeNames]) => `import {${typeNames.join(", ")}} from "${module}";`);
   const ctxDestructure = hasAsync ? "const { write: w, onAsync } = ctx;" : "const { write: w } = ctx;";
   const renderedFile = [
     importStatement,
@@ -30653,12 +30888,13 @@ const JAY_IMPORT_RESOLVER = {
     return analyzeExportedTypes(fullPath, options);
   },
   loadContract(fullPath) {
-    const content = fs.readFileSync(fullPath).toString();
+    const content = fs$1.readFileSync(fullPath).toString();
     return parseContract(content, fullPath);
   },
   resolveLink(importingModuleDir, link) {
     if (link?.[0] === ".") return path.resolve(importingModuleDir, link);
-    else return require$1.resolve(link, { paths: require$1.resolve.paths(importingModuleDir) });
+    if (link?.[0] === "/") return link;
+    return require$1.resolve(link, { paths: require$1.resolve.paths(importingModuleDir) });
   },
   resolvePluginComponent(pluginName, contractName, projectRoot) {
     return resolvePluginComponent(projectRoot, pluginName, contractName);
@@ -30667,7 +30903,7 @@ const JAY_IMPORT_RESOLVER = {
     const resolution = resolvePluginComponent(projectRoot, pluginName, contractName);
     if (resolution.val && resolution.val.contractPath) {
       const contractPath = resolution.val.contractPath;
-      const content = fs.readFileSync(contractPath).toString();
+      const content = fs$1.readFileSync(contractPath).toString();
       const contractResult = parseContract(content, contractPath);
       return contractResult.map((contract) => ({ contract, contractPath }));
     }
@@ -30675,14 +30911,14 @@ const JAY_IMPORT_RESOLVER = {
     const pluginDir = pluginName.startsWith("@") ? pluginName.split("/").pop() || pluginName : pluginName;
     const contractFileName = contractName.replace(/\//g, "-") + ".jay-contract";
     const materializedPath = path.join(materializedDir, pluginDir, contractFileName);
-    if (fs.existsSync(materializedPath)) {
-      const content = fs.readFileSync(materializedPath).toString();
+    if (fs$1.existsSync(materializedPath)) {
+      const content = fs$1.readFileSync(materializedPath).toString();
       const contractResult = parseContract(content, materializedPath);
       let metadata;
       const indexPath = path.join(projectRoot, "agent-kit", "plugins-index.yaml");
-      if (fs.existsSync(indexPath)) {
+      if (fs$1.existsSync(indexPath)) {
         try {
-          const indexContent = fs.readFileSync(indexPath, "utf-8");
+          const indexContent = fs$1.readFileSync(indexPath, "utf-8");
           const index2 = YAML.parse(indexContent);
           const plugin = index2.plugins?.find(
             (p) => p.name === pluginName || p.name === pluginDir
@@ -30711,13 +30947,13 @@ const JAY_IMPORT_RESOLVER = {
     const resolvedPath = src.startsWith(".") ? path.resolve(importingModuleDir, src) : src;
     const jayHtmlPath = resolvedPath + ".jay-html";
     try {
-      const content = fs.readFileSync(jayHtmlPath, "utf-8");
+      const content = fs$1.readFileSync(jayHtmlPath, "utf-8");
       return { content, componentDir: path.dirname(jayHtmlPath), filePath: jayHtmlPath };
     } catch {
     }
     const dirJayHtmlPath = path.resolve(resolvedPath, path.basename(resolvedPath)) + ".jay-html";
     try {
-      const content = fs.readFileSync(dirJayHtmlPath, "utf-8");
+      const content = fs$1.readFileSync(dirJayHtmlPath, "utf-8");
       return {
         content,
         componentDir: path.dirname(dirJayHtmlPath),
@@ -30907,6 +31143,10 @@ function resolveRelativePaths(root, sourceDir) {
     if (src && isRelativePath(src)) {
       script.setAttribute("src", path.resolve(sourceDir, src));
     }
+    const contract = script.getAttribute("contract");
+    if (contract && isRelativePath(contract)) {
+      script.setAttribute("contract", path.resolve(sourceDir, contract));
+    }
   }
   const links = root.querySelectorAll('link[rel="stylesheet"]');
   for (const link of links) {
@@ -31014,7 +31254,7 @@ function discoverHeadlessInstances(preRenderedJayHtml) {
   const instances = [];
   const forEachInstances = [];
   const coordinateCounters = /* @__PURE__ */ new Map();
-  function walk(element, insidePreservedForEach, forEachContexts) {
+  function walk(element, insidePreservedForEach, forEachContexts, parentCoordinate) {
     const tagName = element.tagName?.toLowerCase();
     const forEachAttr = element.getAttribute("forEach");
     const hasForEach = forEachAttr != null;
@@ -31028,6 +31268,7 @@ function discoverHeadlessInstances(preRenderedJayHtml) {
           props[toCamelCase(key)] = value;
         }
       }
+      let childParentCoordinate = parentCoordinate;
       if (!insidePreservedForEach) {
         let ref = element.getAttribute("ref");
         if (!ref) {
@@ -31043,8 +31284,10 @@ function discoverHeadlessInstances(preRenderedJayHtml) {
         instances.push({
           contractName,
           props,
-          coordinate
+          coordinate,
+          parentCoordinate
         });
+        childParentCoordinate = coordinate;
       } else {
         const innerForEach = forEachContexts[forEachContexts.length - 1];
         if (innerForEach) {
@@ -31066,7 +31309,12 @@ function discoverHeadlessInstances(preRenderedJayHtml) {
       }
       for (const child of element.childNodes) {
         if (child.nodeType === NodeType.ELEMENT_NODE) {
-          walk(child, insidePreservedForEach, forEachContexts);
+          walk(
+            child,
+            insidePreservedForEach,
+            forEachContexts,
+            childParentCoordinate
+          );
         }
       }
       return;
@@ -31077,14 +31325,15 @@ function discoverHeadlessInstances(preRenderedJayHtml) {
         walk(
           child,
           insidePreservedForEach || hasForEach,
-          updatedForEachContexts
+          updatedForEachContexts,
+          parentCoordinate
         );
       }
     }
   }
   const body = root.querySelector("body");
   if (body) {
-    walk(body, false, []);
+    walk(body, false, [], void 0);
   }
   return { instances, forEachInstances, preRenderedJayHtml: root.toString() };
 }
@@ -31215,7 +31464,6 @@ export {
   getLinkedContractDir,
   hasSlowPhaseProperties,
   htmlElementTagNameMap,
-  injectHeadfullFSTemplates,
   isTagInPhase,
   loadLinkedContract,
   parseAction,