From 3cc1d2ad035a8c6b799e5768751ad65ce7758a79 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20R=C3=B8ed?= <johanroed@gmail.com>
Date: Fri, 8 May 2026 09:00:55 +0200
Subject: [PATCH 01/20] Suppress element-permitted-content FPs from
 unresolvable wrappers (heuristic + classic-by-name)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two fixes that target the same FP class — `element-permitted-content`
firing on PascalCase components that transparent-blank, where the
wrapper is presumed to render the structurally-correct parent at
runtime via a yield chain we can't statically resolve.

1. Heuristic suppression in detectStructuralYieldRules:
   When a non-native wrapper contains content-restricted structural
   children (`<option>`, `<th>`, `<li>`, `<optgroup>`, etc.), add
   `element-permitted-content` to disableForRules for the Source.
   Catches HDS-style multi-level yield chains
   (`<HdsFormSelectField as |F|><F.Options>...</F.Options>`) where
   precise resolution would require ~250+ lines of cross-file yield-
   chain analysis. Same per-Source-suppression trade-off as Thread B's
   wcag/h32 fix.

2. Classic-Ember by-name resolver (`lib/classic-resolver.ts`):
   For `.hbs` consumers (no JS imports, no Glint), walk PascalCase
   tags, kebab-case them, look up in node_modules under the canonical
   classic-Ember component template paths. Builds a componentTagMap
   for the .hbs path that previously had none. Catches the
   ember-website `<EsCard>` pattern: `EsCard` → kebab `es-card` →
   ember-styleguide's `addon/components/es-card.hbs` (root `<li>`).
   Also handles pnpm-style symlinks (treats them as directories).

Together: clears HDS's ~107 `<option>`-under-`<div>` family, ember-
website's `<EsCard>`-class entries, plus analogous patterns across
discourse and others.

Two regression fixtures + tests:

- `multi-level-yield-chain-options.gts` (heuristic case): unresolvable
  wrapper containing `<option>` children; asserts no
  element-permitted-content fires.
- `classic-resolver-no-import.hbs` (by-name case): `.hbs` consumer
  using a fake `<ClassicCard>` from a fixture node_modules; asserts
  the wrapper resolves to its `<li>` root.

161/161 pass. Verified on real ember-website browser-support.hbs:
18 element-permitted-content findings → 0.
---
 blank.ts                                      |  89 ++++++++-
 examples/multi-level-yield-chain-options.gts  |  55 ++++++
 lib/classic-resolver.ts                       | 175 ++++++++++++++++++
 .../classic-resolver-no-import.hbs            |  22 +++
 .../addon/components/classic-card.hbs         |   1 +
 .../classic-card-addon/package.json           |   9 +
 test/integration.test.ts                      |  70 +++++++
 transform.ts                                  |  25 ++-
 8 files changed, 444 insertions(+), 2 deletions(-)
 create mode 100644 examples/multi-level-yield-chain-options.gts
 create mode 100644 lib/classic-resolver.ts
 create mode 100644 test/glint-fixtures/classic-resolver-no-import.hbs
 create mode 100644 test/glint-fixtures/node_modules/classic-card-addon/addon/components/classic-card.hbs
 create mode 100644 test/glint-fixtures/node_modules/classic-card-addon/package.json

diff --git a/blank.ts b/blank.ts
index b4d63a4..dcf9248 100644
--- a/blank.ts
+++ b/blank.ts
@@ -1391,7 +1391,7 @@ function blankTemplateContent(
 // output, and add the rule to `disableForRules` so the transformer can
 // inject a one-shot disable directive into this Source.
 //
-// Two FP classes covered today:
+// Three FP classes covered today:
 //
 //   1. Yield-bearing `<form>`/`<fieldset>` that lacks a statically-
 //      detectable submit/legend (the suppression target rule fires
@@ -1408,6 +1408,14 @@ function blankTemplateContent(
 //      user). wcag/h32 is suppressed regardless of submit-button or
 //      yield presence.
 //
+//   3. Unresolvable PascalCase / dotted wrapper containing content-
+//      restricted structural children (`<option>`/`<th>`/`<li>`/...).
+//      At runtime such wrappers typically render the structurally-
+//      correct parent (`<select>`/`<thead>`/`<ul>`) via a yield chain
+//      we can't trace statically. Suppress `element-permitted-content`
+//      so the FP doesn't surface. Same per-Source-suppression
+//      trade-off as cases 1 and 2.
+//
 // Branch-aware. `{{#if}}/{{else}}` arms are NOT both walked — that
 // would let one arm's static submit hide the other arm's yield-only
 // FP. Instead we honor `branchSelections` (the same per-pass selection
@@ -1471,6 +1479,25 @@ function detectStructuralYieldRules(
           elementYieldsAndLacksLegend(stmt, branchSelections)
         ) {
           out.push('wcag/h71');
+        } else if (
+          !isNativeTag(stmt.tag) &&
+          containsContentRestrictedStructuralChild(stmt, glintComponentTagMap)
+        ) {
+          // Unresolvable PascalCase / dotted wrapper containing
+          // content-restricted structural children (`<option>`, `<th>`,
+          // `<li>`, `<optgroup>`, `<tr>`). At runtime such wrappers
+          // typically render the structurally-correct parent
+          // (`<select>`, `<thead>`, `<ul>`, …) via a yield chain, so
+          // the static blanker's transparent-blanking puts the
+          // structural children under whatever native ancestor
+          // happens to be in source — almost always invalid, almost
+          // always FP-firing `element-permitted-content`.
+          //
+          // We can't precisely resolve the runtime parent without
+          // multi-level cross-file yield-chain analysis (deferred).
+          // Suppress the rule for the Source instead — same per-Source
+          // suppression trade-off as the form/fieldset cases above.
+          out.push('element-permitted-content');
         }
         walk(stmt.children);
       }
@@ -1530,6 +1557,66 @@ function selectBranch(
 // anything at runtime, so we don't trust them as a suppression signal.
 const INPUT_DRIVEN_FORM_EVENTS: ReadonlySet<string> = new Set(['input', 'change']);
 
+// HTML elements with restrictive content models — they only accept
+// specific native parents. When these appear as children of an
+// unresolvable component invocation, the wrapper is presumed to render
+// the structurally-correct parent at runtime via yield chain. Listing
+// kept narrow on purpose: every entry is a tag whose presence inside a
+// PascalCase wrapper is ambiguous evidence of "the wrapper renders my
+// only valid parent". Adding more entries widens suppression.
+const CONTENT_RESTRICTED_STRUCTURAL_CHILDREN: ReadonlySet<string> = new Set([
+  'option',
+  'optgroup',
+  'th',
+  'td',
+  'tr',
+  'thead',
+  'tbody',
+  'tfoot',
+  'caption',
+  'colgroup',
+  'col',
+  'li',
+  'legend',
+  'summary',
+]);
+
+// True when the element node has at least one direct child that is a
+// content-restricted structural element (`<option>`, `<th>`, `<li>`,
+// etc.). Mustaches and BlockStatements descend through; we only check
+// for native ElementNode children. Doesn't recurse into other
+// component invocations — those have their own rule check.
+//
+// Resolved components are excluded: if Glint already maps the wrapper
+// to a specific native tag, we trust that resolution and let
+// `element-permitted-content` fire normally. Only fully-unresolved
+// wrappers (componentTagMap miss) trigger suppression.
+function containsContentRestrictedStructuralChild(
+  node: AST.ElementNode,
+  glintComponentTagMap: ReadonlyMap<string, string> | null | undefined,
+): boolean {
+  // If Glint has resolved this wrapper to a native tag, no heuristic
+  // needed — the precise resolution wins and the rule fires (or
+  // doesn't) on the actual parent.
+  if (glintComponentTagMap && node.loc.start) {
+    const key = `${node.loc.start.line}:${node.loc.start.column}`;
+    const resolved = glintComponentTagMap.get(key);
+    if (resolved && resolved !== 'transparent') return false;
+  }
+  function check(stmts: ReadonlyArray<AST.Statement>): boolean {
+    for (const stmt of stmts) {
+      if (stmt.type === 'ElementNode') {
+        if (CONTENT_RESTRICTED_STRUCTURAL_CHILDREN.has(stmt.tag)) return true;
+      } else if (stmt.type === 'BlockStatement') {
+        if (check(stmt.program.body)) return true;
+        if (stmt.inverse && check(stmt.inverse.body)) return true;
+      }
+    }
+    return false;
+  }
+  return check(node.children);
+}
+
 function formHasInputModifier(form: AST.ElementNode): boolean {
   for (const modifier of form.modifiers ?? []) {
     if (modifier.path.type !== 'PathExpression') continue;
diff --git a/examples/multi-level-yield-chain-options.gts b/examples/multi-level-yield-chain-options.gts
new file mode 100644
index 0000000..b0478fc
--- /dev/null
+++ b/examples/multi-level-yield-chain-options.gts
@@ -0,0 +1,55 @@
+// Mirrors the unresolvable-yield-chain pattern in HDS's
+// `<HdsFormSelectField as |F|><F.Options>...` — a curried sub-
+// component (`F.Options`) yielded through multiple levels where the
+// final native parent (`<select>`) lives in an inner component's
+// template.
+//
+// To make the FP actually fire here, the outer wrapper has bare
+// `Element: HTMLElement` (not a specific tag) so PR #12 resolves it
+// as 'transparent'. Then everything floats out: <option> ends up
+// directly under <div>, and `element-permitted-content` fires.
+//
+// Resolving this precisely would require recursive cross-file yield-
+// chain analysis (~250+ lines, deferred). The pragmatic fix is
+// heuristic suppression: when an unresolvable component invocation
+// contains structural children (`<option>`/`<th>`/`<li>`) that would
+// be invalid under the actual outer parent, the plugin presumes the
+// wrapper is structurally-rendering and suppresses
+// `element-permitted-content` for the Source. Same per-Source
+// suppression trade-off as Thread B's wcag/h32 fix.
+import Component from '@glimmer/component';
+
+interface PassThroughSig {
+  Element: HTMLElement;
+  Args: Record<string, never>;
+  Blocks: { default: [] };
+}
+class PassThrough extends Component<PassThroughSig> {
+  <template>
+    {{yield}}
+  </template>
+}
+
+interface FormSelectFieldSig {
+  Args: Record<string, never>;
+  Blocks: { default: [{ Options?: typeof PassThrough }] };
+  Element: HTMLElement;
+}
+class FormSelectField extends Component<FormSelectFieldSig> {
+  <template>
+    {{yield (hash Options=PassThrough)}}
+  </template>
+}
+
+<template>
+  <div>
+    <FormSelectField as |F|>
+      <F.Options>
+        <option value='one'>One</option>
+        <option value='two'>Two</option>
+      </F.Options>
+    </FormSelectField>
+  </div>
+</template>
+
+const hash = <T,>(o: T): T => o;
diff --git a/lib/classic-resolver.ts b/lib/classic-resolver.ts
new file mode 100644
index 0000000..9873f4b
--- /dev/null
+++ b/lib/classic-resolver.ts
@@ -0,0 +1,175 @@
+// Classic Ember component resolver — by-name lookup in node_modules.
+//
+// Classic `.hbs` templates resolve PascalCase components through Ember's
+// container resolver: `<EsCard>` corresponds to addon-installed
+// `es-card.hbs` somewhere under `node_modules/<addon>/{addon|app}/`. No
+// JS `import` is involved (unlike `.gts` which goes through Glint).
+//
+// PR #19's `resolveAddonHbsTemplate` walks JS imports — that path is
+// dead in `.hbs` files. This module fills the gap: walk the template
+// AST, find PascalCase tags, look up by kebab-case name in node_modules
+// addons, parse the addon's component template, return its splatted-
+// root tag.
+//
+// Cache:
+//   - In-memory per-(node_modules-root, kebab-name) → ComponentAttrs.
+//     Process-lifetime; cleared via `_clearClassicResolverCache` (tests).
+//   - Negatives are NOT cached: an addon installed mid-session would
+//     otherwise stay invisible until process restart. Negative path is
+//     cheap (regex + a handful of existsSync up to filesystem root).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { preprocess, traverse } from '@glimmer/syntax';
+import type { AST } from '@glimmer/syntax';
+
+import type { ComponentAttrs } from './builtin-components.js';
+import { extractSplattedRootFromTemplate } from './component-attrs.js';
+
+const cache = new Map<string, ComponentAttrs>();
+
+// Components our blank-step handles via the builtin map (not by-name
+// resolution). Skip these — they'd shadow the builtin substitution.
+const BUILTIN_COMPONENT_NAMES: ReadonlySet<string> = new Set([
+  'Input',
+  'Textarea',
+  'LinkTo',
+]);
+
+// PascalCase → kebab-case. `EsCard` → `es-card`, `TabButton` → `tab-button`,
+// `XMLHttpRequest` → `xml-http-request` (acronyms collapse correctly).
+function pascalCaseToKebab(name: string): string {
+  return name
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .toLowerCase();
+}
+
+// Probe an addon directory for a component template by kebab-name.
+// Returns the parsed splatted-root or null. Tries the three canonical
+// classic-Ember component template paths.
+function tryProbeAddon(addonRoot: string, kebabName: string): ComponentAttrs | null {
+  for (const sub of [
+    `addon/templates/components/${kebabName}.hbs`,
+    `addon/components/${kebabName}.hbs`,
+    `app/components/${kebabName}.hbs`,
+  ]) {
+    const hbsPath = path.join(addonRoot, sub);
+    if (!fs.existsSync(hbsPath)) continue;
+    let contents: string;
+    try {
+      contents = fs.readFileSync(hbsPath, 'utf8');
+    } catch {
+      continue;
+    }
+    return extractSplattedRootFromTemplate(contents);
+  }
+  return null;
+}
+
+// Look up `kebabName` in every addon under each `node_modules/` walked
+// up from the consumer file. Returns the first match. Native-tag-only
+// guard mirrors PR #19's `resolveAddonHbsTemplate` behavior.
+function findClassicComponent(consumerFile: string, kebabName: string): ComponentAttrs | null {
+  const cacheKey = `${path.dirname(consumerFile)}\0${kebabName}`;
+  const cached = cache.get(cacheKey);
+  if (cached !== undefined) return cached;
+  let dir = path.dirname(consumerFile);
+  for (;;) {
+    const nodeModules = path.join(dir, 'node_modules');
+    if (fs.existsSync(nodeModules)) {
+      let entries: fs.Dirent[];
+      try {
+        entries = fs.readdirSync(nodeModules, { withFileTypes: true });
+      } catch {
+        entries = [];
+      }
+      for (const entry of entries) {
+        // pnpm uses symlinks for packages — `isDirectory()` returns
+        // false on a symlink, so accept symlinks too. The lookup below
+        // uses `fs.existsSync` which transparently follows links.
+        if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+        if (entry.name.startsWith('.')) continue;
+        if (entry.name.startsWith('@')) {
+          // Scoped package — recurse one level.
+          const scopeRoot = path.join(nodeModules, entry.name);
+          let scopedEntries: fs.Dirent[];
+          try {
+            scopedEntries = fs.readdirSync(scopeRoot, { withFileTypes: true });
+          } catch {
+            continue;
+          }
+          for (const scoped of scopedEntries) {
+            if (!scoped.isDirectory() && !scoped.isSymbolicLink()) continue;
+            const result = tryProbeAddon(path.join(scopeRoot, scoped.name), kebabName);
+            if (result && isLowercaseHtmlTag(result.tag)) {
+              cache.set(cacheKey, result);
+              return result;
+            }
+          }
+          continue;
+        }
+        const result = tryProbeAddon(path.join(nodeModules, entry.name), kebabName);
+        if (result && isLowercaseHtmlTag(result.tag)) {
+          cache.set(cacheKey, result);
+          return result;
+        }
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+// Lightweight native-tag check that doesn't pull `isNativeTag` from
+// blank.ts (avoids circular import — blank.ts → classic-resolver.ts
+// chain). A component template's root being a lowercase ASCII letter
+// followed by name-chars is a sufficient proxy for "native HTML tag";
+// the actual blanker does the strict check via NATIVE_TAGS.
+function isLowercaseHtmlTag(tag: string): boolean {
+  return /^[a-z][a-z0-9-]*$/.test(tag);
+}
+
+// Walk a template AST, find every PascalCase / dotted invocation, and
+// build a `componentTagMap` + `componentAttrMap` keyed by `line:col`
+// (matching what the Glint resolver produces). Both maps are returned;
+// callers pass them to `blankTemplateContent`.
+//
+// Skips:
+//   - Builtin components (`<Input>`, `<Textarea>`, `<LinkTo>`) — handled
+//     by the blanker's builtin map.
+//   - Dotted invocations (`<This.Foo>`, `<F.Options>`) — not classic-
+//     resolved by name.
+//   - Named-block syntax (`<:slot>`).
+export function buildClassicComponentTagMap(
+  consumerFile: string,
+  ast: AST.Template,
+): {
+  componentTagMap: Map<string, string>;
+  componentAttrMap: Map<string, ComponentAttrs>;
+} {
+  const componentTagMap = new Map<string, string>();
+  const componentAttrMap = new Map<string, ComponentAttrs>();
+  traverse(ast, {
+    ElementNode(node) {
+      const tag = node.tag;
+      if (!/^[A-Z][A-Za-z0-9]*$/.test(tag)) return;
+      if (BUILTIN_COMPONENT_NAMES.has(tag)) return;
+      if (!node.loc.start) return;
+      const kebab = pascalCaseToKebab(tag);
+      const result = findClassicComponent(consumerFile, kebab);
+      if (!result) return;
+      const key = `${node.loc.start.line}:${node.loc.start.column}`;
+      componentTagMap.set(key, result.tag);
+      componentAttrMap.set(key, result);
+    },
+  });
+  return { componentTagMap, componentAttrMap };
+}
+
+// Test-only: clear the in-memory by-name resolver cache.
+export function _clearClassicResolverCache(): void {
+  cache.clear();
+}
diff --git a/test/glint-fixtures/classic-resolver-no-import.hbs b/test/glint-fixtures/classic-resolver-no-import.hbs
new file mode 100644
index 0000000..bacb403
--- /dev/null
+++ b/test/glint-fixtures/classic-resolver-no-import.hbs
@@ -0,0 +1,22 @@
+{{!--
+  Classic-Ember `.hbs` consumer using <ClassicCard> with NO JS import.
+  Mirrors ember-website's `<EsCard>` pattern: PascalCase tag resolved
+  at runtime via Ember's container resolver, looking up
+  `classic-card-addon/components/classic-card`.
+
+  At runtime the component renders `<li class="classic-card"
+  ...attributes>{{yield}}</li>`. So inside `<ul>`, the resulting DOM is
+  valid (`<li>` directly under `<ul>`).
+
+  Without the by-name lookup, our plugin transparent-blanks
+  <ClassicCard>, the inner content (potentially structural like
+  another `<ul>` or `<div>`) floats directly into the outer `<ul>`,
+  and `element-permitted-content` FP-fires.
+--}}
+<ul>
+  <ClassicCard>
+    <ul>
+      <li>nested item</li>
+    </ul>
+  </ClassicCard>
+</ul>
diff --git a/test/glint-fixtures/node_modules/classic-card-addon/addon/components/classic-card.hbs b/test/glint-fixtures/node_modules/classic-card-addon/addon/components/classic-card.hbs
new file mode 100644
index 0000000..24c8e83
--- /dev/null
+++ b/test/glint-fixtures/node_modules/classic-card-addon/addon/components/classic-card.hbs
@@ -0,0 +1 @@
+<li class="classic-card" ...attributes>{{yield}}</li>
diff --git a/test/glint-fixtures/node_modules/classic-card-addon/package.json b/test/glint-fixtures/node_modules/classic-card-addon/package.json
new file mode 100644
index 0000000..7ca9e26
--- /dev/null
+++ b/test/glint-fixtures/node_modules/classic-card-addon/package.json
@@ -0,0 +1,9 @@
+{
+  "name": "classic-card-addon",
+  "version": "1.0.0",
+  "main": "index.js",
+  "keywords": ["ember-addon"],
+  "ember-addon": {
+    "main": "addon-main.js"
+  }
+}
diff --git a/test/integration.test.ts b/test/integration.test.ts
index e76abfd..951af8a 100644
--- a/test/integration.test.ts
+++ b/test/integration.test.ts
@@ -675,6 +675,76 @@ describe('end-to-end fixtures', () => {
     ).toHaveLength(0);
   });
 
+  it('classic-resolver-no-import.hbs: PascalCase tag in `.hbs` resolves via container-style by-name lookup', async () => {
+    // Classic Ember `.hbs` templates resolve PascalCase components
+    // through the container resolver (kebab-case name → installed
+    // addon's component template). No JS `import` is involved.
+    //
+    // Mirrors the ember-website `<EsCard>` pattern: in node_modules,
+    // `classic-card-addon/addon/components/classic-card.hbs` renders
+    // `<li class="..." ...attributes>{{yield}}</li>`. The consumer
+    // wraps an inner `<ul>` in `<ClassicCard>` while inside an outer
+    // `<ul>`. Without by-name resolution the wrapper transparent-blanks
+    // and the inner `<ul>` floats to the outer `<ul>` →
+    // `element-permitted-content` FP-fires.
+    //
+    // With by-name resolution, the plugin substitutes `<ClassicCard>`
+    // to `<li>`, so the inner `<ul>` is correctly nested under `<li>`
+    // (legal) under the outer `<ul>`.
+    //
+    // Validated from `test/glint-fixtures/` instead of `examples/` so
+    // the resolver's node_modules walk finds the fake
+    // `classic-card-addon` (the `examples/` dir doesn't have a sibling
+    // node_modules of fixture addons; glint-fixtures does).
+    const v = makeValidator();
+    const fp = path.join(__dirname, 'glint-fixtures', 'classic-resolver-no-import.hbs');
+    const rawReport = await v.validateFile(fp);
+    const messages = rawReport.results.flatMap((r) =>
+      r.messages.map((m) => ({ rule: m.ruleId, line: m.line, column: m.column, message: m.message })),
+    );
+    const offenders = messages.filter((m) => m.rule === 'element-permitted-content');
+    expect(
+      offenders,
+      `element-permitted-content must not fire — by-name resolution should map <ClassicCard> to <li>; got: ${JSON.stringify(messages)}`,
+    ).toHaveLength(0);
+  });
+
+  it('multi-level-yield-chain-options.gts: heuristic suppression silences element-permitted-content for unresolvable wrappers with structural children', async () => {
+    // Unresolvable curried sub-component case: `<F.Options>` is
+    // `PassThrough` (no specific Element type), wrapped in a
+    // `<FormSelectField>` whose outer Element is bare HTMLElement
+    // (PR #12 → 'transparent'). Without the heuristic, `<option>`
+    // floats to outer `<div>` → FP-fires
+    // `element-permitted-content`. Cross-file yield-chain analysis
+    // would resolve this precisely but is ~250+ lines and deferred.
+    //
+    // The heuristic instead recognizes the pattern: an unresolvable
+    // PascalCase wrapper containing `<option>`/`<th>`/`<li>` children
+    // is presumed to render the structurally-correct parent
+    // (`<select>`/`<thead>`/`<ul>`) at runtime via yield chain.
+    // Suppress `element-permitted-content` for the Source so the FP
+    // doesn't surface.
+    //
+    // Same per-Source-suppression trade-off as Thread B's
+    // wcag/h32 fix: real bugs at OTHER locations in the same template
+    // get suppressed too. Acceptable given the volume of these FPs
+    // in real-world Ember code (HDS's 172 entries, ember-website's
+    // 99 entries).
+    const prevGlint = process.env['HVE_GLINT'];
+    process.env['HVE_GLINT'] = '1';
+    try {
+      const r = await validate('multi-level-yield-chain-options.gts');
+      const offenders = r.messages.filter((m) => m.rule === 'element-permitted-content');
+      expect(
+        offenders,
+        `element-permitted-content must not fire — heuristic suppression should kick in; got: ${JSON.stringify(r.messages)}`,
+      ).toHaveLength(0);
+    } finally {
+      if (prevGlint === undefined) delete process.env['HVE_GLINT'];
+      else process.env['HVE_GLINT'] = prevGlint;
+    }
+  });
+
   it('builtins.hbs: <Input>/<Textarea>/<LinkTo> substitute to native tags', async () => {
     // The built-in Ember component map provides tag substitutions for
     // these three components even without Glint. Validate clean (the
diff --git a/transform.ts b/transform.ts
index da62625..706c321 100644
--- a/transform.ts
+++ b/transform.ts
@@ -10,7 +10,10 @@ import type {
 } from 'html-validate';
 import { createRequire } from 'node:module';
 
+import { preprocess } from '@glimmer/syntax';
+
 import { blankTemplateContent, blankTemplateContentMultipass } from './blank.js';
+import { buildClassicComponentTagMap } from './lib/classic-resolver.js';
 import { isDynamicValuePlaceholder } from './lib/dynamic-value.js';
 import { extractAttrTypeMap } from './lib/glint.js';
 import { extractStringScope } from './lib/scope.js';
@@ -232,7 +235,27 @@ function* transformGlimmer(source: Source): Generator<Source, void, unknown> {
   // mapping to native tags. Static-text resolution covers t-helper /
   // if-helper. No top-level scope (no JS).
   if (filename.endsWith('.hbs')) {
-    const result = blankTemplateContent(data);
+    // Classic-Ember by-name component resolution: parse the template
+    // once to walk PascalCase tags, look each one up in node_modules
+    // against the canonical addon component-template paths, and feed
+    // the resulting tag/attr maps to the blanker. Lets `<EsCard>` /
+    // `<HdsCard>` / etc. substitute to their actual rendered tag
+    // (`<li>`, `<div>`, …) instead of transparent-blanking, which
+    // fixes a major class of `element-permitted-content` FPs in
+    // classic Ember apps. Glint isn't involved — `.hbs` doesn't go
+    // through TS.
+    let classicTagMap: Map<string, string> | null = null;
+    let classicAttrMap: Parameters<typeof blankTemplateContent>[4] | null = null;
+    try {
+      const ast = preprocess(data, { mode: 'codemod' });
+      const maps = buildClassicComponentTagMap(filename, ast);
+      classicTagMap = maps.componentTagMap;
+      classicAttrMap = maps.componentAttrMap;
+    } catch {
+      // Parse failure here is non-fatal — `blankTemplateContent`
+      // re-parses and reports the error. Drop the maps and continue.
+    }
+    const result = blankTemplateContent(data, undefined, undefined, classicTagMap, classicAttrMap);
     if (result.error) {
       process.stderr.write(
         `[html-validate-ember] glimmer parse failure on ${filename}: ${result.error.message}\n`,

From 452b958060fc6a25c25df11040e0105b2b71a77e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20R=C3=B8ed?= <johanroed@gmail.com>
Date: Fri, 8 May 2026 09:34:50 +0200
Subject: [PATCH 02/20] Document PR #21 trade-offs with `.fails()` regression
 tests
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two `.fails()`-marked tests + fixtures pinning down the limitations
this PR explicitly accepts:

1. heuristic-masks-real-bug.gts — Per-Source
   `element-permitted-content` suppression. The same template has
   an unresolvable wrapper with structural children (correct
   suppression target) AND a real `<p><div></div></p>` violation
   that html-validate would normally catch. Whole-Source suppression
   masks the real bug. Asserted as `.fails()` so future yield-chain-
   precise resolution surfaces the win.

2. namespaced-classic-resolver.hbs — `<Forms::TextInput>`-style
   namespaced classic-Ember invocations. The by-name resolver
   currently handles single-segment kebab names only
   (`<EsCard>` → `es-card.hbs`); doesn't parse `::` separators or
   probe nested addon paths like `addon/components/forms/
   text-input.hbs`. `.fails()`-tagged: when namespaced resolution
   lands, vitest signals "remove .fails — your fix worked".

Both tests use the same `.fails()` mechanism the codebase has used
elsewhere (see PR #17's deferred-fix patterns) — the suite passes
today (asserted-fail = pass), the test passes for real when we
narrow / remove the limitation, vitest tells us so we update the
marker.

160/160 passing tests + 2 expected-fail = 162 total.
---
 examples/heuristic-masks-real-bug.gts         | 64 +++++++++++++++++++
 .../namespaced-classic-resolver.hbs           | 16 +++++
 .../addon/components/forms/text-input.hbs     |  1 +
 .../namespaced-card-addon/package.json        |  9 +++
 test/integration.test.ts                      | 48 ++++++++++++++
 5 files changed, 138 insertions(+)
 create mode 100644 examples/heuristic-masks-real-bug.gts
 create mode 100644 test/glint-fixtures/namespaced-classic-resolver.hbs
 create mode 100644 test/glint-fixtures/node_modules/namespaced-card-addon/addon/components/forms/text-input.hbs
 create mode 100644 test/glint-fixtures/node_modules/namespaced-card-addon/package.json

diff --git a/examples/heuristic-masks-real-bug.gts b/examples/heuristic-masks-real-bug.gts
new file mode 100644
index 0000000..b00a55e
--- /dev/null
+++ b/examples/heuristic-masks-real-bug.gts
@@ -0,0 +1,64 @@
+// Documents a trade-off: the per-Source `element-permitted-content`
+// heuristic suppression (PR #21) masks REAL `element-permitted-content`
+// violations in OTHER parts of the same template. Same trade-off shape
+// as PR #17's wcag/h32 suppression for input-driven forms.
+//
+// This template has:
+//   1. An unresolvable wrapper with structural children (triggers
+//      suppression — fine, FP avoidance).
+//   2. A genuine spec violation elsewhere (`<p><div></div></p>` —
+//      `<p>` is phrasing content, can't contain `<div>`). With the
+//      whole-Source suppression, html-validate's
+//      `element-permitted-content` doesn't fire on this either.
+//
+// The accompanying test in `test/integration.test.ts` is marked
+// `it.fails(...)` — it asserts the real bug fires, and when (if) we
+// ever implement multi-level yield-chain analysis, the heuristic
+// suppression will narrow / disappear, the real bug will surface,
+// and vitest will signal "remove .fails — your fix worked".
+import Component from '@glimmer/component';
+
+interface PassThroughSig {
+  Element: HTMLElement;
+  Args: Record<string, never>;
+  Blocks: { default: [] };
+}
+class PassThrough extends Component<PassThroughSig> {
+  <template>
+    {{yield}}
+  </template>
+}
+
+interface FormSelectFieldSig {
+  Args: Record<string, never>;
+  Blocks: { default: [{ Options?: typeof PassThrough }] };
+  Element: HTMLElement;
+}
+class FormSelectField extends Component<FormSelectFieldSig> {
+  <template>
+    {{yield (hash Options=PassThrough)}}
+  </template>
+}
+
+<template>
+  <div>
+    {{! 1. Heuristic-suppression target (curried sub-component
+         containing <option> children — wrapper presumed to render
+         <select> via yield chain). }}
+    <FormSelectField as |F|>
+      <F.Options>
+        <option value='one'>One</option>
+      </F.Options>
+    </FormSelectField>
+
+    {{! 2. Genuine spec violation: <p> is phrasing content, can't
+         contain <div>. html-validate would normally flag this — but
+         our heuristic disables `element-permitted-content` for the
+         whole Source, masking it. }}
+    <p>
+      <div>this should fire element-permitted-content but doesn't</div>
+    </p>
+  </div>
+</template>
+
+const hash = <T,>(o: T): T => o;
diff --git a/test/glint-fixtures/namespaced-classic-resolver.hbs b/test/glint-fixtures/namespaced-classic-resolver.hbs
new file mode 100644
index 0000000..3c34dc2
--- /dev/null
+++ b/test/glint-fixtures/namespaced-classic-resolver.hbs
@@ -0,0 +1,16 @@
+{{!--
+  Namespaced classic-Ember component invocation: `<Forms::TextInput>`.
+  At runtime Ember's container resolver maps `Forms::TextInput` to
+  `forms/text-input.hbs` — a slash-namespaced template path.
+
+  Our by-name resolver in `lib/classic-resolver.ts` only handles
+  single-segment kebab names (`<EsCard>` → `es-card.hbs`). It doesn't
+  parse the `::` namespace separator and doesn't probe nested paths
+  like `addon/components/forms/text-input.hbs`.
+
+  Documents this limitation. The accompanying test is `it.fails(...)`
+  so future namespaced-component support shows up as a passing test.
+--}}
+<form>
+  <Forms::TextInput @value="hello" />
+</form>
diff --git a/test/glint-fixtures/node_modules/namespaced-card-addon/addon/components/forms/text-input.hbs b/test/glint-fixtures/node_modules/namespaced-card-addon/addon/components/forms/text-input.hbs
new file mode 100644
index 0000000..e59de08
--- /dev/null
+++ b/test/glint-fixtures/node_modules/namespaced-card-addon/addon/components/forms/text-input.hbs
@@ -0,0 +1 @@
+<input class="ns-input" ...attributes>
diff --git a/test/glint-fixtures/node_modules/namespaced-card-addon/package.json b/test/glint-fixtures/node_modules/namespaced-card-addon/package.json
new file mode 100644
index 0000000..9b26fb8
--- /dev/null
+++ b/test/glint-fixtures/node_modules/namespaced-card-addon/package.json
@@ -0,0 +1,9 @@
+{
+  "name": "namespaced-card-addon",
+  "version": "1.0.0",
+  "main": "index.js",
+  "keywords": ["ember-addon"],
+  "ember-addon": {
+    "main": "addon-main.js"
+  }
+}
diff --git a/test/integration.test.ts b/test/integration.test.ts
index 951af8a..a30cc45 100644
--- a/test/integration.test.ts
+++ b/test/integration.test.ts
@@ -709,6 +709,54 @@ describe('end-to-end fixtures', () => {
     ).toHaveLength(0);
   });
 
+  it.fails(
+    'namespaced-classic-resolver.hbs: <Forms::TextInput> is NOT yet resolved by the by-name resolver (single-segment only)',
+    async () => {
+      // The classic-by-name resolver in `lib/classic-resolver.ts` only
+      // handles single-segment kebab names — `<EsCard>` → `es-card.hbs`.
+      // It doesn't parse Ember's `::` namespace separator nor probe
+      // nested addon paths like `addon/components/forms/text-input.hbs`.
+      //
+      // Asserted via the structural shape: with proper resolution,
+      // `<Forms::TextInput>` would substitute to `<input>` and the
+      // template would lint clean. Today the wrapper transparent-
+      // blanks, leaving an empty `<form>` — which fires wcag/h32
+      // because there's no submit button visible. We assert wcag/h32
+      // does NOT fire (intended future behavior). Today it fires →
+      // .fails() passes the suite. When namespaced resolution lands,
+      // the test passes for real and vitest signals the win.
+      const v = makeValidator();
+      const fp = path.join(__dirname, 'glint-fixtures', 'namespaced-classic-resolver.hbs');
+      const r = await v.validateFile(fp);
+      const wcagH32 = r.results
+        .flatMap((rr) => rr.messages)
+        .filter((m) => m.ruleId === 'wcag/h32');
+      expect(wcagH32).toHaveLength(0);
+    },
+  );
+
+  it.fails(
+    'heuristic-masks-real-bug.gts: per-Source element-permitted-content suppression DOES mask real bugs elsewhere (documented trade-off)',
+    async () => {
+      // Documents PR #21's per-Source suppression trade-off. The
+      // template has an unresolvable wrapper with structural children
+      // (triggers suppression, correct) AND a real `<p><div></div></p>`
+      // spec violation (which html-validate would normally catch).
+      // With the whole-Source suppression, the real bug is masked.
+      //
+      // Marked `.fails(...)` so this asserts our intended-but-not-yet-
+      // achieved future behavior: when we eventually implement multi-
+      // level yield-chain analysis, heuristic suppression narrows or
+      // disappears, the real bug surfaces, this assertion starts to
+      // pass, and vitest signals "remove .fails — your fix worked".
+      const r = await validate('heuristic-masks-real-bug.gts');
+      const offenders = r.messages.filter((m) => m.rule === 'element-permitted-content');
+      // Today: 0 (whole-Source suppression masks the real bug).
+      // Aspiration: 1 (the real <p><div></div></p> violation).
+      expect(offenders.length).toBeGreaterThan(0);
+    },
+  );
+
   it('multi-level-yield-chain-options.gts: heuristic suppression silences element-permitted-content for unresolvable wrappers with structural children', async () => {
     // Unresolvable curried sub-component case: `<F.Options>` is
     // `PassThrough` (no specific Element type), wrapped in a

From 1221959c5d54eaa62d79c67e8b5a6e8048b84649 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20R=C3=B8ed?= <johanroed@gmail.com>
Date: Fri, 8 May 2026 11:55:38 +0200
Subject: [PATCH 03/20] Regression test: heuristic must NOT suppress when Glint
 resolves precisely

Verifies the gating in `containsContentRestrictedStructuralChild` defers
to Glint when it has a precise resolution. Without this gating the
heuristic over-suppresses: a real `<th>`-under-`<select>` violation
inside `<C.Options>` (resolved to `<select>` via PR #18) would be
silenced.

Lives under `test/glint-fixtures/` so the local tsconfig wires up
Glint type extraction; `examples/` has no tsconfig and Glint stays
disabled there, which would mask the gate.
---
 .../glint-resolved-no-suppression.gts         | 46 +++++++++++++++++++
 test/integration.test.ts                      | 30 ++++++++++++
 2 files changed, 76 insertions(+)
 create mode 100644 test/glint-fixtures/glint-resolved-no-suppression.gts

diff --git a/test/glint-fixtures/glint-resolved-no-suppression.gts b/test/glint-fixtures/glint-resolved-no-suppression.gts
new file mode 100644
index 0000000..6af33eb
--- /dev/null
+++ b/test/glint-fixtures/glint-resolved-no-suppression.gts
@@ -0,0 +1,46 @@
+// Regression: heuristic suppression must NOT fire when Glint has
+// already resolved a curried sub-component to a precise native tag.
+//
+// `<C.Options>` resolves to `<select>` via PR #18's
+// `resolveElementFromComponentRefType` (`aliasTypeArguments[0]['Element']`
+// reads `HTMLSelectElement` off `OptionsSig`).
+//
+// `<th>` is structurally restricted to `<tr>` ancestors — illegal under
+// `<select>`. Without correct gating, PR #21's heuristic would over-
+// suppress: it sees an unresolvable-looking PascalCase/dotted wrapper
+// containing a content-restricted child and disables
+// `element-permitted-content` for the whole Source. With correct
+// gating, the heuristic checks Glint's resolution first and bails out
+// — letting `element-permitted-content` fire on the real bug.
+import Component from '@glimmer/component';
+import { hash } from '@ember/helper';
+import type { TOC } from '@ember/component/template-only';
+
+interface OptionsSig {
+  Element: HTMLSelectElement;
+  Blocks: { default: [] };
+}
+const Options: TOC<OptionsSig> = <template>
+  <select ...attributes>{{yield}}</select>
+</template>;
+
+interface SelectBaseSig {
+  Element: HTMLDivElement;
+  Blocks: { default: [{ Options: typeof Options }] };
+}
+class SelectBase extends Component<SelectBaseSig> {
+  Options = Options;
+  <template>
+    <div ...attributes>
+      {{yield (hash Options=this.Options)}}
+    </div>
+  </template>
+}
+
+<template>
+  <SelectBase as |C|>
+    <C.Options>
+      <th>not allowed under select</th>
+    </C.Options>
+  </SelectBase>
+</template>
diff --git a/test/integration.test.ts b/test/integration.test.ts
index a30cc45..39670c6 100644
--- a/test/integration.test.ts
+++ b/test/integration.test.ts
@@ -793,6 +793,36 @@ describe('end-to-end fixtures', () => {
     }
   });
 
+  it('glint-resolved-no-suppression.gts: heuristic must NOT suppress when Glint resolved the wrapper to a precise native tag', async () => {
+    // Regression for the gating in `containsContentRestrictedStructuralChild`:
+    // when Glint resolves `<C.Options>` to `<select>` (via PR #18), the
+    // heuristic must defer to Glint and let `element-permitted-content`
+    // fire on a real `<th>`-under-`<select>` violation. Earlier
+    // implementations risked over-suppressing because the wrapper's tag
+    // looked unresolvable (PascalCase/dotted) at the AST level.
+    //
+    // Lives under `test/glint-fixtures/` (not `examples/`) so the local
+    // tsconfig.json wires up Glint type extraction for the fixture.
+    const prevGlint = process.env['HVE_GLINT'];
+    process.env['HVE_GLINT'] = '1';
+    try {
+      const v = makeValidator();
+      const fp = path.join(__dirname, 'glint-fixtures', 'glint-resolved-no-suppression.gts');
+      const rawReport = await v.validateFile(fp);
+      const messages = rawReport.results.flatMap((r) =>
+        r.messages.map((m) => ({ rule: m.ruleId, line: m.line, column: m.column, message: m.message })),
+      );
+      const offenders = messages.filter((m) => m.rule === 'element-permitted-content');
+      expect(
+        offenders.length,
+        `element-permitted-content MUST fire (Glint resolved <C.Options> to <select> and <th> is illegal there); got: ${JSON.stringify(messages)}`,
+      ).toBeGreaterThan(0);
+    } finally {
+      if (prevGlint === undefined) delete process.env['HVE_GLINT'];
+      else process.env['HVE_GLINT'] = prevGlint;
+    }
+  });
+
   it('builtins.hbs: <Input>/<Textarea>/<LinkTo> substitute to native tags', async () => {
     // The built-in Ember component map provides tag substitutions for
     // these three components even without Glint. Validate clean (the

From 24e998a7456ea903b5a6c497f5709c610b42f4d1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20R=C3=B8ed?= <johanroed@gmail.com>
Date: Fri, 8 May 2026 13:30:15 +0200
Subject: [PATCH 04/20] Project mustache-bound src/alt through classic-resolved
 <img>
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When the classic-by-name resolver substitutes `<MyImg>` to `<img>`
because the addon's template has `<img src={{this.src}} ...attributes />`,
the consumer's narrow Glimmer-attr blank slots (`@src="…"`) can't fit
the projected `src='   '` placeholder via tryInjectComponentAttrs's
source-side rewrite, and `element-required-attributes` FP-fires.

Mirror PR #13's narrow-slot fix: when resolved=='img' and the addon's
attrCtx records `src`/`alt` (literal OR mustache-bound), push the
consumer's offset to `imgSplatOffsets`. The processElement hook then
calls setAttribute at parse time with a DynamicValue, sidestepping
source-width entirely.

Caught by ecosystem CI on PR #21 baseline diff: ember-website's
`<ResponsiveImage @src="…" alt="" />` started FP-firing because the
new by-name resolver mapped it to `<img>` but didn't carry the
mustache-bound `src` from the addon's template through to the
consumer-side substitution.
---
 blank.ts                                      | 34 ++++++++++++++++++-
 .../classic-resolver-mustache-bound-attrs.hbs | 15 ++++++++
 .../addon/components/mustache-bound-img.hbs   | 11 ++++++
 .../mustache-img-addon/package.json           |  1 +
 test/integration.test.ts                      | 32 +++++++++++++++++
 5 files changed, 92 insertions(+), 1 deletion(-)
 create mode 100644 test/glint-fixtures/classic-resolver-mustache-bound-attrs.hbs
 create mode 100644 test/glint-fixtures/node_modules/mustache-img-addon/addon/components/mustache-bound-img.hbs
 create mode 100644 test/glint-fixtures/node_modules/mustache-img-addon/package.json

diff --git a/blank.ts b/blank.ts
index dcf9248..5b57b8f 100644
--- a/blank.ts
+++ b/blank.ts
@@ -595,7 +595,7 @@ function handleGlintSubstitution(node: AST.ElementNode, ctx: Context): string |
     //     Loses parent attrs but supplies content via DynamicValue text
     //     (registered in dynamicContentOffsets) and `type=' '` for button.
     if (VOID_ELEMENTS.has(resolved)) {
-      return substituteSelfClosingVoidComponent(node, ctx, resolved) ? resolved : null;
+      return substituteSelfClosingVoidComponent(node, ctx, resolved, attrCtx) ? resolved : null;
     }
     return substituteSelfClosingComponent(node, ctx, resolved, attrCtx) ? resolved : null;
   }
@@ -661,6 +661,7 @@ function substituteSelfClosingVoidComponent(
   node: AST.ElementNode,
   ctx: Context,
   resolved: string,
+  attrCtx?: ComponentAttrs | null,
 ): boolean {
   const elementStart = startOffset(node);
   // Minimum required: room for `<RESOLVED` (tag-name rename only).
@@ -672,9 +673,40 @@ function substituteSelfClosingVoidComponent(
   if (resolved === 'input') {
     tryInjectInputType(node, ctx);
   }
+  // For <img> substitutions where the addon's splatted-root binds `src`
+  // / `alt` (literal OR mustache-driven), record the offset so the
+  // `processElement` hook synthesizes those attrs at parse time. The
+  // source-side `tryInjectComponentAttrs` path can't always fit the
+  // placeholders in the consumer's narrow Glimmer-attr slots
+  // (`@src="…"` is typically narrower than `src='   '` plus other
+  // injected attrs combined). Skipped when the consumer wrote `src=` /
+  // `alt=` explicitly.
+  if (resolved === 'img' && attrCtx) {
+    tryInjectImgRequiredAttrsViaHook(node, ctx, attrCtx);
+  }
   return true;
 }
 
+// Variant of tryInjectImgRequiredAttrs scoped to component-substituted
+// <img>: the addon's splatted-root template is recorded as
+// `attrCtx.attrs`. If `src`/`alt` are projected there (via literal OR
+// mustache) and the consumer didn't override, push the consumer's
+// element offset so the processElement hook runs setAttribute.
+function tryInjectImgRequiredAttrsViaHook(
+  node: AST.ElementNode,
+  ctx: Context,
+  attrCtx: ComponentAttrs,
+): void {
+  const present = new Set((node.attributes ?? []).map((a) => a.name));
+  // `src` / `alt` ATTRS on the consumer (not @src / @alt args) take
+  // precedence — the consumer chose to write the literal, html-validate
+  // should validate it. Skip the hook in that case.
+  const needsSrc = !present.has('src') && attrCtx.attrs['src'] !== undefined;
+  const needsAlt = !present.has('alt') && attrCtx.attrs['alt'] !== undefined;
+  if (!needsSrc && !needsAlt) return;
+  ctx.imgSplatOffsets.push(startOffset(node));
+}
+
 // Find a Glimmer-only attribute (`@arg`, modifier, `...attributes`)
 // whose source span has room for `type='X'` (no newlines), and rewrite
 // the first chars of that span. The remainder of the attribute's range
diff --git a/test/glint-fixtures/classic-resolver-mustache-bound-attrs.hbs b/test/glint-fixtures/classic-resolver-mustache-bound-attrs.hbs
new file mode 100644
index 0000000..48ca742
--- /dev/null
+++ b/test/glint-fixtures/classic-resolver-mustache-bound-attrs.hbs
@@ -0,0 +1,15 @@
+{{!--
+  Regression: classic-by-name resolver substituting <MustacheBoundImg>
+  to <img>. The addon's template binds `src={{this.src}}` (mustache,
+  not literal). Without the hook-time injection the consumer-side
+  blank slot for `@src=…` is too narrow to fit `src='   '` plus other
+  projected attrs, and `element-required-attributes` FP-fires.
+
+  The fix: when the addon's `attrCtx.attrs['src']` is set
+  (DYNAMIC_VALUE_PLACEHOLDER for mustache-bound), push the consumer's
+  offset to `imgSplatOffsets` so the processElement hook calls
+  setAttribute at parse time. This sidesteps the source-width problem.
+
+  Mirrors ember-website's `<ResponsiveImage @src="…" alt="" />` pattern.
+--}}
+<MustacheBoundImg @src="/foo.png" @width={{100}} alt="" class="x" role="presentation" />
diff --git a/test/glint-fixtures/node_modules/mustache-img-addon/addon/components/mustache-bound-img.hbs b/test/glint-fixtures/node_modules/mustache-img-addon/addon/components/mustache-bound-img.hbs
new file mode 100644
index 0000000..e8eb145
--- /dev/null
+++ b/test/glint-fixtures/node_modules/mustache-img-addon/addon/components/mustache-bound-img.hbs
@@ -0,0 +1,11 @@
+<picture>
+  <img
+    src={{this.src}}
+    width={{this.width}}
+    height={{this.height}}
+    class={{this.classNames}}
+    loading="lazy"
+    decoding="async"
+    ...attributes
+  />
+</picture>
diff --git a/test/glint-fixtures/node_modules/mustache-img-addon/package.json b/test/glint-fixtures/node_modules/mustache-img-addon/package.json
new file mode 100644
index 0000000..9353007
--- /dev/null
+++ b/test/glint-fixtures/node_modules/mustache-img-addon/package.json
@@ -0,0 +1 @@
+{"name":"responsive-image-test","version":"0.0.0","keywords":["ember-addon"]}
diff --git a/test/integration.test.ts b/test/integration.test.ts
index 39670c6..d1c947a 100644
--- a/test/integration.test.ts
+++ b/test/integration.test.ts
@@ -675,6 +675,38 @@ describe('end-to-end fixtures', () => {
     ).toHaveLength(0);
   });
 
+  it('classic-resolver-mustache-bound-attrs.hbs: classic-resolved <img> with addon-side `src={{this.src}}` does not FP-fire element-required-attributes', async () => {
+    // Regression for the by-name resolver's mustache-bound-attr projection.
+    // Addon's template binds `src={{this.src}}` (mustache, not literal).
+    // Without hook-time injection the source-side blank slots in the
+    // consumer (`@src="…"`, `@width={{100}}`) are too narrow to fit the
+    // projected `src='   '` placeholder, and `element-required-attributes`
+    // FP-fires on the substituted <img>.
+    //
+    // The fix: when the resolved tag is <img> and the addon records
+    // `src` (or `alt`) in `attrCtx.attrs` — including the
+    // DYNAMIC_VALUE_PLACEHOLDER for mustache-bound values — push the
+    // consumer's offset to `imgSplatOffsets`, the same hook the
+    // `<img ...attributes>` narrow-slot fix uses (PR #13).
+    //
+    // Mirrors ember-website's `<ResponsiveImage @src="…" alt="" />`
+    // pattern: addon binds `src={{this.src}}`, runtime <img> always
+    // gets a src.
+    const v = makeValidator();
+    const fp = path.join(__dirname, 'glint-fixtures', 'classic-resolver-mustache-bound-attrs.hbs');
+    const rawReport = await v.validateFile(fp);
+    const messages = rawReport.results.flatMap((r) =>
+      r.messages.map((m) => ({ rule: m.ruleId, line: m.line, column: m.column, message: m.message })),
+    );
+    const offenders = messages.filter(
+      (m) => m.rule === 'element-required-attributes' || m.rule === 'wcag/h37',
+    );
+    expect(
+      offenders,
+      `element-required-attributes / wcag/h37 must not fire — addon-side src/alt are mustache-bound but exist; got: ${JSON.stringify(messages)}`,
+    ).toHaveLength(0);
+  });
+
   it('classic-resolver-no-import.hbs: PascalCase tag in `.hbs` resolves via container-style by-name lookup', async () => {
     // Classic Ember `.hbs` templates resolve PascalCase components
     // through the container resolver (kebab-case name → installed

From 09ab145c4c71aa37b1142f45a63cb0a1bf20e0c5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20R=C3=B8ed?= <johanroed@gmail.com>
Date: Fri, 8 May 2026 13:52:22 +0200
Subject: [PATCH 05/20] Address Copilot review feedback on PR #21
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

C1: drop unused `preprocess` import from lib/classic-resolver.ts.
    `verbatimModuleSyntax` would otherwise preserve it in emitted JS.

C2: rewrite the cache-comment block in lib/classic-resolver.ts to match
    the actual key shape — `(consumer-dir, kebab-name)`, not
    `(node_modules-root, kebab-name)`. Drop the misleading "(tests)"
    note about `_clearClassicResolverCache`; record it as exported for
    manual reset if needed.

C3: docstring for `buildClassicComponentTagMap` claimed it walks
    "PascalCase / dotted invocation". The matcher excludes dotted
    (`/^[A-Z][A-Za-z0-9]*$/`). Comment now says single-segment
    PascalCase, with examples of what's excluded.

C4: comment in `containsContentRestrictedStructuralChild` claimed only
    fully-unresolved wrappers trigger suppression. The code also falls
    through on `'transparent'`. Comment now states both cases match the
    children-check path.

C5: `.hbs` classic resolver in transform.ts called `preprocess(data)`
    directly; `blankTemplateContent` first runs
    `stripBlockParamTypeAnnotations` to handle `as |x: T|`. A typed-
    block-param `.hbs` would have silently lost classic resolution.
    Export the stripper from blank.ts and apply it before the classic-
    resolver parse so both paths agree. Practically rare (typed params
    are a `.gts/.gjs` convention) but keeps the two paths consistent.
---
 blank.ts                | 13 ++++++++-----
 lib/classic-resolver.ts | 23 ++++++++++++++++-------
 transform.ts            | 13 +++++++++++--
 3 files changed, 35 insertions(+), 14 deletions(-)

diff --git a/blank.ts b/blank.ts
index 5b57b8f..6c2270f 100644
--- a/blank.ts
+++ b/blank.ts
@@ -368,7 +368,7 @@ function findCloseTagStart(content: string, elementEnd: number): number {
 // bracket tracking for `()`, `{}`, `<>`, `[]` so union (`A | B`),
 // object (`{ a: number }`), parenthesized (`(A | B)[]`), and generic
 // (`Map<string, number>`) types are stripped correctly.
-function stripBlockParamTypeAnnotations(content: string): string {
+export function stripBlockParamTypeAnnotations(content: string): string {
   const buf = content.split('');
   let i = 0;
   while (i < content.length - 1) {
@@ -1619,10 +1619,13 @@ const CONTENT_RESTRICTED_STRUCTURAL_CHILDREN: ReadonlySet<string> = new Set([
 // for native ElementNode children. Doesn't recurse into other
 // component invocations — those have their own rule check.
 //
-// Resolved components are excluded: if Glint already maps the wrapper
-// to a specific native tag, we trust that resolution and let
-// `element-permitted-content` fire normally. Only fully-unresolved
-// wrappers (componentTagMap miss) trigger suppression.
+// Components Glint resolved to a specific native tag are excluded: we
+// trust that resolution and let `element-permitted-content` fire
+// normally. Wrappers that are MISSING from the map AND wrappers Glint
+// resolved as `'transparent'` (children float to parent because the
+// element-type was `unknown`/`any` or generic `HTMLElement`) both fall
+// through to the children check — those are the cases where we can't
+// statically tell what runtime tag the wrapper renders.
 function containsContentRestrictedStructuralChild(
   node: AST.ElementNode,
   glintComponentTagMap: ReadonlyMap<string, string> | null | undefined,
diff --git a/lib/classic-resolver.ts b/lib/classic-resolver.ts
index 9873f4b..f9525d6 100644
--- a/lib/classic-resolver.ts
+++ b/lib/classic-resolver.ts
@@ -12,15 +12,23 @@
 // root tag.
 //
 // Cache:
-//   - In-memory per-(node_modules-root, kebab-name) → ComponentAttrs.
-//     Process-lifetime; cleared via `_clearClassicResolverCache` (tests).
+//   - In-memory per-(consumer-dir, kebab-name) → ComponentAttrs.
+//     Keyed off the consumer file's directory rather than a resolved
+//     node_modules root: cheap to compute, and the lookup is already
+//     local (we don't repeat the upward walk on a hit). Trade-off: two
+//     consumers in different directories under the same node_modules
+//     re-do the addon scan; tolerated because the scan itself is bounded
+//     by `existsSync` probes per addon, and the cost is paid once per
+//     (consumer-dir, kebab-name) pair for the rest of the process.
+//     Process-lifetime; `_clearClassicResolverCache` is exported for
+//     manual reset if a future test ever needs it.
 //   - Negatives are NOT cached: an addon installed mid-session would
 //     otherwise stay invisible until process restart. Negative path is
 //     cheap (regex + a handful of existsSync up to filesystem root).
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { preprocess, traverse } from '@glimmer/syntax';
+import { traverse } from '@glimmer/syntax';
 import type { AST } from '@glimmer/syntax';
 
 import type { ComponentAttrs } from './builtin-components.js';
@@ -132,10 +140,11 @@ function isLowercaseHtmlTag(tag: string): boolean {
   return /^[a-z][a-z0-9-]*$/.test(tag);
 }
 
-// Walk a template AST, find every PascalCase / dotted invocation, and
-// build a `componentTagMap` + `componentAttrMap` keyed by `line:col`
-// (matching what the Glint resolver produces). Both maps are returned;
-// callers pass them to `blankTemplateContent`.
+// Walk a template AST, find every single-segment PascalCase invocation
+// (`<EsCard>`, not `<This.Foo>` or `<Forms::TextInput>`), and build a
+// `componentTagMap` + `componentAttrMap` keyed by `line:col` (matching
+// what the Glint resolver produces). Both maps are returned; callers
+// pass them to `blankTemplateContent`.
 //
 // Skips:
 //   - Builtin components (`<Input>`, `<Textarea>`, `<LinkTo>`) — handled
diff --git a/transform.ts b/transform.ts
index 706c321..9c31438 100644
--- a/transform.ts
+++ b/transform.ts
@@ -12,7 +12,11 @@ import { createRequire } from 'node:module';
 
 import { preprocess } from '@glimmer/syntax';
 
-import { blankTemplateContent, blankTemplateContentMultipass } from './blank.js';
+import {
+  blankTemplateContent,
+  blankTemplateContentMultipass,
+  stripBlockParamTypeAnnotations,
+} from './blank.js';
 import { buildClassicComponentTagMap } from './lib/classic-resolver.js';
 import { isDynamicValuePlaceholder } from './lib/dynamic-value.js';
 import { extractAttrTypeMap } from './lib/glint.js';
@@ -247,7 +251,12 @@ function* transformGlimmer(source: Source): Generator<Source, void, unknown> {
     let classicTagMap: Map<string, string> | null = null;
     let classicAttrMap: Parameters<typeof blankTemplateContent>[4] | null = null;
     try {
-      const ast = preprocess(data, { mode: 'codemod' });
+      // Match `blankTemplateContent`'s preprocessing: strip TS-style
+      // block-param type annotations (`as |x: T|`) before parsing so a
+      // `.hbs` file using that syntax doesn't silently lose classic
+      // resolution. Rare in practice (typed params are conventionally
+      // `.gts`), but keeps both paths consistent.
+      const ast = preprocess(stripBlockParamTypeAnnotations(data), { mode: 'codemod' });
       const maps = buildClassicComponentTagMap(filename, ast);
       classicTagMap = maps.componentTagMap;
       classicAttrMap = maps.componentAttrMap;

From 57dfde7a0250324e6f42a891dfbc347b22a17da3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20R=C3=B8ed?= <johanroed@gmail.com>
Date: Fri, 8 May 2026 13:58:55 +0200
Subject: [PATCH 06/20] Address two more Copilot review comments on PR #21
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

C6 (blank.ts): `containsContentRestrictedStructuralChild` descended
    into BOTH arms of every `{{#if}}/{{else}}` regardless of which
    branch the current multipass pass emits. A structural child living
    in the inactive arm could trigger Source-wide
    `element-permitted-content` suppression and mask a real violation
    in the active arm. Pass `branchSelections` through and use
    `selectBranch` (mirrors the outer `detectStructuralYieldRules`
    walker) so only the chosen arm contributes to suppression
    decisions.

C7 (lib/classic-resolver.ts): probe order for addon component
    templates differed from `lib/glint.ts:resolveAddonHbsTemplate`
    (`addon/templates/components` → `addon/components` → `app/components`
    here vs `addon/templates/components` → `app/components` →
    `addon/components` there). Aligned the classic-by-name resolver to
    the existing import-based order so a `.gts` consumer and `.hbs`
    consumer of the same addon resolve to the same template.
---
 blank.ts                | 13 ++++++++++---
 lib/classic-resolver.ts |  7 +++++--
 2 files changed, 15 insertions(+), 5 deletions(-)

diff --git a/blank.ts b/blank.ts
index 6c2270f..78adcf1 100644
--- a/blank.ts
+++ b/blank.ts
@@ -1513,7 +1513,7 @@ function detectStructuralYieldRules(
           out.push('wcag/h71');
         } else if (
           !isNativeTag(stmt.tag) &&
-          containsContentRestrictedStructuralChild(stmt, glintComponentTagMap)
+          containsContentRestrictedStructuralChild(stmt, glintComponentTagMap, branchSelections)
         ) {
           // Unresolvable PascalCase / dotted wrapper containing
           // content-restricted structural children (`<option>`, `<th>`,
@@ -1629,6 +1629,7 @@ const CONTENT_RESTRICTED_STRUCTURAL_CHILDREN: ReadonlySet<string> = new Set([
 function containsContentRestrictedStructuralChild(
   node: AST.ElementNode,
   glintComponentTagMap: ReadonlyMap<string, string> | null | undefined,
+  branchSelections?: ReadonlyMap<number, BranchChoice>,
 ): boolean {
   // If Glint has resolved this wrapper to a native tag, no heuristic
   // needed — the precise resolution wins and the rule fires (or
@@ -1638,13 +1639,19 @@ function containsContentRestrictedStructuralChild(
     const resolved = glintComponentTagMap.get(key);
     if (resolved && resolved !== 'transparent') return false;
   }
+  // Walk only the arm that matches what the blanker emits in this pass.
+  // Without `selectBranch`, descending into both arms of a
+  // `{{#if}}/{{else}}` would let one branch's structural children
+  // trigger Source-wide suppression even when that branch isn't being
+  // emitted — silently masking real `element-permitted-content`
+  // violations in the active branch.
   function check(stmts: ReadonlyArray<AST.Statement>): boolean {
     for (const stmt of stmts) {
       if (stmt.type === 'ElementNode') {
         if (CONTENT_RESTRICTED_STRUCTURAL_CHILDREN.has(stmt.tag)) return true;
       } else if (stmt.type === 'BlockStatement') {
-        if (check(stmt.program.body)) return true;
-        if (stmt.inverse && check(stmt.inverse.body)) return true;
+        const arm = selectBranch(stmt, branchSelections);
+        if (arm && check(arm.body)) return true;
       }
     }
     return false;
diff --git a/lib/classic-resolver.ts b/lib/classic-resolver.ts
index f9525d6..d87a5a6 100644
--- a/lib/classic-resolver.ts
+++ b/lib/classic-resolver.ts
@@ -55,12 +55,15 @@ function pascalCaseToKebab(name: string): string {
 
 // Probe an addon directory for a component template by kebab-name.
 // Returns the parsed splatted-root or null. Tries the three canonical
-// classic-Ember component template paths.
+// classic-Ember component template paths in the same order as
+// `lib/glint.ts:resolveAddonHbsTemplate` so `.hbs` and `.gts`
+// consumers resolve identically when an addon ships templates in
+// multiple paths.
 function tryProbeAddon(addonRoot: string, kebabName: string): ComponentAttrs | null {
   for (const sub of [
     `addon/templates/components/${kebabName}.hbs`,
-    `addon/components/${kebabName}.hbs`,
     `app/components/${kebabName}.hbs`,
+    `addon/components/${kebabName}.hbs`,
   ]) {
     const hbsPath = path.join(addonRoot, sub);
     if (!fs.existsSync(hbsPath)) continue;

From 289e75add302866d6f6906a7d9a8833119146c1e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20R=C3=B8ed?= <johanroed@gmail.com>
Date: Fri, 8 May 2026 15:18:53 +0200
Subject: [PATCH 07/20] Fall back to template-root tag when Glint resolves to
 'transparent'
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When `resolveComponentElement` returns 'transparent' (the component
declares `Element: HTMLElement` bare, or the type chain didn't
propagate cleanly across a barrel re-export so Glint can't pin a
specific tag), we previously left the component in 'transparent' and
let children float to whatever native ancestor exists in source.
That's the right call when we have no better information — but for a
TOC whose `<template>` literally writes `<li ...attributes>` /
`<button ...attributes>` / etc., we already extracted the splatted
root in `componentAttrMap`. Use that tag instead. The runtime DOM
matches the template-root tag, so the substitution is at least as
accurate as 'transparent' and lets `element-permitted-content`
validate the correct parent context.

Documented limitation (`leaf-element-under-list-wrapper-consumer.gts`,
`.fails()`): when a component declares `Element: HTMLAnchorElement`
(or any leaf-interactive type) but its template wraps the anchor
inside a non-leaf wrapper (`<ListItem><a ...attributes>{{yield}}</a></ListItem>`),
Glint resolves to the leaf tag (`<a>`); our substitution puts `<a>`
directly under the consumer's `<ul>` even though the runtime DOM is
`<ul><li><a></a></li></ul>`. Fixing that needs recursive cross-file
template walking — deferred.

Updated `does NOT resolve generic HTMLElement to <abbr>` test:
component template root is `<div>{{yield}}</div>`, so the resolution
now lands on 'div' (more accurate) instead of 'transparent' (the
PR #12-era conservative fallback).
---
 lib/glint.ts                                  | 26 +++--
 ...af-element-under-list-wrapper-consumer.gts | 64 +++++++++++++
 .../transparent-li-wrapper-consumer.gts       | 45 +++++++++
 test/glint.test.ts                            | 96 +++++++++++++++----
 4 files changed, 209 insertions(+), 22 deletions(-)
 create mode 100644 test/glint-fixtures/leaf-element-under-list-wrapper-consumer.gts
 create mode 100644 test/glint-fixtures/transparent-li-wrapper-consumer.gts

diff --git a/lib/glint.ts b/lib/glint.ts
index e1faab4..2ea9a8d 100644
--- a/lib/glint.ts
+++ b/lib/glint.ts
@@ -990,16 +990,30 @@ export function extractAttrTypeMap(filename: string, contents: string): Extracti
             const first = roots[0];
             if (first) {
               componentAttrMap.set(key, first);
+              // When Glint's TS-only resolution couldn't pin a specific
+              // tag (`null` or `'transparent'`) — typically because the
+              // component declares `Element: HTMLElement` (bare generic),
+              // or because the type chain didn't propagate cleanly across
+              // a barrel re-export — fall back to the splatted-root's tag
+              // from the component's own template. The runtime render IS
+              // that tag (the template literally writes `<li ...attributes>`,
+              // `<button ...attributes>`, etc.), so this is at least as
+              // accurate as 'transparent' and lets `element-permitted-
+              // content` validate the correct parent context.
+              if ((tag === null || tag === 'transparent') && isNativeTag(first.tag)) {
+                componentTagMap.set(key, first.tag);
+              }
             }
           }
         }
         // Classic Ember addon fallback: when the JS-driven resolution
-        // didn't yield a concrete tag (null, or 'transparent' meaning
-        // unknown/any element type), try the component's `.hbs` template
-        // via the addon's import path. Modern shapes (class form, TOC
-        // forms, curried block-params) already resolved above take
-        // priority — this only runs as a last resort.
-        if (tag === null || tag === 'transparent') {
+        // didn't yield a concrete tag AND the same-package template
+        // didn't either, try the component's `.hbs` template via the
+        // addon's import path. Modern shapes (class form, TOC forms,
+        // curried block-params) already resolved above take priority —
+        // this only runs as a last resort.
+        const currentTag = componentTagMap.get(key);
+        if (currentTag === undefined || currentTag === 'transparent') {
           const addonRoot = resolveAddonHbsTemplate(ts, checker, emitCall, filename);
           if (addonRoot) {
             componentTagMap.set(key, addonRoot.tag);
diff --git a/test/glint-fixtures/leaf-element-under-list-wrapper-consumer.gts b/test/glint-fixtures/leaf-element-under-list-wrapper-consumer.gts
new file mode 100644
index 0000000..9bbda16
--- /dev/null
+++ b/test/glint-fixtures/leaf-element-under-list-wrapper-consumer.gts
@@ -0,0 +1,64 @@
+// Documents a deeper wrapper-vs-leaf FP class my template-root
+// fallback does NOT solve.
+//
+// Pattern (real-world: design-system list-link components):
+//
+//   `<XListLink>` declares `Element: HTMLAnchorElement`.
+//   Its template wraps the anchor inside a list-item:
+//     <template>
+//       <XListItem>
+//         <a ...attributes>{{yield}}</a>
+//       </XListItem>
+//     </template>
+//
+// Consumer:
+//   <ul>
+//     <XListLink>...</XListLink>
+//     <XListLink>...</XListLink>
+//   </ul>
+//
+// At runtime: <ul><li><a>…</a></li><li><a>…</a></li></ul> (legal).
+// Our static analysis: Glint says <XListLink>.element is
+// HTMLAnchorElement → 'a'. We substitute consumer's <XListLink> to
+// <a>, so html-validate sees <ul><a></a><a></a></ul> → fires
+// `element-permitted-content` on <a>-under-<ul>.
+//
+// What we'd need to FIX this:
+//   1) Walk the component's template, find the OUTERMOST native
+//      ancestor (here `<XListItem>` → recurse → `<li>`), use that as
+//      the substitution tag instead of the leaf Element type.
+//   2) OR detect when a leaf-style Element (a/button) is placed under
+//      a parent that requires a specific child (ul/ol → li, table →
+//      tr) and refuse the substitution.
+//
+// (1) needs recursive cross-file template walking. (2) is a heuristic
+// that may over- or under-suppress.
+//
+// Marked `.fails(...)` in `test/glint.test.ts` so when this resolution
+// improves, vitest signals "remove .fails — your fix worked".
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+
+interface ListItemSig {
+  Blocks: { default: [] };
+  Element: HTMLLIElement;
+}
+const ListItem: TemplateOnlyComponent<ListItemSig> = <template>
+  <li ...attributes>{{yield}}</li>
+</template>;
+
+interface ListLinkSig {
+  Blocks: { default: [] };
+  Element: HTMLAnchorElement;
+}
+const ListLink: TemplateOnlyComponent<ListLinkSig> = <template>
+  <ListItem>
+    <a href="#" ...attributes>{{yield}}</a>
+  </ListItem>
+</template>;
+
+<template>
+  <ul>
+    <ListLink>One</ListLink>
+    <ListLink>Two</ListLink>
+  </ul>
+</template>
diff --git a/test/glint-fixtures/transparent-li-wrapper-consumer.gts b/test/glint-fixtures/transparent-li-wrapper-consumer.gts
new file mode 100644
index 0000000..8868ce7
--- /dev/null
+++ b/test/glint-fixtures/transparent-li-wrapper-consumer.gts
@@ -0,0 +1,45 @@
+// Regression: a wrapper component that Glint resolves to 'transparent'
+// (Element: HTMLElement bare) sits inside `<ul>`. The wrapper's
+// `<template>` renders `<li>{{yield}}</li>` — that information is
+// statically available in the file's splatted-root, but Glint's
+// TS-only resolution (`Element: HTMLElement`) gives us nothing more
+// specific than 'transparent'.
+//
+// A child that resolves to `<div>` placed inside the wrapper inside
+// `<ul>` would, at runtime, become `<ul><li><div /></li></ul>` —
+// legal. Our static blanker, however, transparent-blanks the wrapper,
+// so `<div>` ends up directly under `<ul>` and
+// `element-permitted-content` FP-fires.
+//
+// Real-world repro: large component libraries shipping list-item
+// components declared as `Element: HTMLLIElement` but imported through
+// barrels often surface as 'transparent' in downstream consumers when
+// the type chain doesn't resolve cleanly across the barrel. Same FP
+// shape regardless of why Glint returned 'transparent'.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+
+interface TransparentWrapperSig {
+  Blocks: { default: [] };
+  Element: HTMLElement;  // bare generic → 'transparent' resolution
+}
+
+const TransparentWrapper: TemplateOnlyComponent<TransparentWrapperSig> =
+  <template>
+    <li class="x" ...attributes>{{yield}}</li>
+  </template>;
+
+interface ContentSig {
+  Element: HTMLDivElement;
+  Blocks: { default: [] };
+}
+const Content: TemplateOnlyComponent<ContentSig> = <template>
+  <div ...attributes>{{yield}}</div>
+</template>;
+
+<template>
+  <ul>
+    <TransparentWrapper>
+      <Content>placeholder</Content>
+    </TransparentWrapper>
+  </ul>
+</template>
diff --git a/test/glint.test.ts b/test/glint.test.ts
index 3b62bba..d289430 100644
--- a/test/glint.test.ts
+++ b/test/glint.test.ts
@@ -199,17 +199,23 @@ describe('Glint integration: cross-file .gts type resolution', () => {
     ).toBeUndefined();
   });
 
-  it('does NOT resolve `Element: HTMLElement` (the generic) to a phantom tag like <abbr>', () => {
-    // Surfaced by ecosystem CI on ember-power-select and HDS: a component
-    // declaring `Signature['Element'] = HTMLElement` (the bare generic) was
-    // resolving to <abbr> because lib.dom.d.ts's HTMLElementTagNameMap has
-    // `"abbr": HTMLElement` as its first entry mapping to bare HTMLElement.
-    // The inversion picked abbr; downstream rules then FP-fired
-    // element-permitted-content on legal content.
+  it('does NOT resolve `Element: HTMLElement` (the generic) to a phantom tag like <abbr>; falls back to the template root tag', () => {
+    // Surfaced by ecosystem CI: a component declaring `Signature['Element']
+    // = HTMLElement` (the bare generic) was resolving to <abbr> because
+    // lib.dom.d.ts's HTMLElementTagNameMap has `"abbr": HTMLElement` as
+    // its first entry mapping to bare HTMLElement. The inversion picked
+    // abbr; downstream rules then FP-fired element-permitted-content on
+    // legal content.
     //
-    // Correct behaviour: skip the inversion for generic HTMLElement so the
-    // component falls through to 'transparent' (children float to real
-    // parent), the same outcome as a component with no Element declared.
+    // Correct behaviour: skip the inversion for generic HTMLElement.
+    // PR #12 originally chose to fall through to 'transparent' so the
+    // children floated to the consumer-side parent. We now do better:
+    // the component's own `<template>` literally writes `<div>{{yield}}</div>`,
+    // so we read the splatted-root (or first-element) tag from the
+    // template AST and use that. Resolving to <div> is more accurate
+    // than 'transparent' and lets rules that depend on the parent
+    // context (`element-permitted-content`, etc.) validate the child
+    // against the real wrapper.
     const { filename, contents } = readFixture('generic-html-element-consumer.gts');
     const { componentTagMap } = extractAttrTypeMap(filename, contents)!;
     const entries = [...componentTagMap.entries()];
@@ -218,13 +224,71 @@ describe('Glint integration: cross-file .gts type resolution', () => {
       abbrEntry,
       `Element: HTMLElement (generic) must NOT resolve to 'abbr'; got: ${JSON.stringify(entries)}`,
     ).toBeUndefined();
-    // And it should resolve as 'transparent' explicitly — null would let
-    // blank.ts's built-in name-based fallback fire (e.g. `<Input>` → input
-    // even when Glint correctly resolved the user's component).
-    const transparentEntry = entries.find(([, tag]) => tag === 'transparent');
+    // Component's template root is `<div>` — that's what the runtime
+    // renders, so the resolution should reflect it.
+    const divEntry = entries.find(([, tag]) => tag === 'div');
     expect(
-      transparentEntry,
-      `expected componentTagMap to record the component as 'transparent'; got: ${JSON.stringify(entries)}`,
+      divEntry,
+      `expected componentTagMap to record the component as 'div' (template root); got: ${JSON.stringify(entries)}`,
+    ).toBeDefined();
+  });
+
+  it.fails(
+    'leaf-element-under-list-wrapper-consumer.gts: deeper wrapper-vs-leaf FP NOT yet handled',
+    () => {
+      // Documents a class of FPs the template-root fallback does NOT
+      // catch: a component declares `Element: HTMLAnchorElement` (or
+      // similar leaf-interactive type) but its template wraps the
+      // anchor inside a list-item wrapper:
+      //
+      //   <template>
+      //     <ListItem>
+      //       <a ...attributes>{{yield}}</a>
+      //     </ListItem>
+      //   </template>
+      //
+      // Glint resolves to the LEAF tag (`<a>`); our substitution
+      // places `<a>` directly under the consumer's `<ul>` and
+      // `element-permitted-content` FP-fires. The runtime DOM is
+      // `<ul><li><a></a></li></ul>` (legal).
+      //
+      // Fixing this needs recursive cross-file template walking to
+      // find the OUTERMOST native ancestor (`<li>`), or a heuristic
+      // that refuses leaf-style substitutions under structural-parent
+      // contexts (ul/ol → li, table → tr).
+      //
+      // Marked `.fails(...)` so when the fix lands, vitest signals
+      // "remove .fails — your fix worked".
+      const { filename, contents } = readFixture('leaf-element-under-list-wrapper-consumer.gts');
+      const { componentTagMap } = extractAttrTypeMap(filename, contents)!;
+      const entries = [...componentTagMap.entries()];
+      // Aspiration: ListLink resolves to 'li' (the outer wrapper) so
+      // children land legally under <ul>. Today: it resolves to 'a'.
+      const liResolution = entries.find(([k, tag]) => tag === 'li' && k.startsWith('20:'));
+      expect(liResolution).toBeDefined();
+    },
+  );
+
+  it('falls back to template-root tag when Glint says transparent and the template literally writes a native wrapper', () => {
+    // Mirrors a common pattern: a wrapper component declares
+    // `Element: HTMLElement` (bare generic — Glint surfaces this as
+    // `'transparent'`) but its `<template>` literally renders
+    // `<li ...attributes>{{yield}}</li>`. Without the template-root
+    // fallback, our blanker transparent-blanks the wrapper and any
+    // `<div>`-rendering child floats to whatever consumer-side
+    // ancestor exists (often `<ul>`), then `element-permitted-content`
+    // FP-fires.
+    //
+    // With the fallback, the wrapper resolves to `<li>` (its template
+    // root tag), the `<div>` child is correctly nested under `<li>`
+    // under `<ul>`, and the rule doesn't fire on legal markup.
+    const { filename, contents } = readFixture('transparent-li-wrapper-consumer.gts');
+    const { componentTagMap } = extractAttrTypeMap(filename, contents)!;
+    const entries = [...componentTagMap.entries()];
+    const liEntry = entries.find(([, tag]) => tag === 'li');
+    expect(
+      liEntry,
+      `expected the transparent-resolving wrapper to fall back to its template root <li>; got: ${JSON.stringify(entries)}`,
     ).toBeDefined();
   });
 

From 9d2848f1c5584270b2930511900f73d0f7441b53 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20R=C3=B8ed?= <johanroed@gmail.com>
Date: Fri, 8 May 2026 15:47:29 +0200
Subject: [PATCH 08/20] Recursive outer-wrapper resolver overrides
 leaf-interactive substitutions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When a component declares `Element: HTMLAnchorElement` (or any leaf-
interactive type), Glint's TS-only resolution gives us the LEAF tag
('a'). But if the component's `<template>` wraps that anchor inside
another wrapper:

  <template>
    <ListItem>
      <a ...attributes>{{yield}}</a>
    </ListItem>
  </template>

…then the OUTERMOST runtime element is whatever `<ListItem>` renders
(`<li>` in this case). A consumer placing this component under `<ul>`
gets `<ul><li><a></a></li></ul>` at runtime — legal — but our
substitution puts `<a>` directly under `<ul>` and
`element-permitted-content` FP-fires.

The new `lib/outer-wrapper-resolver.ts` walks the component's template
AST to find the OUTERMOST ElementNode. If native, returns its tag.
If PascalCase, resolves the local import (relative-path resolver in
the same module) and recurses. Cap depth + cycle detection.

`lib/glint.ts` calls it after Glint's resolveComponentElement and
overrides the resolved tag when the outer wrapper differs and is a
native tag. Single-substitution trade-off: the inner-content
semantics (`<button>`-under-`<a>`) are lost on the consumer's lint
pass for these wrappers; the addon's own template lint catches them
on its side. Outer-context FPs are the dominant pattern, so the
trade-off favors the wrapper.

Verified impact on real HDS files (within-package imports):
  app-footer/legal-links.gts:    5 → 0  element-permitted-content
  app-side-nav/list/index.gts:   clean

Limitation (still not handled): cross-package barrel imports — when
the consumer imports through `@hashicorp/.../components`, TypeScript's
symbol resolution doesn't always reach back to the source `.gts`
file (depends on the package's exports + declarations layout). My
local-import-only resolveComponentImport doesn't bridge package
boundaries either. That's a separate import-based fallback project.
---
 lib/glint.ts                                  |  26 ++
 lib/outer-wrapper-resolver.ts                 | 245 ++++++++++++++++++
 .../glint-fixtures/leaf-element-list-item.gts |  14 +
 .../glint-fixtures/leaf-element-list-link.gts |  20 ++
 ...af-element-under-list-wrapper-consumer.gts |  66 +----
 test/glint.test.ts                            |  60 ++---
 6 files changed, 340 insertions(+), 91 deletions(-)
 create mode 100644 lib/outer-wrapper-resolver.ts
 create mode 100644 test/glint-fixtures/leaf-element-list-item.gts
 create mode 100644 test/glint-fixtures/leaf-element-list-link.gts

diff --git a/lib/glint.ts b/lib/glint.ts
index 2ea9a8d..c281173 100644
--- a/lib/glint.ts
+++ b/lib/glint.ts
@@ -15,6 +15,7 @@ import type * as TS from 'typescript';
 
 import { isNativeTag } from '../blank.js';
 import { getSplattedRootsForFile, extractSplattedRootFromTemplate } from './component-attrs.js';
+import { resolveOuterWrapperTag } from './outer-wrapper-resolver.js';
 import type { ComponentAttrs } from './builtin-components.js';
 import { readCache, writeCache } from './cache.js';
 import type { AttrTypeInfo, ExtractionResult } from './cache.js';
@@ -1004,6 +1005,31 @@ export function extractAttrTypeMap(filename: string, contents: string): Extracti
                 componentTagMap.set(key, first.tag);
               }
             }
+            // Outer-wrapper override: when the component's template
+            // wraps the splatted leaf in an OUTER native ancestor
+            // (e.g. `<ListItem><a ...attributes>{{yield}}</a></ListItem>`
+            // where ListItem renders `<li>`), Glint resolves the
+            // consumer-side substitution to the LEAF type (`<a>`).
+            // That fires `element-permitted-content` when the consumer
+            // places the component under a structurally-restrictive
+            // parent (`<ul>`, `<ol>`, etc.) even though the runtime
+            // DOM is `<ul><li><a>…</a></li></ul>` (legal). Walk the
+            // component's template AST to find the OUTERMOST native
+            // ancestor (recursing through PascalCase wrappers via local
+            // imports), and prefer that tag when it differs from the
+            // leaf-resolved tag. Single-substitution trade-off: the
+            // inner-content semantics (e.g. `<button>`-under-`<a>`)
+            // are lost on the consumer-side lint pass; the addon's
+            // own template lint catches them on its side.
+            const outerWrapper = resolveOuterWrapperTag(gtsPath);
+            const currentResolved = componentTagMap.get(key);
+            if (
+              outerWrapper !== null &&
+              outerWrapper !== currentResolved &&
+              isNativeTag(outerWrapper)
+            ) {
+              componentTagMap.set(key, outerWrapper);
+            }
           }
         }
         // Classic Ember addon fallback: when the JS-driven resolution
diff --git a/lib/outer-wrapper-resolver.ts b/lib/outer-wrapper-resolver.ts
new file mode 100644
index 0000000..16970da
--- /dev/null
+++ b/lib/outer-wrapper-resolver.ts
@@ -0,0 +1,245 @@
+// Outer-wrapper resolver: finds the OUTERMOST native HTML tag wrapping
+// a component's content, by walking the component's `<template>` block
+// and recursively resolving any non-native top-level wrapper.
+//
+// Why: a component declares `Element: HTMLAnchorElement` (Glint reads
+// this as the leaf interactive type → 'a'), but its template wraps
+// the anchor in a list-item:
+//
+//   <template>
+//     <ListItem>
+//       <a ...attributes>{{yield}}</a>
+//     </ListItem>
+//   </template>
+//
+// At runtime the outermost element is `<li>` (via ListItem's own
+// template). When a consumer places this component under `<ul>`, the
+// runtime DOM is `<ul><li><a>…</a></li></ul>` — legal. But our
+// substitution puts `<a>` directly under `<ul>` and
+// `element-permitted-content` FP-fires.
+//
+// This module walks `<ListItem>`'s template, finds it has root `<li>`,
+// recurses no further, and returns 'li'. The caller (lib/glint.ts)
+// uses this to override leaf-interactive substitutions when an outer
+// wrapper exists.
+//
+// Single-substitution trade-off: by preferring the outer wrapper we
+// lose the inner-content semantics for these wrappers (e.g. a
+// `<button>nested</button>` placed inside `<MyLink>` whose template
+// wraps `<a>` in `<div>` won't fire `element-permitted-content` on
+// `<button>`-under-`<a>` from the consumer's lint pass). The
+// component's own template lints catch that on the addon side. The
+// consumer-side parent-context FPs are the dominant pattern, so the
+// trade-off favors outer.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { Preprocessor } from 'content-tag';
+import { preprocess, traverse } from '@glimmer/syntax';
+import type { AST } from '@glimmer/syntax';
+
+import { isNativeTag } from '../blank.js';
+
+const preprocessor = new Preprocessor();
+
+// Cache resolved outer-wrappers per absolute filename. Process-
+// lifetime; cleared via `_clearOuterWrapperCache` for tests.
+const cache = new Map<string, string | null>();
+
+// Cap recursion depth — components in the wild are unlikely to nest
+// wrappers more than a few levels, and a higher cap risks pathological
+// performance on cycles or accidental fan-out.
+const MAX_DEPTH = 8;
+
+// Find the topmost ElementNode in a template — the OUTERMOST wrapper.
+// Returns null if the template has no element children (e.g. just
+// `{{yield}}` or text).
+function findOutermostElement(ast: AST.Template): AST.ElementNode | null {
+  let outermost: AST.ElementNode | null = null;
+  // We want the FIRST top-level element only, not nested children.
+  // `traverse`'s `ElementNode.enter` would visit every descendant;
+  // bail after the first hit at depth 0.
+  let foundAtDepth0 = false;
+  traverse(ast, {
+    ElementNode: {
+      enter(node) {
+        if (foundAtDepth0) return;
+        outermost = node;
+        foundAtDepth0 = true;
+      },
+    },
+  });
+  return outermost;
+}
+
+// Resolve a PascalCase component name in `consumerFile`'s source to
+// the absolute path of its `.gts/.gjs` source. Walks the imports in
+// the file's text (regex-based — we don't pull in a full TS parser).
+//
+// Returns null when:
+//   - The import doesn't exist in the file.
+//   - The import's path doesn't resolve to a readable file.
+//   - The resolved file isn't a `.gts/.gjs` (we don't recurse into
+//     `.ts` re-exports here — that's harder, not done in this pass).
+function resolveComponentImport(consumerFile: string, componentName: string): string | null {
+  let contents: string;
+  try {
+    contents = fs.readFileSync(consumerFile, 'utf8');
+  } catch {
+    return null;
+  }
+  // Match patterns:
+  //   import X from '...';
+  //   import X, { ... } from '...';
+  //   import { X } from '...';
+  //   import { X as Y } from '...';
+  //   import { Y as X } from '...';
+  // We escape the component name for the regex.
+  const escName = componentName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  // Default-import pattern.
+  const defaultRe = new RegExp(
+    `import\\s+${escName}(?:\\s*,\\s*\\{[^}]*\\})?\\s+from\\s+['"]([^'"]+)['"]`,
+    'm',
+  );
+  const defaultMatch = defaultRe.exec(contents);
+  if (defaultMatch) {
+    return resolveImportPath(consumerFile, defaultMatch[1]!);
+  }
+  // Named-import pattern, possibly aliased: { X } / { X as Y } / { Y as X }.
+  const namedRe = new RegExp(
+    `import\\s+(?:\\{[^}]*\\}|[A-Za-z_$][\\w$]*\\s*,\\s*\\{[^}]*\\})\\s+from\\s+['"]([^'"]+)['"]`,
+    'g',
+  );
+  let namedMatch: RegExpExecArray | null;
+  while ((namedMatch = namedRe.exec(contents)) !== null) {
+    const fullStmt = namedMatch[0];
+    // Extract the destructured names; check if `componentName` is in there
+    // (either directly, as `... as componentName`, or as `componentName as ...`
+    // where we want the LOCAL name to match — that's `componentName as ...`).
+    const bracesMatch = /\{([^}]*)\}/.exec(fullStmt);
+    if (!bracesMatch) continue;
+    const names = bracesMatch[1]!.split(',').map((s) => s.trim());
+    const matches = names.some((entry) => {
+      // `Foo as Bar` — local name is Bar.
+      const aliasMatch = /^([\w$]+)\s+as\s+([\w$]+)$/.exec(entry);
+      if (aliasMatch) return aliasMatch[2] === componentName;
+      return entry === componentName;
+    });
+    if (matches) {
+      return resolveImportPath(consumerFile, namedMatch[1]!);
+    }
+  }
+  return null;
+}
+
+// Resolve a relative import path to an absolute `.gts/.gjs` file.
+// Doesn't follow package imports (those go through node_modules and
+// are typically barrels we can't statically traverse without TS).
+function resolveImportPath(fromFile: string, importSpec: string): string | null {
+  if (!importSpec.startsWith('.')) return null;
+  const fromDir = path.dirname(fromFile);
+  // Try the literal path first (in case it ends in .gts/.gjs).
+  const literal = path.resolve(fromDir, importSpec);
+  if (literal.endsWith('.gts') || literal.endsWith('.gjs')) {
+    if (fs.existsSync(literal)) return literal;
+  }
+  // Try appending each extension.
+  for (const ext of ['.gts', '.gjs']) {
+    const candidate = literal + ext;
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  // Try as a directory with an index file.
+  for (const ext of ['.gts', '.gjs']) {
+    const candidate = path.join(literal, 'index' + ext);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+// Resolve the outermost native wrapper tag for the component declared
+// in `filename`'s first `<template>` block. Recurses through nested
+// PascalCase wrappers via local imports.
+//
+// Returns:
+//   - tag name (e.g. 'li', 'div')  if a native wrapper is found.
+//   - null                          if no native wrapper exists in the
+//                                   template chain (e.g. all wrappers
+//                                   are unresolvable PascalCase, or
+//                                   template has no element root).
+//
+// Single-template-block assumption: most component files have one
+// `<template>` block; multi-template files (helper exports + default)
+// would need declaration-to-template matching. The first block is a
+// reasonable default for the common case.
+export function resolveOuterWrapperTag(filename: string): string | null {
+  return resolveOuterWrapperTagInner(filename, new Set(), 0);
+}
+
+function resolveOuterWrapperTagInner(
+  filename: string,
+  visited: Set<string>,
+  depth: number,
+): string | null {
+  if (depth > MAX_DEPTH) return null;
+  if (visited.has(filename)) return null; // cycle guard
+  const cached = cache.get(filename);
+  if (cached !== undefined && depth === 0) return cached;
+  visited.add(filename);
+
+  let contents: string;
+  try {
+    contents = fs.readFileSync(filename, 'utf8');
+  } catch {
+    if (depth === 0) cache.set(filename, null);
+    return null;
+  }
+
+  let blocks: ReturnType<Preprocessor['parse']>;
+  try {
+    blocks = preprocessor.parse(contents, { filename });
+  } catch {
+    if (depth === 0) cache.set(filename, null);
+    return null;
+  }
+
+  for (const block of blocks) {
+    if (block.tagName !== 'template') continue;
+    let ast: AST.Template;
+    try {
+      ast = preprocess(block.contents);
+    } catch {
+      continue;
+    }
+    const outermost = findOutermostElement(ast);
+    if (!outermost) continue;
+
+    if (isNativeTag(outermost.tag)) {
+      if (depth === 0) cache.set(filename, outermost.tag);
+      return outermost.tag;
+    }
+
+    // Skip dotted invocations (`<This.Foo>`, `<F.Options>`) — those
+    // are curried sub-components or instance refs, not statically
+    // resolvable via local imports. Treat as unresolvable wrapper.
+    if (outermost.tag.includes('.')) continue;
+    // Skip named-block syntax (`<:slot>`).
+    if (outermost.tag.startsWith(':')) continue;
+
+    // PascalCase wrapper — try to resolve via local import.
+    const importPath = resolveComponentImport(filename, outermost.tag);
+    if (!importPath) continue;
+    const recursed = resolveOuterWrapperTagInner(importPath, visited, depth + 1);
+    if (recursed !== null) {
+      if (depth === 0) cache.set(filename, recursed);
+      return recursed;
+    }
+  }
+
+  if (depth === 0) cache.set(filename, null);
+  return null;
+}
+
+// Test-only.
+export function _clearOuterWrapperCache(): void {
+  cache.clear();
+}
diff --git a/test/glint-fixtures/leaf-element-list-item.gts b/test/glint-fixtures/leaf-element-list-item.gts
new file mode 100644
index 0000000..206d508
--- /dev/null
+++ b/test/glint-fixtures/leaf-element-list-item.gts
@@ -0,0 +1,14 @@
+// `<ListItem>` — outermost native is `<li>`. Used by
+// `<ListLink>` to wrap its anchor.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+
+interface ListItemSig {
+  Blocks: { default: [] };
+  Element: HTMLLIElement;
+}
+
+const ListItem: TemplateOnlyComponent<ListItemSig> = <template>
+  <li ...attributes>{{yield}}</li>
+</template>;
+
+export default ListItem;
diff --git a/test/glint-fixtures/leaf-element-list-link.gts b/test/glint-fixtures/leaf-element-list-link.gts
new file mode 100644
index 0000000..f6ddd70
--- /dev/null
+++ b/test/glint-fixtures/leaf-element-list-link.gts
@@ -0,0 +1,20 @@
+// `<ListLink>` declares `Element: HTMLAnchorElement` (the leaf
+// interactive type Glint reads). Its template wraps the `<a>` in
+// `<ListItem>` (which renders `<li>`). At runtime the outermost
+// element is `<li>`, but Glint's leaf-type resolution sees only
+// `<a>`.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import ListItem from './leaf-element-list-item.gts';
+
+interface ListLinkSig {
+  Blocks: { default: [] };
+  Element: HTMLAnchorElement;
+}
+
+const ListLink: TemplateOnlyComponent<ListLinkSig> = <template>
+  <ListItem>
+    <a href="#" ...attributes>{{yield}}</a>
+  </ListItem>
+</template>;
+
+export default ListLink;
diff --git a/test/glint-fixtures/leaf-element-under-list-wrapper-consumer.gts b/test/glint-fixtures/leaf-element-under-list-wrapper-consumer.gts
index 9bbda16..ecea506 100644
--- a/test/glint-fixtures/leaf-element-under-list-wrapper-consumer.gts
+++ b/test/glint-fixtures/leaf-element-under-list-wrapper-consumer.gts
@@ -1,60 +1,14 @@
-// Documents a deeper wrapper-vs-leaf FP class my template-root
-// fallback does NOT solve.
+// Consumer for the leaf-vs-wrapper FP fixture. Imports `<ListLink>`
+// from a separate file (mirroring real-world cross-file usage).
 //
-// Pattern (real-world: design-system list-link components):
-//
-//   `<XListLink>` declares `Element: HTMLAnchorElement`.
-//   Its template wraps the anchor inside a list-item:
-//     <template>
-//       <XListItem>
-//         <a ...attributes>{{yield}}</a>
-//       </XListItem>
-//     </template>
-//
-// Consumer:
-//   <ul>
-//     <XListLink>...</XListLink>
-//     <XListLink>...</XListLink>
-//   </ul>
-//
-// At runtime: <ul><li><a>…</a></li><li><a>…</a></li></ul> (legal).
-// Our static analysis: Glint says <XListLink>.element is
-// HTMLAnchorElement → 'a'. We substitute consumer's <XListLink> to
-// <a>, so html-validate sees <ul><a></a><a></a></ul> → fires
-// `element-permitted-content` on <a>-under-<ul>.
-//
-// What we'd need to FIX this:
-//   1) Walk the component's template, find the OUTERMOST native
-//      ancestor (here `<XListItem>` → recurse → `<li>`), use that as
-//      the substitution tag instead of the leaf Element type.
-//   2) OR detect when a leaf-style Element (a/button) is placed under
-//      a parent that requires a specific child (ul/ol → li, table →
-//      tr) and refuse the substitution.
-//
-// (1) needs recursive cross-file template walking. (2) is a heuristic
-// that may over- or under-suppress.
-//
-// Marked `.fails(...)` in `test/glint.test.ts` so when this resolution
-// improves, vitest signals "remove .fails — your fix worked".
-import type { TemplateOnlyComponent } from '@ember/component/template-only';
-
-interface ListItemSig {
-  Blocks: { default: [] };
-  Element: HTMLLIElement;
-}
-const ListItem: TemplateOnlyComponent<ListItemSig> = <template>
-  <li ...attributes>{{yield}}</li>
-</template>;
-
-interface ListLinkSig {
-  Blocks: { default: [] };
-  Element: HTMLAnchorElement;
-}
-const ListLink: TemplateOnlyComponent<ListLinkSig> = <template>
-  <ListItem>
-    <a href="#" ...attributes>{{yield}}</a>
-  </ListItem>
-</template>;
+// Pattern: `<ListLink>` declares `Element: HTMLAnchorElement`. Its
+// template wraps the `<a>` inside `<ListItem>` (which renders `<li>`).
+// At runtime the consumer's `<ul>` contains `<li><a>...</a></li>` —
+// legal. Glint's leaf-type resolution gives us `<a>`; the outer-
+// wrapper resolver should walk the template chain (ListLink →
+// ListItem → `<li>`) and prefer `<li>` for the consumer's
+// substitution.
+import ListLink from './leaf-element-list-link.gts';
 
 <template>
   <ul>
diff --git a/test/glint.test.ts b/test/glint.test.ts
index d289430..e270fc0 100644
--- a/test/glint.test.ts
+++ b/test/glint.test.ts
@@ -233,41 +233,31 @@ describe('Glint integration: cross-file .gts type resolution', () => {
     ).toBeDefined();
   });
 
-  it.fails(
-    'leaf-element-under-list-wrapper-consumer.gts: deeper wrapper-vs-leaf FP NOT yet handled',
-    () => {
-      // Documents a class of FPs the template-root fallback does NOT
-      // catch: a component declares `Element: HTMLAnchorElement` (or
-      // similar leaf-interactive type) but its template wraps the
-      // anchor inside a list-item wrapper:
-      //
-      //   <template>
-      //     <ListItem>
-      //       <a ...attributes>{{yield}}</a>
-      //     </ListItem>
-      //   </template>
-      //
-      // Glint resolves to the LEAF tag (`<a>`); our substitution
-      // places `<a>` directly under the consumer's `<ul>` and
-      // `element-permitted-content` FP-fires. The runtime DOM is
-      // `<ul><li><a></a></li></ul>` (legal).
-      //
-      // Fixing this needs recursive cross-file template walking to
-      // find the OUTERMOST native ancestor (`<li>`), or a heuristic
-      // that refuses leaf-style substitutions under structural-parent
-      // contexts (ul/ol → li, table → tr).
-      //
-      // Marked `.fails(...)` so when the fix lands, vitest signals
-      // "remove .fails — your fix worked".
-      const { filename, contents } = readFixture('leaf-element-under-list-wrapper-consumer.gts');
-      const { componentTagMap } = extractAttrTypeMap(filename, contents)!;
-      const entries = [...componentTagMap.entries()];
-      // Aspiration: ListLink resolves to 'li' (the outer wrapper) so
-      // children land legally under <ul>. Today: it resolves to 'a'.
-      const liResolution = entries.find(([k, tag]) => tag === 'li' && k.startsWith('20:'));
-      expect(liResolution).toBeDefined();
-    },
-  );
+  it('leaf-element-under-list-wrapper-consumer.gts: outer-wrapper resolver overrides leaf-interactive resolution', () => {
+    // A component declares `Element: HTMLAnchorElement` (Glint reads
+    // the leaf interactive type → 'a'), but its template wraps the
+    // `<a>` inside `<ListItem>` (which renders `<li>`):
+    //
+    //   <template>
+    //     <ListItem>
+    //       <a ...attributes>{{yield}}</a>
+    //     </ListItem>
+    //   </template>
+    //
+    // At runtime the outermost element is `<li>`. The outer-wrapper
+    // resolver walks the template chain (ListLink → ListItem → `<li>`)
+    // and overrides Glint's leaf-resolved `<a>` with `<li>`. Lets a
+    // consumer place this under `<ul>` without `element-permitted-
+    // content` FP-firing on `<a>`-under-`<ul>`.
+    const { filename, contents } = readFixture('leaf-element-under-list-wrapper-consumer.gts');
+    const { componentTagMap } = extractAttrTypeMap(filename, contents)!;
+    const entries = [...componentTagMap.entries()];
+    const liEntries = entries.filter(([, tag]) => tag === 'li');
+    expect(
+      liEntries.length,
+      `expected at least one ListLink invocation to resolve to 'li' (outer wrapper); got: ${JSON.stringify(entries)}`,
+    ).toBeGreaterThan(0);
+  });
 
   it('falls back to template-root tag when Glint says transparent and the template literally writes a native wrapper', () => {
     // Mirrors a common pattern: a wrapper component declares

From 3dbff07863f8daf8c71309fe72e59e984af1c104 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20R=C3=B8ed?= <johanroed@gmail.com>
Date: Fri, 8 May 2026 16:12:49 +0200
Subject: [PATCH 09/20] Import-based outer-wrapper fallback for cross-package
 barrels
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When a consumer imports a component through a cross-package barrel
re-export (`import { X } from '@scope/pkg/barrel'`), Glint's TS symbol
resolution often doesn't reach back to the source `.gts` file through
the package's compiled declarations / pnpm-linked layout. The same-
package outer-wrapper override (commit 9d2848f) sits inside the
declFile-based code path and never gets a chance to run for those
imports.

The new import-based fallback bypasses TS:
  1. Look up the consumer's `import` statement for the component name
     (regex on the file's source — both default and named imports,
     handling `as`-aliasing in either direction).
  2. Resolve the import path:
     - Relative imports: walk filesystem from the consumer's dir.
     - Package imports: walk node_modules upward, prefer `src/<sub>`
       source files over compiled `dist/`, fall back to common
       package shapes if `src/` isn't shipped.
  3. If the resolved file is a `.ts` barrel, parse it for
     `export { default as X } from '...'` (or named re-exports) and
     follow the re-exported path.
  4. Walk the resulting `.gts/.gjs` template AST chain to find the
     outermost native ancestor (recursing through nested PascalCase
     wrappers via local imports).

The fallback runs only when the same-package override didn't get a
chance (tracked via `sameTransitivePackageOuterRan` flag set inside
the declFile branch). Override condition is the same: outer wrapper
differs from current resolution AND is a native tag.

Earlier draft gated the fallback on a hardcoded `LEAF_INTERACTIVE_TAGS`
set; dropped that — the override-only-when-different condition is
already principled, and the `sameTransitivePackageOuterRan` flag
keeps the fallback from running redundantly for cases the same-
package path already handled.

Verified impact on real HDS files (after building HDS so the
package's `src/` is reachable through the linked node_modules):
  showcase/.../base-elements.gts:        51 → 0 element-permitted-content
  app-side-nav/.../with-generic-content.gts: clean
  30-file sample across HDS components:  2 e-p-c remaining

New regression test (`cross-package-barrel-consumer.gts`) exercises
the full chain: barrel re-export → recursive template walk →
outer-wrapper override.
---
 lib/glint.ts                                  |  44 +++-
 lib/outer-wrapper-resolver.ts                 | 203 ++++++++++++++++--
 .../cross-package-barrel-consumer.gts         |  18 ++
 .../node_modules/list-link-addon/package.json |  10 +
 .../list-link-addon/src/components.ts         |   6 +
 .../src/components/list-item.gts              |   6 +
 .../src/components/list-link.gts              |   9 +
 test/glint.test.ts                            |  25 +++
 8 files changed, 306 insertions(+), 15 deletions(-)
 create mode 100644 test/glint-fixtures/cross-package-barrel-consumer.gts
 create mode 100644 test/glint-fixtures/node_modules/list-link-addon/package.json
 create mode 100644 test/glint-fixtures/node_modules/list-link-addon/src/components.ts
 create mode 100644 test/glint-fixtures/node_modules/list-link-addon/src/components/list-item.gts
 create mode 100644 test/glint-fixtures/node_modules/list-link-addon/src/components/list-link.gts

diff --git a/lib/glint.ts b/lib/glint.ts
index c281173..deddce5 100644
--- a/lib/glint.ts
+++ b/lib/glint.ts
@@ -15,7 +15,10 @@ import type * as TS from 'typescript';
 
 import { isNativeTag } from '../blank.js';
 import { getSplattedRootsForFile, extractSplattedRootFromTemplate } from './component-attrs.js';
-import { resolveOuterWrapperTag } from './outer-wrapper-resolver.js';
+import {
+  resolveOuterWrapperTag,
+  resolveOuterWrapperFromConsumerImport,
+} from './outer-wrapper-resolver.js';
 import type { ComponentAttrs } from './builtin-components.js';
 import { readCache, writeCache } from './cache.js';
 import type { AttrTypeInfo, ExtractionResult } from './cache.js';
@@ -972,6 +975,11 @@ export function extractAttrTypeMap(filename: string, contents: string): Extracti
       const tag = emitCall ? resolveComponentElement(ts, checker, emitCall, elementTypeToTag) : null;
       const elementLoc = node.parent.sourceNode.loc.start;
       const key = locKey(elementLoc.line, elementLoc.column);
+      // Tracks whether the same-package outer-wrapper override path
+      // ran for this invocation. When false, the import-based fallback
+      // (which doesn't depend on Glint's symbol resolution) takes
+      // over below.
+      let sameTransitivePackageOuterRan = false;
       if (tag) {
         componentTagMap.set(key, tag);
       }
@@ -1023,6 +1031,7 @@ export function extractAttrTypeMap(filename: string, contents: string): Extracti
             // own template lint catches them on its side.
             const outerWrapper = resolveOuterWrapperTag(gtsPath);
             const currentResolved = componentTagMap.get(key);
+            sameTransitivePackageOuterRan = true;
             if (
               outerWrapper !== null &&
               outerWrapper !== currentResolved &&
@@ -1047,6 +1056,39 @@ export function extractAttrTypeMap(filename: string, contents: string): Extracti
           }
         }
       }
+      // Import-based outer-wrapper fallback: when Glint's TS symbol
+      // resolution failed to give us a `.gts` source (typically
+      // because the component is imported through a cross-package
+      // barrel and TS can't trace the symbol back to its origin
+      // through the package's exports/declarations), try the
+      // consumer-side AST: look up the `import` statement for this
+      // component name, resolve the import path (relative or
+      // package-style), follow barrel re-exports, and walk the
+      // resulting `.gts` template chain. Same single-substitution
+      // trade-off as the same-package outer-wrapper override.
+      // Import-based outer-wrapper fallback. Runs only when the same-
+      // package outer-wrapper override (inside `if (declFile)` /
+      // `if (gtsPath)` above) did NOT get a chance — typically because
+      // Glint's TS symbol resolution couldn't reach the component's
+      // source through a cross-package barrel re-export. In that case
+      // we bypass TS by parsing the consumer file's `import` statement
+      // for `componentName`, resolving the path (relative or
+      // package-style), following barrel re-exports, and walking the
+      // resulting `<template>` chain to find the outermost native
+      // wrapper. Same single-substitution trade-off as the same-
+      // package override.
+      if (!sameTransitivePackageOuterRan) {
+        const componentName = node.parent.sourceNode.tag;
+        const outerFromImport = resolveOuterWrapperFromConsumerImport(filename, componentName);
+        const currentResolved = componentTagMap.get(key);
+        if (
+          outerFromImport !== null &&
+          outerFromImport !== currentResolved &&
+          isNativeTag(outerFromImport)
+        ) {
+          componentTagMap.set(key, outerFromImport);
+        }
+      }
     }
 
     for (const child of node.children ?? []) {
diff --git a/lib/outer-wrapper-resolver.ts b/lib/outer-wrapper-resolver.ts
index 16970da..56c0523 100644
--- a/lib/outer-wrapper-resolver.ts
+++ b/lib/outer-wrapper-resolver.ts
@@ -76,11 +76,17 @@ function findOutermostElement(ast: AST.Template): AST.ElementNode | null {
 // the absolute path of its `.gts/.gjs` source. Walks the imports in
 // the file's text (regex-based — we don't pull in a full TS parser).
 //
+// Two import shapes are handled:
+//   1. Relative import (`./foo.gts`) — resolve directly.
+//   2. Package import (`@scope/pkg/components`) — resolve via
+//      `node_modules` walk + package.json `exports`, then if the
+//      resolved file is a barrel `.ts`, parse it for the re-export of
+//      `componentName` and follow that.
+//
 // Returns null when:
 //   - The import doesn't exist in the file.
 //   - The import's path doesn't resolve to a readable file.
-//   - The resolved file isn't a `.gts/.gjs` (we don't recurse into
-//     `.ts` re-exports here — that's harder, not done in this pass).
+//   - The resolved file isn't a `.gts/.gjs` (after barrel-following).
 function resolveComponentImport(consumerFile: string, componentName: string): string | null {
   let contents: string;
   try {
@@ -94,7 +100,6 @@ function resolveComponentImport(consumerFile: string, componentName: string): st
   //   import { X } from '...';
   //   import { X as Y } from '...';
   //   import { Y as X } from '...';
-  // We escape the component name for the regex.
   const escName = componentName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
   // Default-import pattern.
   const defaultRe = new RegExp(
@@ -103,7 +108,7 @@ function resolveComponentImport(consumerFile: string, componentName: string): st
   );
   const defaultMatch = defaultRe.exec(contents);
   if (defaultMatch) {
-    return resolveImportPath(consumerFile, defaultMatch[1]!);
+    return resolveAnyImport(consumerFile, defaultMatch[1]!, componentName, /* defaultExport */ true);
   }
   // Named-import pattern, possibly aliased: { X } / { X as Y } / { Y as X }.
   const namedRe = new RegExp(
@@ -113,25 +118,175 @@ function resolveComponentImport(consumerFile: string, componentName: string): st
   let namedMatch: RegExpExecArray | null;
   while ((namedMatch = namedRe.exec(contents)) !== null) {
     const fullStmt = namedMatch[0];
-    // Extract the destructured names; check if `componentName` is in there
-    // (either directly, as `... as componentName`, or as `componentName as ...`
-    // where we want the LOCAL name to match — that's `componentName as ...`).
     const bracesMatch = /\{([^}]*)\}/.exec(fullStmt);
     if (!bracesMatch) continue;
     const names = bracesMatch[1]!.split(',').map((s) => s.trim());
-    const matches = names.some((entry) => {
-      // `Foo as Bar` — local name is Bar.
+    // For named imports, find the EXPORT name corresponding to the
+    // local name `componentName`. `Foo as Bar` means: external export
+    // `Foo`, local name `Bar`. If the consumer wrote `<Bar>`, we
+    // follow the export `Foo` from the imported module.
+    let exportName: string | null = null;
+    for (const entry of names) {
       const aliasMatch = /^([\w$]+)\s+as\s+([\w$]+)$/.exec(entry);
-      if (aliasMatch) return aliasMatch[2] === componentName;
-      return entry === componentName;
-    });
-    if (matches) {
-      return resolveImportPath(consumerFile, namedMatch[1]!);
+      if (aliasMatch) {
+        if (aliasMatch[2] === componentName) {
+          exportName = aliasMatch[1]!;
+          break;
+        }
+      } else if (entry === componentName) {
+        exportName = componentName;
+        break;
+      }
+    }
+    if (exportName !== null) {
+      return resolveAnyImport(consumerFile, namedMatch[1]!, exportName, false);
     }
   }
   return null;
 }
 
+// Resolve an import (relative or package-style) to an absolute
+// `.gts/.gjs` file, following barrel re-exports if the import lands
+// on a `.ts` barrel.
+//
+// `exportName` is the name we're looking for IN THE IMPORTED MODULE
+// (the export name, not the consumer's local alias).
+// `defaultExport`: when true, we look for `default` re-export in
+// barrels (typical for `import X from 'pkg/barrel'`).
+function resolveAnyImport(
+  fromFile: string,
+  importSpec: string,
+  exportName: string,
+  defaultExport: boolean,
+): string | null {
+  let resolved: string | null;
+  if (importSpec.startsWith('.')) {
+    resolved = resolveImportPath(fromFile, importSpec);
+  } else {
+    resolved = resolvePackageImport(fromFile, importSpec);
+  }
+  if (resolved === null) return null;
+  // If we landed on a `.gts/.gjs`, we're done — that's the source.
+  if (resolved.endsWith('.gts') || resolved.endsWith('.gjs')) {
+    return resolved;
+  }
+  // If we landed on a `.ts` (typically a barrel), parse for the
+  // re-export of `exportName` and follow it.
+  if (resolved.endsWith('.ts') && !resolved.endsWith('.d.ts')) {
+    return followBarrelReExport(resolved, exportName, defaultExport);
+  }
+  return null;
+}
+
+// Resolve a package-style import (`@scope/pkg/sub` or `pkg/sub`) to
+// an absolute file path, walking `node_modules` upward from `fromFile`
+// and consulting package.json `exports` / `main`.
+//
+// Strategy: prefer SOURCE files (`src/<sub>.ts/.gts`) over compiled
+// dist (`dist/<sub>.js`), so we can read the original `<template>`
+// blocks. If `src/` doesn't exist, fall through to the package's
+// declared exports.
+function resolvePackageImport(fromFile: string, importSpec: string): string | null {
+  // Split into `<package-name>` and `<sub-path>` (e.g.
+  // `@scope/pkg/foo/bar` → `@scope/pkg`, `foo/bar`;
+  // `pkg/foo` → `pkg`, `foo`; bare `pkg` → `pkg`, '').
+  let pkgName: string;
+  let subPath: string;
+  if (importSpec.startsWith('@')) {
+    const slashIdx = importSpec.indexOf('/');
+    if (slashIdx < 0) return null;
+    const secondSlash = importSpec.indexOf('/', slashIdx + 1);
+    if (secondSlash < 0) {
+      pkgName = importSpec;
+      subPath = '';
+    } else {
+      pkgName = importSpec.slice(0, secondSlash);
+      subPath = importSpec.slice(secondSlash + 1);
+    }
+  } else {
+    const slashIdx = importSpec.indexOf('/');
+    if (slashIdx < 0) {
+      pkgName = importSpec;
+      subPath = '';
+    } else {
+      pkgName = importSpec.slice(0, slashIdx);
+      subPath = importSpec.slice(slashIdx + 1);
+    }
+  }
+  // Walk up looking for node_modules/<pkgName>.
+  let dir = path.dirname(fromFile);
+  while (true) {
+    const pkgRoot = path.join(dir, 'node_modules', pkgName);
+    if (fs.existsSync(pkgRoot)) {
+      // Try SOURCE first: src/<sub>.{ts,gts,gjs} or src/<sub>/index.*
+      if (subPath) {
+        for (const ext of ['.gts', '.gjs', '.ts']) {
+          const candidate = path.join(pkgRoot, 'src', subPath + ext);
+          if (fs.existsSync(candidate)) return candidate;
+        }
+        for (const ext of ['.gts', '.gjs', '.ts']) {
+          const candidate = path.join(pkgRoot, 'src', subPath, 'index' + ext);
+          if (fs.existsSync(candidate)) return candidate;
+        }
+      } else {
+        for (const ext of ['.gts', '.gjs', '.ts']) {
+          const candidate = path.join(pkgRoot, 'src', 'index' + ext);
+          if (fs.existsSync(candidate)) return candidate;
+        }
+      }
+      // Fall back to whatever the package's exports/main points to.
+      // We don't fully resolve `exports` patterns — just probe a few
+      // common shapes.
+      if (subPath) {
+        for (const sub of [`${subPath}.ts`, `${subPath}.gts`, `${subPath}/index.ts`]) {
+          const candidate = path.join(pkgRoot, sub);
+          if (fs.existsSync(candidate)) return candidate;
+        }
+      }
+      return null;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+// Parse a `.ts` barrel for `export { default as <exportName> } from '...'`
+// or `export { <exportName> } from '...'` and follow the path.
+//
+// We use simple regex extraction; the barrel files we care about are
+// generated re-export files, so the syntax is regular.
+function followBarrelReExport(
+  barrelFile: string,
+  exportName: string,
+  defaultExport: boolean,
+): string | null {
+  let contents: string;
+  try {
+    contents = fs.readFileSync(barrelFile, 'utf8');
+  } catch {
+    return null;
+  }
+  const escName = exportName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  // `export { default as <exportName> } from '<path>';` (when defaultExport=true,
+  // also matches `export { default as <exportName>, ... } from '<path>';`).
+  // For named exports (defaultExport=false), match `export { <exportName>` or
+  // `export { ..., <exportName>` — the export name appears verbatim.
+  const exportRe = defaultExport
+    ? new RegExp(
+        `export\\s+\\{[^}]*\\bdefault\\s+as\\s+${escName}\\b[^}]*\\}\\s+from\\s+['"]([^'"]+)['"]`,
+        'm',
+      )
+    : new RegExp(
+        `export\\s+\\{[^}]*\\b${escName}\\b[^}]*\\}\\s+from\\s+['"]([^'"]+)['"]`,
+        'm',
+      );
+  const m = exportRe.exec(contents);
+  if (!m) return null;
+  // Resolve the re-exported path relative to the barrel's location.
+  return resolveAnyImport(barrelFile, m[1]!, exportName, defaultExport);
+}
+
 // Resolve a relative import path to an absolute `.gts/.gjs` file.
 // Doesn't follow package imports (those go through node_modules and
 // are typically barrels we can't statically traverse without TS).
@@ -239,6 +394,26 @@ function resolveOuterWrapperTagInner(
   return null;
 }
 
+// Resolve outer-wrapper for a component invoked from `consumerFile`
+// when Glint's TS-based `findComponentDeclSourceFile` returned null
+// (typically: the component is imported through a package-level
+// barrel and TS can't trace the symbol back to its source file).
+//
+// We bypass TS by looking up the `import` statement in the consumer's
+// source, resolving the path (relative or package-style), following
+// barrel re-exports, and then walking the component's template chain.
+//
+// Returns the outermost native wrapper tag, or null if we can't
+// locate the source.
+export function resolveOuterWrapperFromConsumerImport(
+  consumerFile: string,
+  componentName: string,
+): string | null {
+  const sourceFile = resolveComponentImport(consumerFile, componentName);
+  if (sourceFile === null) return null;
+  return resolveOuterWrapperTagInner(sourceFile, new Set(), 0);
+}
+
 // Test-only.
 export function _clearOuterWrapperCache(): void {
   cache.clear();
diff --git a/test/glint-fixtures/cross-package-barrel-consumer.gts b/test/glint-fixtures/cross-package-barrel-consumer.gts
new file mode 100644
index 0000000..dba587e
--- /dev/null
+++ b/test/glint-fixtures/cross-package-barrel-consumer.gts
@@ -0,0 +1,18 @@
+// Cross-package barrel import — consumer pulls `<ListLink>` through a
+// package's barrel (`list-link-addon/components`). The import-based
+// fallback in `lib/outer-wrapper-resolver.ts` walks the consumer's
+// import statement, resolves the package path, follows the barrel
+// re-export, and reads the resolved `.gts` to find the outer
+// wrapper (`<li>` via ListItem).
+//
+// Mirrors the design-system component-package pattern that Glint's
+// TS symbol resolution can fail to follow when the package's
+// compiled declarations don't expose the source typing cleanly.
+import { ListLink } from 'list-link-addon/components';
+
+<template>
+  <ul>
+    <ListLink>One</ListLink>
+    <ListLink>Two</ListLink>
+  </ul>
+</template>
diff --git a/test/glint-fixtures/node_modules/list-link-addon/package.json b/test/glint-fixtures/node_modules/list-link-addon/package.json
new file mode 100644
index 0000000..9914868
--- /dev/null
+++ b/test/glint-fixtures/node_modules/list-link-addon/package.json
@@ -0,0 +1,10 @@
+{
+  "name": "list-link-addon",
+  "version": "0.0.0",
+  "exports": {
+    "./*": {
+      "types": "./declarations/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  }
+}
diff --git a/test/glint-fixtures/node_modules/list-link-addon/src/components.ts b/test/glint-fixtures/node_modules/list-link-addon/src/components.ts
new file mode 100644
index 0000000..5ccba05
--- /dev/null
+++ b/test/glint-fixtures/node_modules/list-link-addon/src/components.ts
@@ -0,0 +1,6 @@
+// Barrel re-export pattern (mirrors design-system component packages):
+// `export { default as X } from './path/to/X.gts'` — TS may not always
+// trace symbols back through this when the package's compiled
+// declarations aren't installed.
+export { default as ListItem } from './components/list-item.gts';
+export { default as ListLink } from './components/list-link.gts';
diff --git a/test/glint-fixtures/node_modules/list-link-addon/src/components/list-item.gts b/test/glint-fixtures/node_modules/list-link-addon/src/components/list-item.gts
new file mode 100644
index 0000000..50943b3
--- /dev/null
+++ b/test/glint-fixtures/node_modules/list-link-addon/src/components/list-item.gts
@@ -0,0 +1,6 @@
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+interface S { Blocks: { default: [] }; Element: HTMLLIElement }
+const ListItem: TemplateOnlyComponent<S> = <template>
+  <li ...attributes>{{yield}}</li>
+</template>;
+export default ListItem;
diff --git a/test/glint-fixtures/node_modules/list-link-addon/src/components/list-link.gts b/test/glint-fixtures/node_modules/list-link-addon/src/components/list-link.gts
new file mode 100644
index 0000000..5662423
--- /dev/null
+++ b/test/glint-fixtures/node_modules/list-link-addon/src/components/list-link.gts
@@ -0,0 +1,9 @@
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import ListItem from './list-item.gts';
+interface S { Blocks: { default: [] }; Element: HTMLAnchorElement }
+const ListLink: TemplateOnlyComponent<S> = <template>
+  <ListItem>
+    <a href="#" ...attributes>{{yield}}</a>
+  </ListItem>
+</template>;
+export default ListLink;
diff --git a/test/glint.test.ts b/test/glint.test.ts
index e270fc0..bee985b 100644
--- a/test/glint.test.ts
+++ b/test/glint.test.ts
@@ -233,6 +233,31 @@ describe('Glint integration: cross-file .gts type resolution', () => {
     ).toBeDefined();
   });
 
+  it('cross-package-barrel-consumer.gts: import-based fallback resolves through barrel re-exports', () => {
+    // Mirrors design-system-style component packages: the consumer
+    // imports `<ListLink>` through `list-link-addon/components`
+    // (a barrel `src/components.ts` re-exporting `default as ListLink`
+    // from `./components/list-link.gts`). Glint's TS symbol resolution
+    // doesn't always reach the source through such barrels; the
+    // import-based fallback in `lib/outer-wrapper-resolver.ts` walks
+    // the consumer's `import` statement, resolves the package path
+    // (Node-style + `src/<sub>.ts` source preference), follows the
+    // re-export, and walks the resulting `<template>` chain.
+    //
+    // ListLink's leaf is `<a>`; outer wrapper is `<li>` (via
+    // `<ListItem>`). The consumer places `<ListLink>` under `<ul>` —
+    // legal at runtime (`<ul><li><a></a></li></ul>`). The override
+    // resolves to `<li>` and `element-permitted-content` doesn't fire.
+    const { filename, contents } = readFixture('cross-package-barrel-consumer.gts');
+    const { componentTagMap } = extractAttrTypeMap(filename, contents)!;
+    const entries = [...componentTagMap.entries()];
+    const liEntries = entries.filter(([, tag]) => tag === 'li');
+    expect(
+      liEntries.length,
+      `expected ListLink (imported via barrel) to resolve to 'li'; got: ${JSON.stringify(entries)}`,
+    ).toBeGreaterThan(0);
+  });
+
   it('leaf-element-under-list-wrapper-consumer.gts: outer-wrapper resolver overrides leaf-interactive resolution', () => {
     // A component declares `Element: HTMLAnchorElement` (Glint reads
     // the leaf interactive type → 'a'), but its template wraps the

From 5dbe339060668e34f0d528885a97b79da5169516 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20R=C3=B8ed?= <johanroed@gmail.com>
Date: Fri, 8 May 2026 19:14:48 +0200
Subject: [PATCH 10/20] Address Copilot review (round 2): C8/C9/C10
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

C8 (blank.ts + transform.ts):
  `tryInjectImgRequiredAttrsViaHook` recorded the element offset in a
  single `imgSplatOffsets` list, and the downstream `processElement`
  hook injected BOTH `src` AND `alt` for any registered offset. A
  component template that binds only `src={{this.src}}` (common) would
  silently get an `alt=DynamicValue` injected, masking `wcag/h37`
  (missing alt) when the consumer forgot to pass an alt.

  Split into per-attr offset lists: `imgSplatSrcOffsets` /
  `imgSplatAltOffsets`. Each path (`tryInjectImgRequiredAttrs` for
  native `<img ...attributes>` and `tryInjectImgRequiredAttrsViaHook`
  for component-substituted `<img>`) registers only the attrs it can
  guarantee at runtime. The hook injects per-attr.

  Native `<img ...attributes>` still registers BOTH (the splat is the
  contract — we can't statically know what the parent passes). The
  component-substituted path registers only what's in the addon's
  `attrCtx.attrs`. Updated 4 tests in `test/blank.test.ts`; new test
  asserts the per-attr precision (consumer wrote `src=` literally,
  alt is missing — `imgSplatAltOffsets` records the offset,
  `imgSplatSrcOffsets` does not).

C9 (lib/classic-resolver.ts):
  Custom `isLowercaseHtmlTag` filtered to lowercase-ASCII tag names.
  This rejected mixed-case SVG roots (`linearGradient`,
  `clipPath`, …) that `lib/glint.ts:resolveAddonHbsTemplate` accepts
  via the shared `isNativeTag`. Fix: import `isNativeTag` from
  `blank.js` and use it in classic-resolver. The earlier comment
  about avoiding circular imports was speculative — blank.ts doesn't
  import classic-resolver (the dep flows transform.ts →
  classic-resolver), so direct import is safe.

C10 (lib/classic-resolver.ts):
  `findClassicComponent` iterated `fs.readdirSync` results in
  filesystem order, which varies across OS / filesystem and would
  return different addon templates for the same kebab name on
  different platforms. Sort entries (and scoped-package entries) by
  name before probing so the resolver is deterministic regardless of
  filesystem.
---
 blank.ts                | 74 ++++++++++++++++++++++++++++++-----------
 lib/classic-resolver.ts | 19 +++++------
 test/blank.test.ts      | 28 +++++++++++-----
 transform.ts            | 38 ++++++++++++---------
 4 files changed, 105 insertions(+), 54 deletions(-)

diff --git a/blank.ts b/blank.ts
index 78adcf1..2875993 100644
--- a/blank.ts
+++ b/blank.ts
@@ -478,7 +478,17 @@ interface Context {
   renames: Array<[number, number, string]>;
   fullyBlankedRanges: Range[];
   dynamicContentOffsets: number[];
-  imgSplatOffsets: number[];
+  // Per-attr hook-injection offsets. The downstream `processElement`
+  // hook injects `src=DynamicValue` only for offsets in
+  // `imgSplatSrcOffsets` and `alt=DynamicValue` only for offsets in
+  // `imgSplatAltOffsets`. Splitting per-attr (rather than a single
+  // imgSplatOffsets list that triggers both) lets us register only
+  // the attrs the component/template actually guarantees — a
+  // template binding `src={{this.src}}` but not `alt` only registers
+  // `src`, so `wcag/h37` (missing alt) still fires when the consumer
+  // forgets to pass an alt.
+  imgSplatSrcOffsets: number[];
+  imgSplatAltOffsets: number[];
   effectiveComponentAttrMap?: Map<string, ComponentAttrs>;
   // When set, `handleBlockStatement` uses the selection from this map
   // (keyed by the BlockStatement's source-start offset) instead of the
@@ -700,11 +710,21 @@ function tryInjectImgRequiredAttrsViaHook(
   const present = new Set((node.attributes ?? []).map((a) => a.name));
   // `src` / `alt` ATTRS on the consumer (not @src / @alt args) take
   // precedence — the consumer chose to write the literal, html-validate
-  // should validate it. Skip the hook in that case.
-  const needsSrc = !present.has('src') && attrCtx.attrs['src'] !== undefined;
-  const needsAlt = !present.has('alt') && attrCtx.attrs['alt'] !== undefined;
-  if (!needsSrc && !needsAlt) return;
-  ctx.imgSplatOffsets.push(startOffset(node));
+  // should validate it. Skip per-attr in that case.
+  //
+  // Per-attr precision matters here: the downstream `processElement`
+  // hook injects `src` only for offsets in `imgSplatSrcOffsets` and
+  // `alt` only for offsets in `imgSplatAltOffsets`. For a component
+  // whose template binds `src={{this.src}}` but not `alt`, only the
+  // src set gets the offset — `wcag/h37` (missing alt) still fires
+  // correctly when the consumer forgets to pass an alt.
+  const offset = startOffset(node);
+  if (!present.has('src') && attrCtx.attrs['src'] !== undefined) {
+    ctx.imgSplatSrcOffsets.push(offset);
+  }
+  if (!present.has('alt') && attrCtx.attrs['alt'] !== undefined) {
+    ctx.imgSplatAltOffsets.push(offset);
+  }
 }
 
 // Find a Glimmer-only attribute (`@arg`, modifier, `...attributes`)
@@ -750,8 +770,16 @@ function tryInjectImgRequiredAttrs(node: AST.ElementNode, ctx: Context): void {
   const hasSplat = (node.attributes ?? []).some((a) => a.name === '...attributes');
   if (!hasSplat) return;
   const present = new Set((node.attributes ?? []).map((a) => a.name));
-  if (present.has('src') && present.has('alt')) return;
-  ctx.imgSplatOffsets.push(startOffset(node));
+  // Native `<img ...attributes>`: the splat is the contract — whatever
+  // the parent passes flows through. We don't know statically which
+  // attrs come through, so be permissive: register both `src` and `alt`
+  // for hook-injection so downstream rules see "attribute present,
+  // value unknowable" for whichever the consumer didn't write
+  // explicitly. Real-bug detection happens at the consumer of THIS
+  // component (where they may forget to pass src/alt).
+  const offset = startOffset(node);
+  if (!present.has('src')) ctx.imgSplatSrcOffsets.push(offset);
+  if (!present.has('alt')) ctx.imgSplatAltOffsets.push(offset);
 }
 
 function tryInjectInputType(node: AST.ElementNode, ctx: Context): void {
@@ -1285,14 +1313,19 @@ export interface BlankResult {
   content: string;
   error: Error | null;
   dynamicContentOffsets: number[];
-  // Offsets of `<img ...attributes>` elements (start of `<` byte) where
-  // the consumer-side `...attributes` is expected to provide required
-  // attrs (src/alt) at runtime. The transformer's processElement hook
-  // synthesizes these attrs as DynamicValue at parse-time so html-
-  // validate sees them as "present, value unknowable" — sidesteps the
-  // narrow-slot problem where source-side rewrite can't fit two 9-char
-  // `attr='   '` placeholders into a 13-char `...attributes` slot.
-  imgSplatOffsets: number[];
+  // Per-attr offsets for hook-time `setAttribute` injection. The
+  // transformer's `processElement` hook injects `src=DynamicValue`
+  // only at offsets in `imgSplatSrcOffsets` and `alt=DynamicValue`
+  // only at offsets in `imgSplatAltOffsets`. Splitting per-attr
+  // sidesteps the narrow-slot problem (a 13-char `...attributes`
+  // slot can't fit two 9-char `attr='   '` placeholders) AND lets
+  // a component-substituted `<img>` register only the attrs its
+  // template actually guarantees — so a template binding
+  // `src={{this.src}}` but not `alt` only registers `src`, and
+  // `wcag/h37` (missing alt) still fires when the consumer forgets
+  // to pass an alt.
+  imgSplatSrcOffsets: number[];
+  imgSplatAltOffsets: number[];
   // Rule IDs that the consumer should disable for this Source as a whole —
   // populated when the template contains structural patterns the static
   // blanker can't faithfully model. Today: `wcag/h32` when a `<form>` has
@@ -1308,7 +1341,8 @@ export interface BlankErrorResult {
   error: Error;
   dynamicContentOffsets?: undefined;
   disableForRules?: undefined;
-  imgSplatOffsets?: undefined;
+  imgSplatSrcOffsets?: undefined;
+  imgSplatAltOffsets?: undefined;
 }
 
 function blankTemplateContent(
@@ -1346,7 +1380,8 @@ function blankTemplateContent(
     renames: [],
     fullyBlankedRanges: [],
     dynamicContentOffsets: [],
-    imgSplatOffsets: [],
+    imgSplatSrcOffsets: [],
+    imgSplatAltOffsets: [],
     branchSelections,
     inFullyBlankedRange(offset: number): boolean {
       for (const [s, e] of ctx.fullyBlankedRanges) {
@@ -1409,7 +1444,8 @@ function blankTemplateContent(
     content: buf.join(''),
     error: null,
     dynamicContentOffsets: ctx.dynamicContentOffsets,
-    imgSplatOffsets: ctx.imgSplatOffsets,
+    imgSplatSrcOffsets: ctx.imgSplatSrcOffsets,
+    imgSplatAltOffsets: ctx.imgSplatAltOffsets,
     disableForRules: detectStructuralYieldRules(
       ast,
       branchSelections,
diff --git a/lib/classic-resolver.ts b/lib/classic-resolver.ts
index d87a5a6..a800886 100644
--- a/lib/classic-resolver.ts
+++ b/lib/classic-resolver.ts
@@ -31,6 +31,7 @@ import path from 'node:path';
 import { traverse } from '@glimmer/syntax';
 import type { AST } from '@glimmer/syntax';
 
+import { isNativeTag } from '../blank.js';
 import type { ComponentAttrs } from './builtin-components.js';
 import { extractSplattedRootFromTemplate } from './component-attrs.js';
 
@@ -95,6 +96,11 @@ function findClassicComponent(consumerFile: string, kebabName: string): Componen
       } catch {
         entries = [];
       }
+      // Sort by name for deterministic resolution: `fs.readdirSync`
+      // returns entries in filesystem order, which varies across OS
+      // and filesystems. When two addons ship the same kebab-cased
+      // template, sort order picks a stable winner.
+      entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
       for (const entry of entries) {
         // pnpm uses symlinks for packages — `isDirectory()` returns
         // false on a symlink, so accept symlinks too. The lookup below
@@ -110,10 +116,11 @@ function findClassicComponent(consumerFile: string, kebabName: string): Componen
           } catch {
             continue;
           }
+          scopedEntries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
           for (const scoped of scopedEntries) {
             if (!scoped.isDirectory() && !scoped.isSymbolicLink()) continue;
             const result = tryProbeAddon(path.join(scopeRoot, scoped.name), kebabName);
-            if (result && isLowercaseHtmlTag(result.tag)) {
+            if (result && isNativeTag(result.tag)) {
               cache.set(cacheKey, result);
               return result;
             }
@@ -121,7 +128,7 @@ function findClassicComponent(consumerFile: string, kebabName: string): Componen
           continue;
         }
         const result = tryProbeAddon(path.join(nodeModules, entry.name), kebabName);
-        if (result && isLowercaseHtmlTag(result.tag)) {
+        if (result && isNativeTag(result.tag)) {
           cache.set(cacheKey, result);
           return result;
         }
@@ -134,14 +141,6 @@ function findClassicComponent(consumerFile: string, kebabName: string): Componen
   return null;
 }
 
-// Lightweight native-tag check that doesn't pull `isNativeTag` from
-// blank.ts (avoids circular import — blank.ts → classic-resolver.ts
-// chain). A component template's root being a lowercase ASCII letter
-// followed by name-chars is a sufficient proxy for "native HTML tag";
-// the actual blanker does the strict check via NATIVE_TAGS.
-function isLowercaseHtmlTag(tag: string): boolean {
-  return /^[a-z][a-z0-9-]*$/.test(tag);
-}
 
 // Walk a template AST, find every single-segment PascalCase invocation
 // (`<EsCard>`, not `<This.Foo>` or `<Forms::TextInput>`), and build a
diff --git a/test/blank.test.ts b/test/blank.test.ts
index 1b9b7e8..637c5a6 100644
--- a/test/blank.test.ts
+++ b/test/blank.test.ts
@@ -112,8 +112,12 @@ describe('mustache blanking', () => {
     expect(out.content).toHaveLength(src.length);
     expect(out.content).not.toContain('...attributes');
     expect(
-      out.imgSplatOffsets,
-      `expected the <img ...attributes> offset to be recorded for hook-time injection`,
+      out.imgSplatSrcOffsets,
+      `expected the <img ...attributes> offset to be recorded for src injection`,
+    ).toEqual([0]);
+    expect(
+      out.imgSplatAltOffsets,
+      `expected the <img ...attributes> offset to be recorded for alt injection`,
     ).toEqual([0]);
   });
 
@@ -124,28 +128,34 @@ describe('mustache blanking', () => {
     const src = '<img @loading="lazy" {{on "load" this.h}} ...attributes>';
     const out = blank(src);
     expect(out.content).toHaveLength(src.length);
-    expect(out.imgSplatOffsets).toEqual([0]);
+    expect(out.imgSplatSrcOffsets).toEqual([0]);
+    expect(out.imgSplatAltOffsets).toEqual([0]);
   });
 
   it('does not record offset when the consumer wrote both src and alt explicitly', () => {
     // When src AND alt are both already on the element, no injection is
-    // needed — leave the offset out of the set so the hook skips it.
+    // needed — leave the offset out of the per-attr sets so the hook
+    // skips it.
     const src = '<img src="/foo.png" alt="bar" {{on "load" this.h}} ...attributes>';
     const out = blank(src);
     expect(out.content).toHaveLength(src.length);
     // Original literal values survive.
     expect(out.content).toContain('src="/foo.png"');
     expect(out.content).toContain('alt="bar"');
-    expect(out.imgSplatOffsets).toEqual([]);
+    expect(out.imgSplatSrcOffsets).toEqual([]);
+    expect(out.imgSplatAltOffsets).toEqual([]);
   });
 
-  it('records offset when only ONE of src/alt is consumer-written (other still synthesized)', () => {
+  it('records offset only for the missing attr when only one is consumer-written', () => {
     // When the consumer wrote only `src=` but not `alt=`, alt still needs
-    // synthesis — record the offset; the hook checks per-attr presence
-    // and synthesizes only the missing one.
+    // synthesis (record in altOffsets) but src does NOT (already there).
+    // Per-attr precision: this is exactly the FN-avoidance Copilot flagged
+    // — synthesizing both for any registered offset would silence
+    // wcag/h37 (missing alt) when the component only guarantees src.
     const src = '<img src="/foo.png" {{on "load" this.h}} ...attributes>';
     const out = blank(src);
-    expect(out.imgSplatOffsets).toEqual([0]);
+    expect(out.imgSplatSrcOffsets).toEqual([]);
+    expect(out.imgSplatAltOffsets).toEqual([0]);
   });
 });
 
diff --git a/transform.ts b/transform.ts
index 9c31438..44a097c 100644
--- a/transform.ts
+++ b/transform.ts
@@ -150,7 +150,8 @@ function offsetToLineCol(source: string, offset: number): { line: number; column
 
 function makeHooks(
   dynamicSet: ReadonlySet<number>,
-  imgSplatSet: ReadonlySet<number>,
+  imgSplatSrcSet: ReadonlySet<number>,
+  imgSplatAltSet: ReadonlySet<number>,
   startOffset: number,
 ): SourceHooks {
   const processAttribute: ProcessAttributeCallback = (attr: AttributeData) => {
@@ -189,16 +190,18 @@ function makeHooks(
         location,
       );
     }
-    // Inject required attrs synthetically for `<img ...attributes>`.
-    // The blanker erases `...attributes` from the source but records
-    // the element's start offset; we honor that here by adding a
-    // DynamicValue-backed `src` and/or `alt` if the consumer didn't
-    // already write them. Sidesteps the source-side slot-width
-    // problem (a 13-char `...attributes` slot can't fit two valid
-    // `attr=value` placeholders that html-validate accepts).
+    // Inject required attrs synthetically for `<img ...attributes>` or
+    // for component-substituted `<img>` whose addon template binds
+    // `src={{this.src}}` and/or `alt={{this.alt}}`. The blanker records
+    // each attr's offset independently in `imgSplatSrcSet` /
+    // `imgSplatAltSet` so we only inject what's actually guaranteed
+    // at runtime — silently injecting `alt` for a component that
+    // doesn't bind it would mask `wcag/h37` (missing alt) at the
+    // consumer.
+    const isImg = (el as unknown as { tagName?: string }).tagName === 'img';
     if (
-      imgSplatSet.has(templateRelativeOffset) &&
-      (el as unknown as { tagName?: string }).tagName === 'img'
+      isImg &&
+      (imgSplatSrcSet.has(templateRelativeOffset) || imgSplatAltSet.has(templateRelativeOffset))
     ) {
       const elWithAttrs = el as unknown as {
         hasAttribute(name: string): boolean;
@@ -209,10 +212,11 @@ function makeHooks(
           valueLocation: unknown,
         ): void;
       };
-      for (const name of ['src', 'alt']) {
-        if (!elWithAttrs.hasAttribute(name)) {
-          elWithAttrs.setAttribute(name, new DynamicValue(''), location, location);
-        }
+      if (imgSplatSrcSet.has(templateRelativeOffset) && !elWithAttrs.hasAttribute('src')) {
+        elWithAttrs.setAttribute('src', new DynamicValue(''), location, location);
+      }
+      if (imgSplatAltSet.has(templateRelativeOffset) && !elWithAttrs.hasAttribute('alt')) {
+        elWithAttrs.setAttribute('alt', new DynamicValue(''), location, location);
       }
     }
   };
@@ -285,7 +289,8 @@ function* transformGlimmer(source: Source): Generator<Source, void, unknown> {
       originalData,
       hooks: makeHooks(
         new Set(result.dynamicContentOffsets ?? []),
-        new Set(result.imgSplatOffsets ?? []),
+        new Set(result.imgSplatSrcOffsets ?? []),
+        new Set(result.imgSplatAltOffsets ?? []),
         0,
       ),
     };
@@ -412,7 +417,8 @@ function* transformGlimmer(source: Source): Generator<Source, void, unknown> {
         originalData,
         hooks: makeHooks(
           new Set(result.dynamicContentOffsets ?? []),
-          new Set(result.imgSplatOffsets ?? []),
+          new Set(result.imgSplatSrcOffsets ?? []),
+          new Set(result.imgSplatAltOffsets ?? []),
           startOffset,
         ),
       };

From a358d40dd1c323822e2532fd2438dc9e6208c7e9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20R=C3=B8ed?= <johanroed@gmail.com>
Date: Fri, 8 May 2026 21:12:21 +0200
Subject: [PATCH 11/20] Chain-attr collection in outer-wrapper resolver
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fix-busts a class of `aria-label-misuse` (and assorted other
attribute-dependent rules) FPs caused by chained component wrappers.
A component declares `Element: HTMLAnchorElement` (Glint reads → 'a');
its template wraps the anchor in another component whose template
renders `<a href={{@href}}>`; the consumer places it under a parent
that's fine with anchors-with-href but not with anchors-without-href.
Pre-fix: we extracted attrs only at the IMMEDIATE template level
(non-native PascalCase wrapper) and substituted the leaf tag without
the `href` from the inner native — html-validate then fired
`aria-label-misuse` on a "non-interactive `<a>`" that's actually
interactive at runtime.

Two changes:

1. `findOutermostElement` now descends through `BlockStatement`
   bodies (e.g. `{{#if @route}}<X>{{else if @href}}<a>{{/if}}`) and
   skips dotted/slot-named elements as wrapper candidates while
   continuing to search for a usable one. Without this, HdsInteractive-
   style templates whose top-level is conditional would fail to walk
   into either branch.

2. `OuterWrapperResolution` now carries `attrs` and `hasSplat` UNIONED
   from each level of the chain (inner wins on conflicts — closer to
   the rendered DOM). `lib/glint.ts` overrides `componentAttrMap`
   with the chain's accumulated attrs, not just the top-level
   splatted-root descriptor. The runtime `<a>` carries `href` (from
   the inner native) AND `aria-label` (from the outer wrapper's
   invocation), so html-validate's role-validity checks pass.

Verified impact on real HDS files (with HDS built so source `src/` is
reachable through pnpm-linked node_modules):
  aria-label-misuse:        38 → 5  (33 cleared; remaining are real
                                     "strictly allowed but not
                                     recommended" stylistic warnings)
  element-permitted-content: 172 → 11 (161 cleared; chain-attr
                                       collection helps here too —
                                       parent-context checks see the
                                       outer wrapper instead of the
                                       leaf)

Sampled 5 cleared findings to confirm they were FPs:
  - HdsButton invocations resolved to `<a>` without href; runtime
    DOM is `<button>` (no @href branch) or `<a href>` (with @href) —
    both interactive, both allow aria-label.
  - HdsAppFooterLink under `<ul>`: runtime is
    `<ul><li><a></a></li></ul>` (HdsAppFooterLink wraps `<a>` in
    HdsAppFooterItem which renders `<li>`) — fully legal.

New regression test (`conditional-leaf-href-consumer.gts`) asserts
the chain-attr collection at the AST level: a wrapper whose template
contains a top-level `{{#if @href}}<a href={{@href}}>{{else}}<button>`
bubbles `href` up so consumer-side substitutions register it.

Exported `literalAttrs` and `elementHasSplat` from
`lib/component-attrs.ts` so the resolver can read attrs off any
element node directly (rather than going through the splatted-root
helper which has its own selection logic).
---
 lib/component-attrs.ts                        |   4 +-
 lib/glint.ts                                  |  41 +++--
 lib/outer-wrapper-resolver.ts                 | 151 ++++++++++++++----
 .../conditional-leaf-href-consumer.gts        |  21 +++
 .../conditional-leaf-href-wrapper.gts         |  21 +++
 test/glint-fixtures/conditional-leaf-href.gts |  24 +++
 test/glint.test.ts                            |  34 ++++
 7 files changed, 248 insertions(+), 48 deletions(-)
 create mode 100644 test/glint-fixtures/conditional-leaf-href-consumer.gts
 create mode 100644 test/glint-fixtures/conditional-leaf-href-wrapper.gts
 create mode 100644 test/glint-fixtures/conditional-leaf-href.gts

diff --git a/lib/component-attrs.ts b/lib/component-attrs.ts
index a9eb232..d4ba900 100644
--- a/lib/component-attrs.ts
+++ b/lib/component-attrs.ts
@@ -76,14 +76,14 @@ function isGlimmerOnlyAttr(name: string | undefined): boolean {
   return name.startsWith('@') || name === '...attributes' || name === 'as' || name.startsWith('|');
 }
 
-function elementHasSplat(node: AST.ElementNode): boolean {
+export function elementHasSplat(node: AST.ElementNode): boolean {
   for (const attr of node.attributes ?? []) {
     if (attr.name === '...attributes') return true;
   }
   return false;
 }
 
-function literalAttrs(node: AST.ElementNode): Record<string, string> {
+export function literalAttrs(node: AST.ElementNode): Record<string, string> {
   const attrs: Record<string, string> = {};
   for (const attr of node.attributes ?? []) {
     if (isGlimmerOnlyAttr(attr.name)) continue;
diff --git a/lib/glint.ts b/lib/glint.ts
index deddce5..6c7e14a 100644
--- a/lib/glint.ts
+++ b/lib/glint.ts
@@ -1032,12 +1032,24 @@ export function extractAttrTypeMap(filename: string, contents: string): Extracti
             const outerWrapper = resolveOuterWrapperTag(gtsPath);
             const currentResolved = componentTagMap.get(key);
             sameTransitivePackageOuterRan = true;
-            if (
-              outerWrapper !== null &&
-              outerWrapper !== currentResolved &&
-              isNativeTag(outerWrapper)
-            ) {
-              componentTagMap.set(key, outerWrapper);
+            if (outerWrapper !== null && isNativeTag(outerWrapper.tag)) {
+              if (outerWrapper.tag !== currentResolved) {
+                componentTagMap.set(key, outerWrapper.tag);
+              }
+              // Always update componentAttrMap with the chain's
+              // accumulated attrs — even when the leaf tag matches the
+              // current resolution, the chain's deeper attrs (e.g. an
+              // `<a href={{@href}}>` in a wrapper's wrapper) are what
+              // make rules like `aria-label-misuse` pass. Without these,
+              // we'd inject only the SPLATTED-ROOT level's attrs (which
+              // for a non-native splatted root would be the wrapper's
+              // literal/mustache attrs only, missing the ultimately-
+              // rendered native's).
+              componentAttrMap.set(key, {
+                tag: outerWrapper.tag,
+                attrs: outerWrapper.attrs,
+                hasSplat: outerWrapper.hasSplat,
+              });
             }
           }
         }
@@ -1081,12 +1093,17 @@ export function extractAttrTypeMap(filename: string, contents: string): Extracti
         const componentName = node.parent.sourceNode.tag;
         const outerFromImport = resolveOuterWrapperFromConsumerImport(filename, componentName);
         const currentResolved = componentTagMap.get(key);
-        if (
-          outerFromImport !== null &&
-          outerFromImport !== currentResolved &&
-          isNativeTag(outerFromImport)
-        ) {
-          componentTagMap.set(key, outerFromImport);
+        if (outerFromImport !== null && isNativeTag(outerFromImport.tag)) {
+          if (outerFromImport.tag !== currentResolved) {
+            componentTagMap.set(key, outerFromImport.tag);
+          }
+          // Override componentAttrMap with the chain's accumulated
+          // attrs (see same-package branch above for rationale).
+          componentAttrMap.set(key, {
+            tag: outerFromImport.tag,
+            attrs: outerFromImport.attrs,
+            hasSplat: outerFromImport.hasSplat,
+          });
         }
       }
     }
diff --git a/lib/outer-wrapper-resolver.ts b/lib/outer-wrapper-resolver.ts
index 56c0523..61fb49f 100644
--- a/lib/outer-wrapper-resolver.ts
+++ b/lib/outer-wrapper-resolver.ts
@@ -39,37 +39,101 @@ import { preprocess, traverse } from '@glimmer/syntax';
 import type { AST } from '@glimmer/syntax';
 
 import { isNativeTag } from '../blank.js';
+import { elementHasSplat, literalAttrs } from './component-attrs.js';
 
 const preprocessor = new Preprocessor();
 
+// Result of resolving a component's runtime DOM outermost tag, plus
+// the attrs extracted from each level of the wrapper chain. Used by
+// `lib/glint.ts` to override both `componentTagMap` and
+// `componentAttrMap` when the component's leaf-style Element type
+// (e.g. `<a>`) is hidden inside a wrapper structure that determines
+// the consumer-side parent context.
+//
+// The `attrs` field is a UNION of attrs from each native level walked,
+// with INNER (closer to the DOM) wins on conflicts. That mirrors
+// Glimmer's runtime semantics: a wrapper's `<X ...attributes>` flows
+// the consumer's attrs INTO `<X>`, but `<X>`'s own literal attrs
+// (e.g. `<a href={{@href}}>`) are still applied and visible on the
+// rendered DOM.
+//
+// Why we need this: a component declares `Element: HTMLAnchorElement`
+// (Glint reads → 'a'); its template wraps the anchor in another
+// component (`<HdsInteractive ...attributes>`); HdsInteractive's
+// template renders `<a href={{@href}} ...>`. With only the
+// outermost-splatted-root attrs, we'd inject `class` + `aria-label`
+// (HdsInteractive-level) but miss `href`. html-validate's
+// `aria-label-misuse` then fires because aria-label on an `<a>`
+// without href is invalid.
+export interface OuterWrapperResolution {
+  tag: string;
+  attrs: Record<string, string>;
+  // Whether the template's actual native leaf has `...attributes` on
+  // it. Forwarded from the leaf level so component-attr injection
+  // logic that depends on splat-presence (e.g. `lookupComponentAttr`'s
+  // builtin-fallback in blank.ts) sees the right value.
+  hasSplat: boolean;
+}
+
 // Cache resolved outer-wrappers per absolute filename. Process-
 // lifetime; cleared via `_clearOuterWrapperCache` for tests.
-const cache = new Map<string, string | null>();
+const cache = new Map<string, OuterWrapperResolution | null>();
 
 // Cap recursion depth — components in the wild are unlikely to nest
 // wrappers more than a few levels, and a higher cap risks pathological
 // performance on cycles or accidental fan-out.
 const MAX_DEPTH = 8;
 
-// Find the topmost ElementNode in a template — the OUTERMOST wrapper.
-// Returns null if the template has no element children (e.g. just
-// `{{yield}}` or text).
+// Find the OUTERMOST wrapper in a template — the element that
+// determines the consumer-side parent context.
+//
+// Walk rules:
+//   - DO descend through `BlockStatement` bodies (`{{#if}}/{{else}}`,
+//     `{{#each}}`, etc.) so we can see top-level elements gated by
+//     conditionals — e.g. HdsInteractive's
+//     `{{#if @route}}<LinkTo>{{else if @href}}<a>{{else}}<button>{{/if}}`.
+//   - DO NOT descend into `ElementNode` children: a child is INSIDE
+//     a wrapper, not at the outermost level. `<ListItem><a>...</a>`
+//     should yield `<ListItem>`, not `<a>`.
+//   - SKIP dotted (`<this.X>`, `<F.Options>`) and slot-named
+//     (`<:foo>`) elements — not statically resolvable. Keep walking
+//     siblings / further branches.
+//
+// Among reachable candidates, prefer:
+//   1. The first NATIVE element.
+//   2. Else the first resolvable PascalCase wrapper.
+//
+// Returns null if no usable element exists.
 function findOutermostElement(ast: AST.Template): AST.ElementNode | null {
-  let outermost: AST.ElementNode | null = null;
-  // We want the FIRST top-level element only, not nested children.
-  // `traverse`'s `ElementNode.enter` would visit every descendant;
-  // bail after the first hit at depth 0.
-  let foundAtDepth0 = false;
-  traverse(ast, {
-    ElementNode: {
-      enter(node) {
-        if (foundAtDepth0) return;
-        outermost = node;
-        foundAtDepth0 = true;
-      },
-    },
-  });
-  return outermost;
+  let firstNative: AST.ElementNode | null = null;
+  let firstResolvableWrapper: AST.ElementNode | null = null;
+  function isUnresolvable(tag: string): boolean {
+    return tag.includes('.') || tag.startsWith(':');
+  }
+  function visit(stmts: ReadonlyArray<AST.Statement | AST.TopLevelStatement>): void {
+    for (const stmt of stmts) {
+      if (firstNative !== null) return;
+      if (stmt.type === 'ElementNode') {
+        if (isUnresolvable(stmt.tag)) continue;
+        if (isNativeTag(stmt.tag)) {
+          firstNative = stmt;
+          return;
+        }
+        if (firstResolvableWrapper === null) firstResolvableWrapper = stmt;
+        // Don't descend into ElementNode children — they're nested
+        // content, not outermost candidates.
+        continue;
+      }
+      if (stmt.type === 'BlockStatement') {
+        visit(stmt.program.body);
+        if (firstNative !== null) return;
+        if (stmt.inverse) visit(stmt.inverse.body);
+        continue;
+      }
+    }
+  }
+  visit(ast.body);
+  return firstNative ?? firstResolvableWrapper;
 }
 
 // Resolve a PascalCase component name in `consumerFile`'s source to
@@ -311,22 +375,21 @@ function resolveImportPath(fromFile: string, importSpec: string): string | null
   return null;
 }
 
-// Resolve the outermost native wrapper tag for the component declared
-// in `filename`'s first `<template>` block. Recurses through nested
-// PascalCase wrappers via local imports.
+// Resolve the outermost native wrapper tag and accumulated attrs for
+// the component declared in `filename`'s first `<template>` block.
+// Recurses through nested PascalCase wrappers via local imports.
 //
 // Returns:
-//   - tag name (e.g. 'li', 'div')  if a native wrapper is found.
-//   - null                          if no native wrapper exists in the
-//                                   template chain (e.g. all wrappers
-//                                   are unresolvable PascalCase, or
-//                                   template has no element root).
+//   - {tag, attrs} if a native wrapper is found anywhere in the chain.
+//     `attrs` is the UNION of attrs from each level walked (literal and
+//     mustache-bound), inner-wins on conflicts.
+//   - null         if no native wrapper exists in the template chain.
 //
 // Single-template-block assumption: most component files have one
 // `<template>` block; multi-template files (helper exports + default)
 // would need declaration-to-template matching. The first block is a
 // reasonable default for the common case.
-export function resolveOuterWrapperTag(filename: string): string | null {
+export function resolveOuterWrapperTag(filename: string): OuterWrapperResolution | null {
   return resolveOuterWrapperTagInner(filename, new Set(), 0);
 }
 
@@ -334,7 +397,7 @@ function resolveOuterWrapperTagInner(
   filename: string,
   visited: Set<string>,
   depth: number,
-): string | null {
+): OuterWrapperResolution | null {
   if (depth > MAX_DEPTH) return null;
   if (visited.has(filename)) return null; // cycle guard
   const cached = cache.get(filename);
@@ -368,9 +431,21 @@ function resolveOuterWrapperTagInner(
     const outermost = findOutermostElement(ast);
     if (!outermost) continue;
 
+    // Extract attrs at THIS level — directly off the outermost
+    // element returned by `findOutermostElement`. Reading attrs off a
+    // different element (e.g. via `extractSplattedRootFromTemplate`'s
+    // own splatted-root selection) could miss attrs on the actual
+    // chain wrapper.
+    const levelAttrs = literalAttrs(outermost);
+
     if (isNativeTag(outermost.tag)) {
-      if (depth === 0) cache.set(filename, outermost.tag);
-      return outermost.tag;
+      const result = {
+        tag: outermost.tag,
+        attrs: levelAttrs,
+        hasSplat: elementHasSplat(outermost),
+      };
+      if (depth === 0) cache.set(filename, result);
+      return result;
     }
 
     // Skip dotted invocations (`<This.Foo>`, `<F.Options>`) — those
@@ -385,8 +460,16 @@ function resolveOuterWrapperTagInner(
     if (!importPath) continue;
     const recursed = resolveOuterWrapperTagInner(importPath, visited, depth + 1);
     if (recursed !== null) {
-      if (depth === 0) cache.set(filename, recursed);
-      return recursed;
+      // Merge attrs: outer wrapper level's attrs UNDER the recursed
+      // attrs (inner wins on conflicts — closer to the rendered DOM).
+      const merged = { ...levelAttrs, ...recursed.attrs };
+      const result = {
+        tag: recursed.tag,
+        attrs: merged,
+        hasSplat: recursed.hasSplat,
+      };
+      if (depth === 0) cache.set(filename, result);
+      return result;
     }
   }
 
@@ -408,7 +491,7 @@ function resolveOuterWrapperTagInner(
 export function resolveOuterWrapperFromConsumerImport(
   consumerFile: string,
   componentName: string,
-): string | null {
+): OuterWrapperResolution | null {
   const sourceFile = resolveComponentImport(consumerFile, componentName);
   if (sourceFile === null) return null;
   return resolveOuterWrapperTagInner(sourceFile, new Set(), 0);
diff --git a/test/glint-fixtures/conditional-leaf-href-consumer.gts b/test/glint-fixtures/conditional-leaf-href-consumer.gts
new file mode 100644
index 0000000..7deff6c
--- /dev/null
+++ b/test/glint-fixtures/conditional-leaf-href-consumer.gts
@@ -0,0 +1,21 @@
+// Consumer that uses `<OuterButton>` with `aria-label` set via the
+// wrapper's args. Mirrors the real-world HDS pattern where
+// `<HdsCopyButton>` wraps `<HdsButton>` which wraps `<HdsInteractive>`
+// which renders `<a href={{@href}}>` or `<button>`.
+//
+// Without chain-attr collection, the consumer-side substitution puts
+// `<a aria-label='...'>` (no href) into the blanked output, which
+// fires `aria-label-misuse` (aria-label requires an interactive `<a>`,
+// i.e. one with href).
+//
+// With chain-attr collection (this regression test asserts the
+// behavior at the AST/map level), the substituted element carries
+// `href` as a `DynamicValue` placeholder so html-validate sees the
+// `<a>` as interactive and aria-label-misuse doesn't fire.
+import OuterButton from './conditional-leaf-href-wrapper.gts';
+
+<template>
+  <OuterButton @href="/" @label="More info">
+    Click me
+  </OuterButton>
+</template>
diff --git a/test/glint-fixtures/conditional-leaf-href-wrapper.gts b/test/glint-fixtures/conditional-leaf-href-wrapper.gts
new file mode 100644
index 0000000..8caba33
--- /dev/null
+++ b/test/glint-fixtures/conditional-leaf-href-wrapper.gts
@@ -0,0 +1,21 @@
+// Outer wrapper around `<ConditionalLeaf>` (mirrors HdsButton wrapping
+// HdsInteractive). The wrapper's template invokes ConditionalLeaf
+// with extra args + `aria-label`. We want the chain-attr collection
+// to combine: ConditionalLeaf's `<a href={{@href}}>` attrs (href +
+// any others on that native) AND this wrapper's `aria-label`.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import ConditionalLeaf from './conditional-leaf-href.gts';
+
+interface OuterButtonSig {
+  Args: { href?: string; label?: string };
+  Element: HTMLAnchorElement | HTMLButtonElement;
+  Blocks: { default: [] };
+}
+
+const OuterButton: TemplateOnlyComponent<OuterButtonSig> = <template>
+  <ConditionalLeaf @href={{@href}} aria-label={{@label}} ...attributes>
+    {{yield}}
+  </ConditionalLeaf>
+</template>;
+
+export default OuterButton;
diff --git a/test/glint-fixtures/conditional-leaf-href.gts b/test/glint-fixtures/conditional-leaf-href.gts
new file mode 100644
index 0000000..e08dc32
--- /dev/null
+++ b/test/glint-fixtures/conditional-leaf-href.gts
@@ -0,0 +1,24 @@
+// `<ConditionalLeaf>` mirrors HdsInteractive: declares an interactive
+// leaf type but the template's outermost is a top-level
+// `{{#if}}/{{else}}` switching between `<a href={{@href}}>` and
+// `<button>`. The walker descends through the BlockStatement to find
+// the first reachable native (`<a href={{@href}}>`), and the
+// chain-attr collection picks up `href` so consumer-side substitutions
+// don't fire `aria-label-misuse` on an `<a>` without href.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+
+interface ConditionalLeafSig {
+  Args: { href?: string };
+  Blocks: { default: [] };
+  Element: HTMLAnchorElement | HTMLButtonElement;
+}
+
+const ConditionalLeaf: TemplateOnlyComponent<ConditionalLeafSig> = <template>
+  {{#if @href}}
+    <a href={{@href}} ...attributes>{{yield}}</a>
+  {{else}}
+    <button type="button" ...attributes>{{yield}}</button>
+  {{/if}}
+</template>;
+
+export default ConditionalLeaf;
diff --git a/test/glint.test.ts b/test/glint.test.ts
index bee985b..3f7c940 100644
--- a/test/glint.test.ts
+++ b/test/glint.test.ts
@@ -233,6 +233,40 @@ describe('Glint integration: cross-file .gts type resolution', () => {
     ).toBeDefined();
   });
 
+  it('conditional-leaf-href-consumer.gts: chain-attr collection picks up href from a deep leaf inside conditional branches', () => {
+    // Mirrors the real-world `<HdsButton>` → `<HdsInteractive>` pattern:
+    // an outer wrapper invokes a component whose template is a top-
+    // level `{{#if @href}}<a href={{@href}}>{{else}}<button>{{/if}}`.
+    // The walker descends through the BlockStatement to find the
+    // first reachable native (`<a href={{@href}}>`), and the chain-
+    // attr collection unions:
+    //   - the outer wrapper level's attrs (`aria-label={{@label}}`)
+    //   - the leaf's attrs (`href={{@href}}`)
+    // — resulting in `componentAttrMap` recording BOTH. Without this,
+    // a consumer-side substitution to `<a aria-label='   '>` (without
+    // href) would FP-fire `aria-label-misuse` (anchor without href is
+    // non-interactive, can't carry aria-label).
+    //
+    // (Note: this asserts the AST-level chain-attr collection. The
+    // consumer-side source-substitution may still fail to fit `href`
+    // into a too-narrow Glimmer-attr slot — that's a separate
+    // concern, addressable via a hook-time fallback similar to PR #13's
+    // `imgSplatSrcOffsets` / `imgSplatAltOffsets`.)
+    const { filename, contents } = readFixture('conditional-leaf-href-consumer.gts');
+    const { componentAttrMap } = extractAttrTypeMap(filename, contents)!;
+    const entries = [...componentAttrMap.values()];
+    const wrapperEntry = entries.find((e) => e.tag === 'a');
+    expect(wrapperEntry, `expected <OuterButton> to resolve to 'a' (leaf type)`).toBeDefined();
+    expect(
+      'href' in wrapperEntry!.attrs,
+      `expected chain-attr to include 'href' from the leaf <a> in ConditionalLeaf's template; got: ${JSON.stringify(wrapperEntry!.attrs)}`,
+    ).toBe(true);
+    expect(
+      'aria-label' in wrapperEntry!.attrs,
+      `expected chain-attr to include 'aria-label' from OuterButton's wrapping <ConditionalLeaf>; got: ${JSON.stringify(wrapperEntry!.attrs)}`,
+    ).toBe(true);
+  });
+
   it('cross-package-barrel-consumer.gts: import-based fallback resolves through barrel re-exports', () => {
     // Mirrors design-system-style component packages: the consumer
     // imports `<ListLink>` through `list-link-addon/components`

From 521f80c3ee66bb1e0fc6ed08f85ff8d0e7169120 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20R=C3=B8ed?= <johanroed@gmail.com>
Date: Fri, 8 May 2026 21:24:39 +0200
Subject: [PATCH 12/20] Document position on no-implicit-button-type
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add a note in Known Limitations: the rule fires on every untyped
`<button>` regardless of `<form>` ancestry, per html-validate's
strict design. We don't try to soften it. Users who only want
inside-form buttons flagged can disable the rule project-wide.

Static `<form>`-ancestry detection is feasible but inherits the
same per-Source-suppression caveat as wcag/h32 (a button inside a
wrapper component that someone else's template wraps in `<form>`
would be silenced in the wrong direction). Investigated ecosystem
findings (HDS 12 cleared by chain-attr collection — pre-fix wrong-
tag substitutions; discourse 20 are real per the rule).
---
 README.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/README.md b/README.md
index 1900f1d..f87ddda 100644
--- a/README.md
+++ b/README.md
@@ -423,6 +423,11 @@ The bundled `validate-gts` CLI dedupes identical messages by `(line, column, rul
 ## Known limitations
 
 - **Static-string scope.** `{{NAME}}` resolves against same-file `const NAME = '...'` declarations and one-level-deep `import { NAME } from './sibling'` (relative paths only — package and path-aliased imports are skipped). `{{this.field}}` resolves against same-file class-field initializers (`field = '...'` or `field: T = '...'`). What's not resolved: transitive re-exports (`export { X } from './...'` chains), default imports, namespace imports, and getters returning literals — Glint narrows some of these to string-literal types when `--glint` is on, which the blanker picks up through a separate code path.
+- **`no-implicit-button-type` fires on every untyped `<button>`** regardless of `<form>` ancestry — that's html-validate's strict design (default `type=submit` is non-obvious). The plugin doesn't try to soften it; if you'd rather only flag buttons that actually live inside a `<form>` at runtime (where the default-submit matters), disable the rule project-wide and rely on review / a custom lint:
+  ```json
+  { "rules": { "no-implicit-button-type": "off" } }
+  ```
+  Static "is this `<button>` inside a `<form>`?" detection is feasible in principle (walk ancestors at the AST + chain into PascalCase wrappers) but adds the same per-Source-suppression caveat as `wcag/h32`: a button inside a wrapper component that someone else's template wraps in `<form>` would be silenced in the wrong direction. We left it untouched.
 - **TS-flavored block-param types are stripped, not parsed.** `@glimmer/syntax`'s parser doesn't understand `{{#each items as |item: T|}}`-style annotations (or the comma separators that come with multi-param lists). The transformer pre-strips them to whitespace before Glimmer parses, with balanced-bracket scanning so unions (`A | B`), object types (`{ a: number }`), parenthesized types (`(A | B)[]`), generics (`Map<string, number>`), arrays (`T[]`), and qualified names (`NS.Type`) all work. Length-preserving — AST offsets after the strip match original source. The strip only operates inside `as |…|` ranges of mustache openers; type literals appearing elsewhere in the template aren't touched (and Glimmer wouldn't accept them there anyway).
 
 ## Future work

From 7e3d49866e737293fc2c776bf375b89ee783b4de Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20R=C3=B8ed?= <johanroed@gmail.com>
Date: Fri, 8 May 2026 21:51:48 +0200
Subject: [PATCH 13/20] Suppress wcag/h32 when form contains an unresolved
 component child
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A `<form>` whose submit button is provided by a component the static
analyzer can't pin to a native tag (no Glint Element annotation, not
in node_modules, not a builtin, dynamic-element template like
`<this.wrapperElement type={{...}}>`) used to FP-fire wcag/h32 because
the blanker couldn't see any submit candidate. Common in real Ember
codebases that use button-style component wrappers from non-addon
packages or dynamic-element addon components.

Extend `elementYieldsAndLacksSubmit` (PR #17) to also recognize
"form contains unresolved PascalCase / dotted component" as
"may contain submit." Per-Source suppression — same trade-off as the
yield-bearing-form case (real bugs at OTHER locations in the same
template get suppressed too), acceptable given the FP volume.

A previously-`.fails()` test (`namespaced-classic-resolver.hbs`)
now passes for real: the namespaced-component support is still missing
as a feature, but the unresolved-component heuristic catches the same
wcag/h32 FP. Updated the test's narrative.

Verified ecosystem impact:
  discourse wcag/h32:    41 → 10 (31 cleared)
  HDS wcag/h32:          5  → 2  (3 cleared)
  Other rules:           unchanged (no regressions on
                         element-permitted-content, aria-label-misuse,
                         no-implicit-button-type)

Heuristic detail: when iterating a form's children, an ElementNode
is treated as an unresolved component when it's PascalCase / dotted
AND not a builtin AND either has no entry in `glintComponentTagMap`
or has an entry of `'transparent'`. The `'transparent'` case matters
because Glint may resolve a component to a generic-HTMLElement-style
"transparent" tag that doesn't tell us what runtime tag actually
renders.
---
 blank.ts                                      | 34 ++++++++-
 .../form-with-unresolved-component-submit.gts | 41 +++++++++++
 test/integration.test.ts                      | 69 ++++++++++++-------
 3 files changed, 118 insertions(+), 26 deletions(-)
 create mode 100644 examples/form-with-unresolved-component-submit.gts

diff --git a/blank.ts b/blank.ts
index 2875993..bbd2a5a 100644
--- a/blank.ts
+++ b/blank.ts
@@ -1715,6 +1715,20 @@ function elementYieldsAndLacksSubmit(
 ): boolean {
   let hasYield = false;
   let hasStaticSubmit = false;
+  // Tracks whether the form contains any UNRESOLVED PascalCase /
+  // dotted component invocation. Such a component may render a
+  // submit button at runtime that we can't see statically — common
+  // when a button-style component's template uses a dynamic-element
+  // pattern (`<this.wrapperElement type={{...}}>`) or when its
+  // source isn't reachable from the consumer (cross-package paths
+  // outside `node_modules`, no Glint, etc.). Treat "unresolved
+  // component child" as "may contain submit" so `wcag/h32` gets
+  // suppressed for the whole Source. Same per-Source-suppression
+  // trade-off as the unresolvable-wrapper-with-structural-children
+  // heuristic (PR #21): real bugs at OTHER locations in the same
+  // template get suppressed too. Acceptable given the FP volume in
+  // real Ember code.
+  let hasUnresolvedComponent = false;
   function walk(stmts: ReadonlyArray<AST.Statement>): void {
     for (const stmt of stmts) {
       if (hasStaticSubmit) return;
@@ -1742,13 +1756,31 @@ function elementYieldsAndLacksSubmit(
           hasStaticSubmit = true;
           return;
         }
+        // Track unresolved PascalCase / dotted component invocations.
+        // These are candidates for "may contain submit" suppression
+        // when the form has no other static submit. Native tags and
+        // builtins are excluded. Glint-resolved entries are excluded
+        // ONLY when Glint pinned a concrete native tag — entries
+        // mapped to `'transparent'` mean "Glint couldn't pin a tag"
+        // and the component might still render submit at runtime, so
+        // those count as unresolved for this purpose.
+        if (!isNativeTag(stmt.tag) && !lookupBuiltinComponent(stmt.tag)) {
+          const key = stmt.loc.start ? `${stmt.loc.start.line}:${stmt.loc.start.column}` : null;
+          const resolved = key ? glintComponentTagMap?.get(key) : undefined;
+          if (resolved === undefined || resolved === 'transparent') {
+            hasUnresolvedComponent = true;
+          }
+        }
         walk(stmt.children);
         continue;
       }
     }
   }
   walk(form.children);
-  return hasYield && !hasStaticSubmit;
+  // Suppress wcag/h32 for either an opaque-source form (yield-bearing,
+  // PR #17) OR a form whose only "candidates" for submit are
+  // unresolved component invocations (heuristic above).
+  return (hasYield || hasUnresolvedComponent) && !hasStaticSubmit;
 }
 
 // True when a `<fieldset>` body has opaque legend-source content AND
diff --git a/examples/form-with-unresolved-component-submit.gts b/examples/form-with-unresolved-component-submit.gts
new file mode 100644
index 0000000..5364bff
--- /dev/null
+++ b/examples/form-with-unresolved-component-submit.gts
@@ -0,0 +1,41 @@
+// `<form>` containing an UNRESOLVED PascalCase component that
+// (presumably) provides the submit button at runtime. The component's
+// source isn't Glint-typed (no @Element annotation), isn't in
+// node_modules where the classic-by-name resolver looks, and isn't a
+// builtin — so `componentTagMap` has no concrete native tag for it.
+//
+// At runtime, button-style components (e.g. addon-shipped `<XButton
+// @type="submit">`) render real `<button>`s, but our static blanker
+// can't see that — especially when the component's template uses a
+// dynamic-element pattern (`<this.wrapperElement type={{...}}>`).
+// Without this heuristic wcag/h32 would FP-fire because the form
+// looks empty of submit candidates from the validator's view.
+//
+// Heuristic: when a `<form>` contains an unresolved PascalCase
+// component AND lacks a statically-detectable submit, the rule
+// suppresses for the Source — the component MIGHT render submit at
+// runtime. Same per-Source-suppression trade-off as the
+// yield-bearing-form case (PR #17): real bugs at OTHER locations in
+// the same template get suppressed too. Acceptable given the volume
+// of these FPs in real-world Ember code.
+import Component from '@glimmer/component';
+
+interface Sig {
+  Element: HTMLFormElement;
+  Args: { onSubmit: () => void };
+  Blocks: { default: [] };
+}
+
+export default class FormWithUnresolvedComponentSubmit extends Component<Sig> {
+  handleSubmit = (e: Event): void => {
+    e.preventDefault();
+    this.args.onSubmit();
+  };
+
+  <template>
+    <form {{on 'submit' this.handleSubmit}} ...attributes>
+      <input type="text" name="email" />
+      <SubmitWidget @label="Save" />
+    </form>
+  </template>
+}
diff --git a/test/integration.test.ts b/test/integration.test.ts
index d1c947a..a6fc6e8 100644
--- a/test/integration.test.ts
+++ b/test/integration.test.ts
@@ -741,31 +741,50 @@ describe('end-to-end fixtures', () => {
     ).toHaveLength(0);
   });
 
-  it.fails(
-    'namespaced-classic-resolver.hbs: <Forms::TextInput> is NOT yet resolved by the by-name resolver (single-segment only)',
-    async () => {
-      // The classic-by-name resolver in `lib/classic-resolver.ts` only
-      // handles single-segment kebab names — `<EsCard>` → `es-card.hbs`.
-      // It doesn't parse Ember's `::` namespace separator nor probe
-      // nested addon paths like `addon/components/forms/text-input.hbs`.
-      //
-      // Asserted via the structural shape: with proper resolution,
-      // `<Forms::TextInput>` would substitute to `<input>` and the
-      // template would lint clean. Today the wrapper transparent-
-      // blanks, leaving an empty `<form>` — which fires wcag/h32
-      // because there's no submit button visible. We assert wcag/h32
-      // does NOT fire (intended future behavior). Today it fires →
-      // .fails() passes the suite. When namespaced resolution lands,
-      // the test passes for real and vitest signals the win.
-      const v = makeValidator();
-      const fp = path.join(__dirname, 'glint-fixtures', 'namespaced-classic-resolver.hbs');
-      const r = await v.validateFile(fp);
-      const wcagH32 = r.results
-        .flatMap((rr) => rr.messages)
-        .filter((m) => m.ruleId === 'wcag/h32');
-      expect(wcagH32).toHaveLength(0);
-    },
-  );
+  it('form-with-unresolved-component-submit.gts: wcag/h32 suppressed when form contains an unresolved component (may render submit)', async () => {
+    // A `<form>` whose submit button is provided by an unresolved
+    // PascalCase component (no Glint Element annotation, not in
+    // node_modules, not a builtin) FP-fired wcag/h32 because the
+    // static blanker couldn't see a submit candidate. Heuristic
+    // extension in `elementYieldsAndLacksSubmit`: a form that lacks
+    // a static submit BUT contains any unresolved component
+    // invocation is treated as "may render submit" and gets the
+    // rule suppressed. Same per-Source-suppression trade-off as
+    // PR #17's yield-bearing-form case.
+    const r = await validate('form-with-unresolved-component-submit.gts');
+    const wcagH32 = r.messages.filter((m) => m.rule === 'wcag/h32');
+    expect(
+      wcagH32,
+      `wcag/h32 must not fire — form contains an unresolved component child that may render submit; got: ${JSON.stringify(r.messages)}`,
+    ).toHaveLength(0);
+  });
+
+  it('namespaced-classic-resolver.hbs: wcag/h32 suppressed via the unresolved-component-child heuristic', async () => {
+    // Originally a `.fails()` test asserting future-intent: namespaced
+    // `<Forms::TextInput>` isn't resolved by the classic-by-name
+    // resolver (it only handles single-segment kebab names). The
+    // wrapper transparent-blanks, leaving an empty `<form>` which
+    // fires wcag/h32.
+    //
+    // Now passes naturally: the unresolved-component-child heuristic
+    // in `elementYieldsAndLacksSubmit` recognizes `<Forms::TextInput>`
+    // as a component our static analysis can't pin and treats it as
+    // "may contain submit" — the form's wcag/h32 is suppressed for
+    // the Source. (This is the same FP class that affects ANY form
+    // whose submit comes from an unresolved component invocation —
+    // a button-style component whose source isn't reachable.)
+    //
+    // Namespaced classic-resolver support is still missing as a
+    // feature; this test is now passing for a different reason than
+    // originally intended.
+    const v = makeValidator();
+    const fp = path.join(__dirname, 'glint-fixtures', 'namespaced-classic-resolver.hbs');
+    const r = await v.validateFile(fp);
+    const wcagH32 = r.results
+      .flatMap((rr) => rr.messages)
+      .filter((m) => m.ruleId === 'wcag/h32');
+    expect(wcagH32).toHaveLength(0);
+  });
 
   it.fails(
     'heuristic-masks-real-bug.gts: per-Source element-permitted-content suppression DOES mask real bugs elsewhere (documented trade-off)',

From f8d4b57a22e0b5c595b73569a385a3d27376f582 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20R=C3=B8ed?= <johanroed@gmail.com>
Date: Fri, 8 May 2026 21:57:32 +0200
Subject: [PATCH 14/20] Address Copilot review (round 3): C11/C12/C13/C14/C15
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

C11 (lib/outer-wrapper-resolver.ts):
  `preprocess(block.contents)` lacked both `stripBlockParamTypeAnnotations`
  and `mode: 'codemod'`. A `.gts` template using TS-flavored block-
  param annotations (`as |x: T|`) would throw, the resolver would
  silently skip the block, and the FPs this resolver is meant to fix
  would re-surface. Apply the same preprocess preamble blank.ts uses.

C12: drop unused `traverse` import from
  `lib/outer-wrapper-resolver.ts` (the file uses only `preprocess` —
  `traverse` was left over from an earlier draft).

C13: rewrite the docstring for `resolvePackageImport` in
  `lib/outer-wrapper-resolver.ts`. The old text claimed the function
  consults `package.json` `exports` / `main`, which it never has —
  the implementation only probes `src/<sub>` and a few bare paths.
  New docstring lists the four probe shapes explicitly.

C14: add an `isEmberAddonPackage` pre-filter to
  `lib/classic-resolver.ts`. `findClassicComponent` previously did 3
  `existsSync` probes per package per PascalCase tag, even for
  packages that obviously don't ship classic component templates
  (anything that's not an Ember addon). Skip non-addon packages by
  reading `package.json` `keywords: ['ember-addon']` or `ember-addon`
  field once, cached per-package. Reduces IO in large
  `node_modules` while preserving the resolver's behavior.

C15: update the comment on the
  `classic-resolver-mustache-bound-attrs.hbs` test to reflect the
  per-attr offset sets (`imgSplatSrcOffsets` / `imgSplatAltOffsets`)
  that replaced the original single `imgSplatOffsets` list.

Verified 168/168 tests pass; HDS / ember-website ecosystem counts
unchanged from previous commit (no regressions from the addon-pre-
filter).
---
 lib/classic-resolver.ts       | 49 ++++++++++++++++++++++++++++++++---
 lib/outer-wrapper-resolver.ts | 39 +++++++++++++++++++---------
 test/integration.test.ts      |  6 +++--
 3 files changed, 77 insertions(+), 17 deletions(-)

diff --git a/lib/classic-resolver.ts b/lib/classic-resolver.ts
index a800886..8d0a189 100644
--- a/lib/classic-resolver.ts
+++ b/lib/classic-resolver.ts
@@ -37,6 +37,42 @@ import { extractSplattedRootFromTemplate } from './component-attrs.js';
 
 const cache = new Map<string, ComponentAttrs>();
 
+// Pre-filter cache for `findClassicComponent`: per absolute package
+// path → "is this an Ember addon?" (`true`/`false`). Only addons ship
+// classic component templates at the canonical `addon/`-prefixed
+// paths, so probing 3 file paths × every package on every PascalCase
+// lookup is wasted IO on large `node_modules`. We read each package's
+// `package.json` once (per process) and cache the verdict.
+//
+// "Is an Ember addon" check: package.json has either
+//   - `keywords` containing `'ember-addon'`, OR
+//   - an `ember-addon` field (object).
+//
+// Both patterns are conventional v1-addon markers. v2 addons use
+// different layouts that classic-by-name resolution doesn't target
+// anyway.
+const isAddonCache = new Map<string, boolean>();
+
+function isEmberAddonPackage(pkgRoot: string): boolean {
+  const cached = isAddonCache.get(pkgRoot);
+  if (cached !== undefined) return cached;
+  let result = false;
+  try {
+    const pkgJson = JSON.parse(fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf8')) as {
+      keywords?: unknown;
+      'ember-addon'?: unknown;
+    };
+    const kws = pkgJson.keywords;
+    const hasKeyword = Array.isArray(kws) && kws.includes('ember-addon');
+    const hasField = typeof pkgJson['ember-addon'] === 'object' && pkgJson['ember-addon'] !== null;
+    result = hasKeyword || hasField;
+  } catch {
+    // Missing / unparseable package.json → not an addon for our purposes.
+  }
+  isAddonCache.set(pkgRoot, result);
+  return result;
+}
+
 // Components our blank-step handles via the builtin map (not by-name
 // resolution). Skip these — they'd shadow the builtin substitution.
 const BUILTIN_COMPONENT_NAMES: ReadonlySet<string> = new Set([
@@ -119,7 +155,9 @@ function findClassicComponent(consumerFile: string, kebabName: string): Componen
           scopedEntries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
           for (const scoped of scopedEntries) {
             if (!scoped.isDirectory() && !scoped.isSymbolicLink()) continue;
-            const result = tryProbeAddon(path.join(scopeRoot, scoped.name), kebabName);
+            const pkgRoot = path.join(scopeRoot, scoped.name);
+            if (!isEmberAddonPackage(pkgRoot)) continue;
+            const result = tryProbeAddon(pkgRoot, kebabName);
             if (result && isNativeTag(result.tag)) {
               cache.set(cacheKey, result);
               return result;
@@ -127,7 +165,9 @@ function findClassicComponent(consumerFile: string, kebabName: string): Componen
           }
           continue;
         }
-        const result = tryProbeAddon(path.join(nodeModules, entry.name), kebabName);
+        const pkgRoot = path.join(nodeModules, entry.name);
+        if (!isEmberAddonPackage(pkgRoot)) continue;
+        const result = tryProbeAddon(pkgRoot, kebabName);
         if (result && isNativeTag(result.tag)) {
           cache.set(cacheKey, result);
           return result;
@@ -180,7 +220,10 @@ export function buildClassicComponentTagMap(
   return { componentTagMap, componentAttrMap };
 }
 
-// Test-only: clear the in-memory by-name resolver cache.
+// Test-only: clear the in-memory by-name resolver caches (the
+// per-(consumerDir, kebabName) lookup cache and the per-package
+// "is an Ember addon" pre-filter cache).
 export function _clearClassicResolverCache(): void {
   cache.clear();
+  isAddonCache.clear();
 }
diff --git a/lib/outer-wrapper-resolver.ts b/lib/outer-wrapper-resolver.ts
index 61fb49f..35643c6 100644
--- a/lib/outer-wrapper-resolver.ts
+++ b/lib/outer-wrapper-resolver.ts
@@ -35,10 +35,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { Preprocessor } from 'content-tag';
-import { preprocess, traverse } from '@glimmer/syntax';
+import { preprocess } from '@glimmer/syntax';
 import type { AST } from '@glimmer/syntax';
 
-import { isNativeTag } from '../blank.js';
+import { isNativeTag, stripBlockParamTypeAnnotations } from '../blank.js';
 import { elementHasSplat, literalAttrs } from './component-attrs.js';
 
 const preprocessor = new Preprocessor();
@@ -243,13 +243,23 @@ function resolveAnyImport(
 }
 
 // Resolve a package-style import (`@scope/pkg/sub` or `pkg/sub`) to
-// an absolute file path, walking `node_modules` upward from `fromFile`
-// and consulting package.json `exports` / `main`.
+// an absolute file path. Walks `node_modules` upward from `fromFile`
+// to find the package root, then probes a fixed set of source-style
+// paths for the sub-path:
 //
-// Strategy: prefer SOURCE files (`src/<sub>.ts/.gts`) over compiled
-// dist (`dist/<sub>.js`), so we can read the original `<template>`
-// blocks. If `src/` doesn't exist, fall through to the package's
-// declared exports.
+//   1. `src/<sub>.{gts,gjs,ts}`  — most v2 addon source layouts.
+//   2. `src/<sub>/index.{gts,gjs,ts}` — directory imports.
+//   3. (no `<sub>`) `src/index.{gts,gjs,ts}`.
+//   4. Bare `<sub>.{ts,gts}` / `<sub>/index.ts` at the package root,
+//      for packages that don't have a `src/` layer.
+//
+// Note: this does NOT read `package.json` `exports` / `main`. We
+// prefer SOURCE files (so we can read the original `<template>`
+// blocks) over whatever the package declares for runtime use, and
+// the source layout for v2 addons is conventional enough that the
+// hardcoded probes hit. If a package uses an unconventional source
+// layout this resolver returns null and the caller falls back to
+// other paths (Glint TS resolution, classic-by-name).
 function resolvePackageImport(fromFile: string, importSpec: string): string | null {
   // Split into `<package-name>` and `<sub-path>` (e.g.
   // `@scope/pkg/foo/bar` → `@scope/pkg`, `foo/bar`;
@@ -298,9 +308,8 @@ function resolvePackageImport(fromFile: string, importSpec: string): string | nu
           if (fs.existsSync(candidate)) return candidate;
         }
       }
-      // Fall back to whatever the package's exports/main points to.
-      // We don't fully resolve `exports` patterns — just probe a few
-      // common shapes.
+      // Fall back to a few bare paths at the package root for
+      // packages that don't have a `src/` layer.
       if (subPath) {
         for (const sub of [`${subPath}.ts`, `${subPath}.gts`, `${subPath}/index.ts`]) {
           const candidate = path.join(pkgRoot, sub);
@@ -424,7 +433,13 @@ function resolveOuterWrapperTagInner(
     if (block.tagName !== 'template') continue;
     let ast: AST.Template;
     try {
-      ast = preprocess(block.contents);
+      // Match `blank.ts`'s template-parsing preamble: strip TS-style
+      // block-param type annotations (`as |x: T|`) so Glimmer's
+      // parser accepts them, and use `mode: 'codemod'` for source
+      // fidelity. Without these, a typed-block-param template would
+      // throw and we'd silently miss wrapper/attr resolution —
+      // reintroducing the FPs this resolver is meant to fix.
+      ast = preprocess(stripBlockParamTypeAnnotations(block.contents), { mode: 'codemod' });
     } catch {
       continue;
     }
diff --git a/test/integration.test.ts b/test/integration.test.ts
index a6fc6e8..e40ed37 100644
--- a/test/integration.test.ts
+++ b/test/integration.test.ts
@@ -686,8 +686,10 @@ describe('end-to-end fixtures', () => {
     // The fix: when the resolved tag is <img> and the addon records
     // `src` (or `alt`) in `attrCtx.attrs` — including the
     // DYNAMIC_VALUE_PLACEHOLDER for mustache-bound values — push the
-    // consumer's offset to `imgSplatOffsets`, the same hook the
-    // `<img ...attributes>` narrow-slot fix uses (PR #13).
+    // consumer's offset to `imgSplatSrcOffsets` / `imgSplatAltOffsets`
+    // per-attr, the same hook the `<img ...attributes>` narrow-slot
+    // fix uses (PR #13). Per-attr precision sidesteps the FN risk of
+    // injecting an unintended attr.
     //
     // Mirrors ember-website's `<ResponsiveImage @src="…" alt="" />`
     // pattern: addon binds `src={{this.src}}`, runtime <img> always

From 6542a1b19cdfa79f4a649b11601cf06284603972 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20R=C3=B8ed?= <johanroed@gmail.com>
Date: Fri, 8 May 2026 23:02:51 +0200
Subject: [PATCH 15/20] Fix three regressions surfaced during ecosystem
 re-baseline
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The chain-attr collection + outer-wrapper override (a358d40, 3dbff07)
introduced new FPs in three patterns that weren't covered by the
existing tests. All surfaced when re-baselining HDS / ember-power-
select against the latest tip.

1. blank.ts: void-element block-form guard.
   When the chain resolves a block-form component invocation
   (`<G.CheckboxField>...</G.CheckboxField>`) to a VOID native (e.g.
   `<input>`, the leaf in CheckboxField's template), the rename pass
   produced `<input>...</input>` — invalid HTML (void elements can't
   have content). HDS's form-complex.gts fired hundreds of `void-
   content` + `no-implicit-input-type` for these. Guard:
   `handleGlintSubstitution` now bails to transparent-blanking when
   `resolved` is void-and-block-form. Children float to the actual
   parent's content model — same as an unresolved component.

2. lib/glint.ts: gate the same-package outer-wrapper override on the
   declaration being TOP-LEVEL. The override walks the declaration
   file's first `<template>` block. That's correct for top-level TOC
   declarations (`const X: TOC<S> = <template>`), but produces wrong
   results for INNER-SCOPE bindings — a `{{let @x as |Group|}}`
   becomes `const [Group] = ...` inside the template-to-typescript
   output, and `findComponentDeclSourceFile` resolves Group's
   declFile back to the consumer file. Walking the consumer's first
   `<template>` block returns whatever wrapper happens to be there
   (e.g. `<ul>` for a power-select-options-style recursive template),
   not what `Group` actually renders. New helper
   `isTopLevelDeclaration` walks the declaration's parents for a
   SourceFile-direct `VariableStatement` / `ClassDeclaration` /
   `FunctionDeclaration` / etc; the override only runs when the
   declaration is top-level. Surfaced by ember-power-select's
   `<Group><Options>` recursive case (let-block-param).

3. lib/glint.ts: "essentially-all-elements" union threshold. When a
   component declares `Element: HTMLElementTagNameMap[keyof
   HTMLElementTagNameMap]` (the union of EVERY HTML element type),
   `matchElementTypeToTag` was picking the first matching branch
   arbitrarily — typically `<a>` or `<h1>` — and substituting the
   component to it, cascading FPs everywhere downstream. Treat union
   sizes >= 30 as "transparent" (children float to actual parent).
   HDS's `<HdsLayoutGrid>` uses this exact pattern; the showcase
   `page-layouts/grid/sub-sections/base-elements.gts` had 98 e-p-c
   findings that all clear with this gate. Threshold of 30 is well
   above realistic per-component declarations (5-10 union members
   are typical for "this component renders one of N specific tags")
   and well below the ~110 entries in HTMLElementTagNameMap.

Verified on real HDS / power-select files post-fix:
  HDS form-complex.gts:           hundreds of void-content/missing-type → 0
  HDS grid base-elements.gts:     98 element-permitted-content → 0
  HDS legal-links.gts:            still 0 (preserved win)
  power-select options.gts:       3 element-permitted-content → 0

168/168 tests pass.
---
 blank.ts     | 17 +++++++++++++
 lib/glint.ts | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 86 insertions(+), 1 deletion(-)

diff --git a/blank.ts b/blank.ts
index bbd2a5a..05eac8f 100644
--- a/blank.ts
+++ b/blank.ts
@@ -612,6 +612,23 @@ function handleGlintSubstitution(node: AST.ElementNode, ctx: Context): string |
 
   // Block-form: rename open and close tags in place. Children stay visible
   // to html-validate.
+  //
+  // Guard against block-form invocations whose resolved tag is VOID
+  // (e.g. `<G.CheckboxField>...</G.CheckboxField>` where the curried
+  // sub-component renders `<input ...attributes>`). Substituting open
+  // and close tags would produce `<input>...</input>` — invalid HTML
+  // (void elements can't have content). Bail to transparent-blanking
+  // instead so the children float to the actual parent's content
+  // model, same as an unresolved component. Inner-content semantics
+  // (e.g. validation against the input's content model) are
+  // unavailable for these substitutions; that's the same trade-off
+  // as the non-substituted path. The void's required attributes
+  // (e.g. `<input type=...>`) get checked via the addon's own
+  // template lint, not the consumer's substitution.
+  if (VOID_ELEMENTS.has(resolved)) {
+    blankComponentTagsTransparent(node, ctx);
+    return 'transparent';
+  }
   const elementStart = startOffset(node);
   const elementEnd = endOffset(node);
   const tagStart = elementStart + 1;
diff --git a/lib/glint.ts b/lib/glint.ts
index 6c7e14a..05ec2cd 100644
--- a/lib/glint.ts
+++ b/lib/glint.ts
@@ -646,6 +646,17 @@ function matchElementTypeToTag(
     }
   }
   if (allGenericBase) return 'transparent';
+  // "Essentially all elements" — when the union covers (almost) every
+  // HTMLElement type, the author has expressed "this component can
+  // render any element"; picking the first matching branch arbitrarily
+  // would substitute to whatever happened to be first (often `<a>` or
+  // `<h1>`) and cascade FPs into the consumer's content-model checks.
+  // Resolve to 'transparent' so children float to the actual parent.
+  // Surfaced by HDS's `<HdsLayoutGrid>` declaring
+  // `Element: HTMLElementTagNameMap[keyof HTMLElementTagNameMap]`.
+  if (branches.length >= ESSENTIALLY_ALL_ELEMENTS_THRESHOLD) {
+    return 'transparent';
+  }
   // Pick a single tag for unions: take the first matching branch.
   for (const branch of branches) {
     const name = branch.getSymbol()?.name;
@@ -656,6 +667,15 @@ function matchElementTypeToTag(
   return null;
 }
 
+// Threshold below which a union of HTML element types is treated as
+// "the author chose specific tags" (we resolve to one of them) and
+// above which it's treated as "the author chose effectively all tags"
+// (we resolve to 'transparent'). HTMLElementTagNameMap has ~110
+// entries; user-declared unions of "any of a handful" are typically
+// 5-10 elements. Pick a threshold well above realistic per-component
+// declarations but well below 110.
+const ESSENTIALLY_ALL_ELEMENTS_THRESHOLD = 30;
+
 // Recover the rendered tag from the *type* of the component-reference
 // expression itself — for cases where Glint's `emitComponent(...).element`
 // surfaces as `unknown`/`any` (for example yielded-curried block params like
@@ -988,7 +1008,18 @@ export function extractAttrTypeMap(filename: string, contents: string): Extracti
       // root and stash literal attributes for blank.ts to inject.
       if (emitCall) {
         const declFile = findComponentDeclSourceFile(ts, checker, emitCall);
-        if (declFile) {
+        // Skip the same-package outer-wrapper override when the
+        // declaration ISN'T a top-level statement in `declFile` —
+        // typically a let-block-param (`{{let @x as |Group|}}` becomes
+        // `const [Group] = ...` inside the template-to-typescript
+        // output). For these, declFile is the consumer file and
+        // walking its outer `<template>` block returns whatever
+        // happens to be at the file's root (often unrelated to what
+        // `Group` actually renders).
+        const symbol = getComponentSymbolFromEmitCall(ts, checker, emitCall);
+        const decl = symbol?.declarations?.[0];
+        const isTopLevel = decl ? isTopLevelDeclaration(ts, decl) : false;
+        if (declFile && isTopLevel) {
           const gtsPath = resolveGtsPath(declFile);
           if (gtsPath) {
             const roots = getSplattedRootsForFile(gtsPath);
@@ -1167,6 +1198,43 @@ function findComponentDeclSourceFile(
   return decl.getSourceFile().fileName;
 }
 
+// True when the component reference's declaration is a top-level
+// statement in its source file (e.g. `const X: TOC<S> = <template>`),
+// rather than an inner-scope binding (e.g. a let-block-param emitted
+// as `const [Group] = ...` inside the template-to-typescript output).
+//
+// Why we need this: the outer-wrapper override walks the declaration
+// file's first `<template>` block to find a wrapping native tag.
+// That's correct for top-level component declarations whose template
+// IS the file's first block, but produces wrong results for inner-
+// scope bindings — a `{{let @groupComponent as |Group|}}` would resolve
+// `<Group>`'s declFile back to the consumer file, and walking the
+// consumer's first `<template>` block returns whatever wrapper
+// happens to be there (often `<ul>` for a power-select-options-style
+// recursive template), not what `Group` actually renders.
+function isTopLevelDeclaration(ts: typeof TS, decl: TS.Declaration): boolean {
+  // VariableDeclaration → VariableDeclarationList → VariableStatement
+  // → SourceFile (when top-level).
+  // ClassDeclaration / FunctionDeclaration etc. → directly child of
+  // SourceFile.
+  let node: TS.Node | undefined = decl;
+  while (node) {
+    if (
+      node.kind === ts.SyntaxKind.VariableStatement ||
+      node.kind === ts.SyntaxKind.ClassDeclaration ||
+      node.kind === ts.SyntaxKind.FunctionDeclaration ||
+      node.kind === ts.SyntaxKind.InterfaceDeclaration ||
+      node.kind === ts.SyntaxKind.TypeAliasDeclaration ||
+      node.kind === ts.SyntaxKind.ExportAssignment
+    ) {
+      // Only top-level if the parent IS the SourceFile.
+      return node.parent?.kind === ts.SyntaxKind.SourceFile;
+    }
+    node = node.parent;
+  }
+  return false;
+}
+
 // Resolve the rendered tag (and splatted-root attrs) for a classic Ember
 // addon component imported as `import X from '<addon>/components/<name>'`
 // — addons whose template lives at `addon/templates/components/<name>.hbs`

From f6682d74a01f409cfc02db4a8bc696d63dc226e3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20R=C3=B8ed?= <johanroed@gmail.com>
Date: Fri, 8 May 2026 23:07:01 +0200
Subject: [PATCH 16/20] Address Copilot review (round 4): C16/C17 cache perf
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

C16 (lib/outer-wrapper-resolver.ts):
  `resolveOuterWrapperTagInner` only consulted/populated the per-
  filename cache when `depth === 0`, so the same wrapper file would be
  re-read and re-parsed every time it appeared as a nested wrapper.
  In large component graphs (e.g. design-system packages where many
  components wrap shared interactive primitives) this is noticeable
  IO. The result for a given filename is deterministic — it walks
  that file's first `<template>` block and recurses through its
  wrappers — so caching at all depths is safe. The cycle guard via
  `visited` still prevents recursing back into a file currently
  being walked higher up the call stack; it's a separate concern
  from cross-call caching.

C17 (lib/classic-resolver.ts):
  `findClassicComponent` re-did a full `readdirSync` + sort + per-
  package `isEmberAddonPackage` scan of each `node_modules` directory
  on every kebab-name lookup. With many distinct PascalCase tags in
  a `.hbs` template the cost was O(packages × tags). New
  `listAddonRootsIn` cache stores the sorted, addon-filtered list of
  package roots per `node_modules` path; subsequent lookups iterate
  the cached list and only pay the per-package hbs-probe cost
  (3 `existsSync` per addon per kebab-name). Per-name result cache
  unchanged.
---
 lib/classic-resolver.ts       | 110 ++++++++++++++++++++--------------
 lib/outer-wrapper-resolver.ts |  16 +++--
 2 files changed, 77 insertions(+), 49 deletions(-)

diff --git a/lib/classic-resolver.ts b/lib/classic-resolver.ts
index 8d0a189..8dc0e9e 100644
--- a/lib/classic-resolver.ts
+++ b/lib/classic-resolver.ts
@@ -73,6 +73,63 @@ function isEmberAddonPackage(pkgRoot: string): boolean {
   return result;
 }
 
+// Cache of pre-computed addon-package roots per `node_modules` path.
+// `findClassicComponent` walks a consumer's `node_modules` for every
+// PascalCase lookup; without this cache the readdir + sort + per-
+// package isEmberAddonPackage check would run anew on each call. With
+// it, scan once per `node_modules` directory and reuse for every
+// kebab-name lookup.
+//
+// Stored as the absolute paths to addon roots (sorted by name for
+// determinism), so callers can iterate without re-doing the scan.
+// pnpm-style symlinks are resolved into actual paths for stable
+// `isEmberAddonPackage` lookups (the same package may appear via
+// multiple symlinks; the cache is keyed on the symlink-target path's
+// `node_modules`).
+const addonRootsCache = new Map<string, string[]>();
+
+function listAddonRootsIn(nodeModules: string): string[] {
+  const cached = addonRootsCache.get(nodeModules);
+  if (cached !== undefined) return cached;
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(nodeModules, { withFileTypes: true });
+  } catch {
+    addonRootsCache.set(nodeModules, []);
+    return [];
+  }
+  entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  const addonRoots: string[] = [];
+  for (const entry of entries) {
+    // pnpm uses symlinks for packages — `isDirectory()` returns false
+    // on a symlink, so accept symlinks too. `fs.existsSync` /
+    // `readFileSync` below transparently follow links.
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+    if (entry.name.startsWith('.')) continue;
+    if (entry.name.startsWith('@')) {
+      // Scoped package — recurse one level.
+      const scopeRoot = path.join(nodeModules, entry.name);
+      let scopedEntries: fs.Dirent[];
+      try {
+        scopedEntries = fs.readdirSync(scopeRoot, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      scopedEntries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+      for (const scoped of scopedEntries) {
+        if (!scoped.isDirectory() && !scoped.isSymbolicLink()) continue;
+        const pkgRoot = path.join(scopeRoot, scoped.name);
+        if (isEmberAddonPackage(pkgRoot)) addonRoots.push(pkgRoot);
+      }
+      continue;
+    }
+    const pkgRoot = path.join(nodeModules, entry.name);
+    if (isEmberAddonPackage(pkgRoot)) addonRoots.push(pkgRoot);
+  }
+  addonRootsCache.set(nodeModules, addonRoots);
+  return addonRoots;
+}
+
 // Components our blank-step handles via the builtin map (not by-name
 // resolution). Skip these — they'd shadow the builtin substitution.
 const BUILTIN_COMPONENT_NAMES: ReadonlySet<string> = new Set([
@@ -118,6 +175,11 @@ function tryProbeAddon(addonRoot: string, kebabName: string): ComponentAttrs | n
 // Look up `kebabName` in every addon under each `node_modules/` walked
 // up from the consumer file. Returns the first match. Native-tag-only
 // guard mirrors PR #19's `resolveAddonHbsTemplate` behavior.
+//
+// Per-name cost is bounded by the cached addon-roots list (see
+// `listAddonRootsIn`) plus 3 `existsSync` per addon for the hbs probe.
+// The readdir + sort + per-package isEmberAddonPackage scan happens
+// once per `node_modules` directory and is reused across kebab names.
 function findClassicComponent(consumerFile: string, kebabName: string): ComponentAttrs | null {
   const cacheKey = `${path.dirname(consumerFile)}\0${kebabName}`;
   const cached = cache.get(cacheKey);
@@ -126,47 +188,8 @@ function findClassicComponent(consumerFile: string, kebabName: string): Componen
   for (;;) {
     const nodeModules = path.join(dir, 'node_modules');
     if (fs.existsSync(nodeModules)) {
-      let entries: fs.Dirent[];
-      try {
-        entries = fs.readdirSync(nodeModules, { withFileTypes: true });
-      } catch {
-        entries = [];
-      }
-      // Sort by name for deterministic resolution: `fs.readdirSync`
-      // returns entries in filesystem order, which varies across OS
-      // and filesystems. When two addons ship the same kebab-cased
-      // template, sort order picks a stable winner.
-      entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
-      for (const entry of entries) {
-        // pnpm uses symlinks for packages — `isDirectory()` returns
-        // false on a symlink, so accept symlinks too. The lookup below
-        // uses `fs.existsSync` which transparently follows links.
-        if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
-        if (entry.name.startsWith('.')) continue;
-        if (entry.name.startsWith('@')) {
-          // Scoped package — recurse one level.
-          const scopeRoot = path.join(nodeModules, entry.name);
-          let scopedEntries: fs.Dirent[];
-          try {
-            scopedEntries = fs.readdirSync(scopeRoot, { withFileTypes: true });
-          } catch {
-            continue;
-          }
-          scopedEntries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
-          for (const scoped of scopedEntries) {
-            if (!scoped.isDirectory() && !scoped.isSymbolicLink()) continue;
-            const pkgRoot = path.join(scopeRoot, scoped.name);
-            if (!isEmberAddonPackage(pkgRoot)) continue;
-            const result = tryProbeAddon(pkgRoot, kebabName);
-            if (result && isNativeTag(result.tag)) {
-              cache.set(cacheKey, result);
-              return result;
-            }
-          }
-          continue;
-        }
-        const pkgRoot = path.join(nodeModules, entry.name);
-        if (!isEmberAddonPackage(pkgRoot)) continue;
+      const addonRoots = listAddonRootsIn(nodeModules);
+      for (const pkgRoot of addonRoots) {
         const result = tryProbeAddon(pkgRoot, kebabName);
         if (result && isNativeTag(result.tag)) {
           cache.set(cacheKey, result);
@@ -220,10 +243,9 @@ export function buildClassicComponentTagMap(
   return { componentTagMap, componentAttrMap };
 }
 
-// Test-only: clear the in-memory by-name resolver caches (the
-// per-(consumerDir, kebabName) lookup cache and the per-package
-// "is an Ember addon" pre-filter cache).
+// Test-only: clear the in-memory by-name resolver caches.
 export function _clearClassicResolverCache(): void {
   cache.clear();
   isAddonCache.clear();
+  addonRootsCache.clear();
 }
diff --git a/lib/outer-wrapper-resolver.ts b/lib/outer-wrapper-resolver.ts
index 35643c6..a24bcbe 100644
--- a/lib/outer-wrapper-resolver.ts
+++ b/lib/outer-wrapper-resolver.ts
@@ -409,15 +409,21 @@ function resolveOuterWrapperTagInner(
 ): OuterWrapperResolution | null {
   if (depth > MAX_DEPTH) return null;
   if (visited.has(filename)) return null; // cycle guard
+  // The result for a given `filename` is deterministic (it walks the
+  // file's first `<template>` block and recurses through its
+  // wrappers), so it's safe to consult/populate the cache at any
+  // depth. The cycle guard via `visited` still prevents us from
+  // recursing into a file that's currently being walked higher up
+  // the call stack — a separate concern from cross-call caching.
   const cached = cache.get(filename);
-  if (cached !== undefined && depth === 0) return cached;
+  if (cached !== undefined) return cached;
   visited.add(filename);
 
   let contents: string;
   try {
     contents = fs.readFileSync(filename, 'utf8');
   } catch {
-    if (depth === 0) cache.set(filename, null);
+    cache.set(filename, null);
     return null;
   }
 
@@ -425,7 +431,7 @@ function resolveOuterWrapperTagInner(
   try {
     blocks = preprocessor.parse(contents, { filename });
   } catch {
-    if (depth === 0) cache.set(filename, null);
+    cache.set(filename, null);
     return null;
   }
 
@@ -459,7 +465,7 @@ function resolveOuterWrapperTagInner(
         attrs: levelAttrs,
         hasSplat: elementHasSplat(outermost),
       };
-      if (depth === 0) cache.set(filename, result);
+      cache.set(filename, result);
       return result;
     }
 
@@ -483,7 +489,7 @@ function resolveOuterWrapperTagInner(
         attrs: merged,
         hasSplat: recursed.hasSplat,
       };
-      if (depth === 0) cache.set(filename, result);
+      cache.set(filename, result);
       return result;
     }
   }

From a1c28bbd53536da59c9b1fd5c58582204268181b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20R=C3=B8ed?= <johanroed@gmail.com>
Date: Sat, 9 May 2026 01:42:57 +0200
Subject: [PATCH 17/20] Suppress element-permitted-content/parent on resolved
 curried-child wrappers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Surfaced during ecosystem re-baseline: HDS components like `<HdsTabs
as |T|>` resolve via Glint to a specific native tag (their splatted
root, e.g. `<div>`) but their template wraps `{{yield (hash Tab=...)}}`
inside a different native ancestor (`<ul role="tablist">`). The
curried sub-component `<T.Tab>` resolves via PR #18's
`aliasTypeArguments` to `<li>`. Static substitution puts `<li>`
directly under the wrapper's resolved `<div>`, FP-firing
`element-permitted-content` ("li under div") and the paired
`element-permitted-parent` ("li requires ul"). The runtime DOM is
fine: `<div>...<ul><li>...</li>...</ul>...</div>`.

Two refinements to `containsContentRestrictedStructuralChild`:

1. Recognize Glint-resolved-to-structural children, not just literal
   structural elements. A child that resolves to `<li>`/`<th>`/etc.
   counts the same as a literal `<li>`/`<th>` for this purpose.

2. Refine the wrapper-pinned gate so it only blocks suppression for
   LITERAL structural children, not for curried-resolved children.
   Case A (literal `<th>` inside resolved `<select>`) is a real bug
   we still catch — the runtime DOM puts `<th>` directly inside
   `<select>`. Case B (`<T.Tab>` inside resolved `<HdsTabs>`) is the
   yield-through pattern — runtime DOM nests `<li>` inside the
   addon's `<ul>`, not the wrapper's resolved `<div>`. Suppression
   triggers for B, not A.

Plus: also add `element-permitted-parent` to `disableForRules` when
the heuristic fires. The two rules are paired on misnesting (e.g.
`<li>` under `<div>` triggers BOTH "div doesn't allow li" AND "li
requires ul/ol/menu"); suppressing only one leaves half-noise.

Verified on HDS variants.gts (was 23 element-permitted-content + 23
element-permitted-parent) — 0 findings post-fix. Existing
`glint-resolved-no-suppression.gts` regression test still passes
(literal `<th>` under resolved `<select>` correctly fires).
---
 blank.ts | 73 +++++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 64 insertions(+), 9 deletions(-)

diff --git a/blank.ts b/blank.ts
index 05eac8f..0a1d3a7 100644
--- a/blank.ts
+++ b/blank.ts
@@ -1582,7 +1582,15 @@ function detectStructuralYieldRules(
           // multi-level cross-file yield-chain analysis (deferred).
           // Suppress the rule for the Source instead — same per-Source
           // suppression trade-off as the form/fieldset cases above.
+          //
+          // Both `element-permitted-content` and `element-permitted-
+          // parent` fire on the same misnesting (e.g. `<li>` under
+          // `<div>` triggers e-p-c "div doesn't allow li" AND e-p-p
+          // "li requires ul/ol/menu"). Suppress both — they're a
+          // matched pair and treating them separately would leave
+          // half-suppressed noise.
           out.push('element-permitted-content');
+          out.push('element-permitted-parent');
         }
         walk(stmt.children);
       }
@@ -1684,24 +1692,71 @@ function containsContentRestrictedStructuralChild(
   glintComponentTagMap: ReadonlyMap<string, string> | null | undefined,
   branchSelections?: ReadonlyMap<number, BranchChoice>,
 ): boolean {
-  // If Glint has resolved this wrapper to a native tag, no heuristic
-  // needed — the precise resolution wins and the rule fires (or
-  // doesn't) on the actual parent.
-  if (glintComponentTagMap && node.loc.start) {
-    const key = `${node.loc.start.line}:${node.loc.start.column}`;
-    const resolved = glintComponentTagMap.get(key);
-    if (resolved && resolved !== 'transparent') return false;
-  }
+  // Two cases trigger this suppression:
+  //
+  //  A) Wrapper is unresolved or resolved as 'transparent': we don't
+  //     know what tag wraps the yielded children at runtime. If any
+  //     child is a structural-child element (literal `<li>`/`<th>`/
+  //     ...) OR a curried sub-component that resolves to one, presume
+  //     the wrapper renders the structurally-correct parent (`<ul>`/
+  //     `<thead>`/...) via yield chain.
+  //
+  //  B) Wrapper resolves to a SPECIFIC native tag, AND has CURRIED
+  //     SUB-COMPONENT children that resolve to structural tags. This
+  //     is the `<HdsTabs as |T|><T.Tab>` pattern: `<HdsTabs>`
+  //     resolves to `<div>` (its splatted root), but its template
+  //     wraps `{{yield (hash Tab=...)}}` inside `<ul role="tablist">`.
+  //     The curried `<T.Tab>` resolves to `<li>` (via PR #18), but at
+  //     runtime that `<li>` lands inside the addon's `<ul>`, not the
+  //     outer `<div>`. Suppress.
+  //
+  // We DO NOT suppress when the wrapper resolves to a specific native
+  // tag AND structural children are LITERAL (case A's `literal-li-in-
+  // resolved-div` doesn't apply because case B excludes literals).
+  // Literal `<th>` inside `<C.Options>` resolved to `<select>` is the
+  // glint-resolved-no-suppression test case: a real bug we want to
+  // catch. The runtime DOM puts `<th>` directly inside `<select>`
+  // (which doesn't allow th); rule must fire.
   // Walk only the arm that matches what the blanker emits in this pass.
   // Without `selectBranch`, descending into both arms of a
   // `{{#if}}/{{else}}` would let one branch's structural children
   // trigger Source-wide suppression even when that branch isn't being
   // emitted — silently masking real `element-permitted-content`
   // violations in the active branch.
+  // Determine whether the wrapper itself resolves to a specific
+  // native tag (for case-B gating). We compute it once up front and
+  // pass into `check` as a closure binding.
+  const wrapperResolved =
+    glintComponentTagMap && node.loc.start
+      ? glintComponentTagMap.get(`${node.loc.start.line}:${node.loc.start.column}`)
+      : undefined;
+  const wrapperPinned =
+    typeof wrapperResolved === 'string' && wrapperResolved !== 'transparent';
+
   function check(stmts: ReadonlyArray<AST.Statement>): boolean {
     for (const stmt of stmts) {
       if (stmt.type === 'ElementNode') {
-        if (CONTENT_RESTRICTED_STRUCTURAL_CHILDREN.has(stmt.tag)) return true;
+        // (A) Native structural-child literally in source. Trigger
+        // suppression only when the wrapper isn't pinned — a pinned
+        // wrapper IS the runtime parent for literal children, so a
+        // literal `<th>` inside a resolved `<select>` is a real bug.
+        if (CONTENT_RESTRICTED_STRUCTURAL_CHILDREN.has(stmt.tag) && !wrapperPinned) {
+          return true;
+        }
+        // (B) Curried sub-component / component invocation that
+        // resolves to a structural tag. Trigger suppression in BOTH
+        // wrapper states — even when the wrapper resolves to a
+        // specific native tag, its template may wrap `{{yield (hash
+        // X=...)}}` in a different native ancestor (the HdsTabs
+        // pattern), so the runtime parent for the curried child
+        // isn't the wrapper's resolved tag.
+        if (glintComponentTagMap && stmt.loc.start) {
+          const childKey = `${stmt.loc.start.line}:${stmt.loc.start.column}`;
+          const childResolved = glintComponentTagMap.get(childKey);
+          if (childResolved && CONTENT_RESTRICTED_STRUCTURAL_CHILDREN.has(childResolved)) {
+            return true;
+          }
+        }
       } else if (stmt.type === 'BlockStatement') {
         const arm = selectBranch(stmt, branchSelections);
         if (arm && check(arm.body)) return true;

From 8f5939d56842411b9190f3759de842755e25f1d4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20R=C3=B8ed?= <johanroed@gmail.com>
Date: Sat, 9 May 2026 01:45:13 +0200
Subject: [PATCH 18/20] Address Copilot review (round 5): C18/C19/C20
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

C18 (blank.ts): the structural-yield-rules heuristic suppressed
  `element-permitted-content` for ANY non-native wrapper, including
  built-in components (`LinkTo`, `Input`, `Textarea`) which the
  blanker can always resolve via `lookupBuiltinComponent`. A
  `<LinkTo>` substituted to `<a>` in a `.hbs` (non-Glint) run with a
  literal `<li>` child is a real `<a><li>` bug we should catch — but
  the heuristic was silencing it. Add a builtin-component guard to
  the gate so suppression only applies to genuinely unresolvable
  wrappers.

C19 (lib/outer-wrapper-resolver.ts): the docstring on
  `resolveComponentImport` still claimed package imports resolve via
  "node_modules walk + package.json exports". That referred to the
  pre-fix behavior; the implementation only probes conventional
  `src/` paths (the inner `resolvePackageImport` docstring already
  reflects this; the outer one was missed in round 3). Updated.

C20 (lib/outer-wrapper-resolver.ts): one leftover `if (depth === 0)`
  on the final `cache.set(filename, null)` write. The result IS
  deterministic per filename (the function's own docstring notes
  this); cache the null at all depths so repeated lookups via
  different wrapper chains hit the cache.
---
 blank.ts                      |  1 +
 lib/outer-wrapper-resolver.ts | 14 +++++++++-----
 2 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/blank.ts b/blank.ts
index 0a1d3a7..0d9698d 100644
--- a/blank.ts
+++ b/blank.ts
@@ -1566,6 +1566,7 @@ function detectStructuralYieldRules(
           out.push('wcag/h71');
         } else if (
           !isNativeTag(stmt.tag) &&
+          !lookupBuiltinComponent(stmt.tag) &&
           containsContentRestrictedStructuralChild(stmt, glintComponentTagMap, branchSelections)
         ) {
           // Unresolvable PascalCase / dotted wrapper containing
diff --git a/lib/outer-wrapper-resolver.ts b/lib/outer-wrapper-resolver.ts
index a24bcbe..a9e537a 100644
--- a/lib/outer-wrapper-resolver.ts
+++ b/lib/outer-wrapper-resolver.ts
@@ -142,10 +142,14 @@ function findOutermostElement(ast: AST.Template): AST.ElementNode | null {
 //
 // Two import shapes are handled:
 //   1. Relative import (`./foo.gts`) — resolve directly.
-//   2. Package import (`@scope/pkg/components`) — resolve via
-//      `node_modules` walk + package.json `exports`, then if the
-//      resolved file is a barrel `.ts`, parse it for the re-export of
-//      `componentName` and follow that.
+//   2. Package import (`@scope/pkg/components`) — walk `node_modules`
+//      upward and probe a fixed set of source-style paths
+//      (`src/<sub>.{gts,gjs,ts}`, `src/<sub>/index.*`, plus a few
+//      bare paths at the package root). We do NOT read the package's
+//      `package.json` `exports`/`main`; we deliberately prefer source
+//      files over compiled dist so we can read original `<template>`
+//      blocks. If the resolved file is a barrel `.ts`, parse it for
+//      the re-export of `componentName` and follow that.
 //
 // Returns null when:
 //   - The import doesn't exist in the file.
@@ -494,7 +498,7 @@ function resolveOuterWrapperTagInner(
     }
   }
 
-  if (depth === 0) cache.set(filename, null);
+  cache.set(filename, null);
   return null;
 }
 

From fd7fb2a7f00c4fc895a2389096aab0c954465b70 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20R=C3=B8ed?= <johan@fremby.no>
Date: Sat, 9 May 2026 02:19:55 +0200
Subject: [PATCH 19/20] Extend wcag/h32, wcag/h71, and form-submit suppression
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three connected refinements surfaced by ecosystem re-baseline on HDS:

1. detectStructuralYieldRules now matches `<form>` / `<fieldset>`
   via the resolved tag, not just the literal source tag. HDS-style
   `<HdsFormFieldset>` substitutes to `<fieldset>` in the blanked
   output but the heuristic was only checking literal `<fieldset>`,
   so the per-Source `wcag/h71` suppression directive never got
   emitted and the rule FP-fired on the substituted fieldset
   (which lacks a static `<legend>` because the addon renders one
   inside its own template). Same fix for `<form>`/wcag/h32.

2. elementYieldsAndLacksSubmit now treats DOTTED invocations
   (`<F.Body>`, `<G.Item>`, ...) as opaque content sources that may
   contain submit. These are curried sub-components yielded from
   the wrapper — their content is supplied at the consumer of the
   WRAPPER, not at the form's site. Without this, a form whose
   submit lives in a slotted-from-outside block would FP-fire
   wcag/h32 (HDS's flyout-with-form pattern: the form is inside a
   `CodeFragmentWithTrigger` whose template wraps the form in
   `<HdsFlyout as |F|>` and yields the consumer's `<:flyout>`
   block content into it).

Verified on HDS:
  checkbox/group.gts:    wcag/h71 1 → 0
  flyout/demo.gts:       wcag/h32 1 → 0
---
 blank.ts | 36 ++++++++++++++++++++++++++++--------
 1 file changed, 28 insertions(+), 8 deletions(-)

diff --git a/blank.ts b/blank.ts
index 0d9698d..127e644 100644
--- a/blank.ts
+++ b/blank.ts
@@ -1547,7 +1547,19 @@ function detectStructuralYieldRules(
         continue;
       }
       if (stmt.type === 'ElementNode') {
-        if (stmt.tag === 'form') {
+        // Resolved tag — for PascalCase / dotted invocations, this
+        // is what the element will substitute to in the blanked
+        // output. The form/fieldset heuristics need to fire whether
+        // the consumer wrote `<form>`/`<fieldset>` literally or a
+        // component invocation that resolves to one (e.g.
+        // `<HdsFormFieldset>` → `<fieldset>`); without this, the
+        // suppression directives don't get emitted and html-validate
+        // FP-fires `wcag/h32`/`wcag/h71` on the substituted output.
+        const stmtKey = stmt.loc.start ? `${stmt.loc.start.line}:${stmt.loc.start.column}` : null;
+        const stmtResolved =
+          (isNativeTag(stmt.tag) ? stmt.tag : null) ||
+          (stmtKey ? glintComponentTagMap?.get(stmtKey) : undefined);
+        if (stmtResolved === 'form') {
           if (
             formHasInputModifier(stmt) ||
             elementYieldsAndLacksSubmit(
@@ -1560,7 +1572,7 @@ function detectStructuralYieldRules(
             out.push('wcag/h32');
           }
         } else if (
-          stmt.tag === 'fieldset' &&
+          stmtResolved === 'fieldset' &&
           elementYieldsAndLacksLegend(stmt, branchSelections)
         ) {
           out.push('wcag/h71');
@@ -1832,15 +1844,23 @@ function elementYieldsAndLacksSubmit(
         // Track unresolved PascalCase / dotted component invocations.
         // These are candidates for "may contain submit" suppression
         // when the form has no other static submit. Native tags and
-        // builtins are excluded. Glint-resolved entries are excluded
-        // ONLY when Glint pinned a concrete native tag — entries
-        // mapped to `'transparent'` mean "Glint couldn't pin a tag"
-        // and the component might still render submit at runtime, so
-        // those count as unresolved for this purpose.
+        // builtins are excluded. Two cases qualify:
+        //   - Glint-resolved entries are excluded ONLY when Glint
+        //     pinned a concrete native tag — entries mapped to
+        //     `'transparent'` mean "Glint couldn't pin a tag" and
+        //     the component might still render submit at runtime.
+        //   - Dotted invocations (`<F.Body>`, `<G.Item>`, ...) are
+        //     curried sub-components yielded from the wrapper — their
+        //     content is supplied at the consumer of the WRAPPER, not
+        //     here, so we can't see what's inside. Treat as
+        //     potentially containing a submit; otherwise a form whose
+        //     submit lives in a slotted-from-outside block would FP-
+        //     fire (HDS's flyout-with-form pattern).
         if (!isNativeTag(stmt.tag) && !lookupBuiltinComponent(stmt.tag)) {
+          const isDotted = stmt.tag.includes('.');
           const key = stmt.loc.start ? `${stmt.loc.start.line}:${stmt.loc.start.column}` : null;
           const resolved = key ? glintComponentTagMap?.get(key) : undefined;
-          if (resolved === undefined || resolved === 'transparent') {
+          if (isDotted || resolved === undefined || resolved === 'transparent') {
             hasUnresolvedComponent = true;
           }
         }

From 109fa19719dd745a8ee69dac80700dd96e080895 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20R=C3=B8ed?= <johan@fremby.no>
Date: Sat, 9 May 2026 08:02:44 +0200
Subject: [PATCH 20/20] Dual-tag substitution: prefer yield-nearest-ancestor
 over outer wrapper
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The general fix that subsumes most of the per-rule whack-a-mole. We
were substituting components to a SINGLE tag (the outer wrapper, the
splatted-root, or Glint's leaf type) — but a component's template
has a STRUCTURE, not just a tag:

  HdsTabs's template:
    <div ...attributes>           ← outer (Element type → 'div')
      <div class="...">
        <ul role="tablist">       ← yield-nearest-ancestor
          {{yield (hash Tab=...)}}
        </ul>
      </div>
    </div>

The OUTER tag determines what the consumer's PARENT context sees.
The YIELD-NEAREST-ANCESTOR determines what CHILDREN are validated
against. They can differ; today we picked one and got FPs whenever
the choice mismatched.

Two changes:

1. `lib/outer-wrapper-resolver.ts` now ALSO computes the
   yield-nearest-ancestor by walking the AST tracking the element
   stack and locating each `{{yield}}` / `{{has-block}}` mustache.
   When the yield's ancestor is a PascalCase wrapper, recurses into
   that wrapper (consumer-yielded content passes through ITS yield,
   so the actual native ancestor is reached transitively). The
   `OuterWrapperResolution` interface gained `yieldAncestorTag` and
   `yieldAncestorAttrs`.

   Two recursions in one walk (outer-wrapper + yield-ancestor) need
   distinct cycle tracking; the secondary recursion clones the
   `visited` set so it doesn't pollute the first.

   Multi-template-file guard: when a file has multiple `<template>`
   blocks (e.g. several inline TOC consts + a default export), we'd
   have to match each to the requested component. We can't yet — bail
   to null. Cross-file paths (one-template-per-file is the dominant
   shape) still work.

2. `lib/glint.ts` adds `chooseSubstitutionFromResolution`. Heuristic:
     - If outer is in `STRUCTURAL_CHILD_TAGS` (`<li>`, `<tr>`,
       `<option>`, etc. — tags that REQUIRE a specific parent),
       keep outer. Dropping it would break the consumer's parent-
       context (`<HdsAppFooterLink>` substituted to `<a>` under
       `<ul>` would fire e-p-c, but to `<li>` it's fine).
     - Otherwise (outer is permissive — `<div>`, `<span>`, etc.) AND
       yield-ancestor is a different native, prefer the yield-
       ancestor. Children validation hinges on what wraps them at
       runtime; a `<div>` lets `<li>`-yielded children sit under
       `<div>` and FP-fire e-p-c, while `<ul>` correctly accepts
       them.

Verified on real ecosystem files:
  HDS variants.gts (was 23×e-p-c + 23×e-p-p):     0
  HDS legal-links (li outer kept):                preserved 0
  HDS filter-bar/clear-button (a yield-ancestor): preserved 0
  HDS form/checkbox/group:                        preserved 0
  ember-website classic-card:                     preserved 0
  Local glint-resolved-no-suppression test:       still fires 1 (literal th)
---
 lib/glint.ts                  | 106 ++++++++++++++++-----
 lib/outer-wrapper-resolver.ts | 169 +++++++++++++++++++++++++++++++++-
 2 files changed, 252 insertions(+), 23 deletions(-)

diff --git a/lib/glint.ts b/lib/glint.ts
index 05ec2cd..ef13f0f 100644
--- a/lib/glint.ts
+++ b/lib/glint.ts
@@ -545,6 +545,79 @@ const GENERIC_BASE_ELEMENT_TYPES: ReadonlySet<string> = new Set([
   'MathMLElement',
 ]);
 
+// Pick the substitution tag/attrs from an `OuterWrapperResolution`.
+//
+// Heuristic: if the outer wrapper tag is structurally meaningful
+// (in STRUCTURAL_CHILD_TAGS — `<li>`, `<tr>`, etc.), keep outer;
+// the consumer-side parent-context check matters and dropping outer
+// would let arbitrary content sit directly under (e.g.) `<ul>`.
+//
+// Otherwise (outer is permissive — `<div>`, `<span>`, `<form>`, etc.)
+// AND the resolution computed a different yield-ancestor: prefer the
+// yield-ancestor. The children's content-model validation hinges on
+// what wraps them at runtime; for a component like `<HdsTabs>` whose
+// template is `<div>...<ul>{{yield}}</ul>...</div>`, the `<ul>` is
+// where children land — using `<div>` lets `<li>`-yielded children
+// sit under `<div>` and FP-fire `element-permitted-content`.
+//
+// Returns the chosen tag + attrs + hasSplat. The caller uses these
+// for both `componentTagMap` and `componentAttrMap`.
+function chooseSubstitutionFromResolution(
+  res: { tag: string; attrs: Record<string, string>; hasSplat: boolean; yieldAncestorTag?: string | null; yieldAncestorAttrs?: Record<string, string> },
+): { tag: string; attrs: Record<string, string>; hasSplat: boolean } {
+  const yieldTag = res.yieldAncestorTag;
+  if (
+    yieldTag &&
+    yieldTag !== res.tag &&
+    !STRUCTURAL_CHILD_TAGS.has(res.tag) &&
+    isNativeTag(yieldTag)
+  ) {
+    return {
+      tag: yieldTag,
+      attrs: res.yieldAncestorAttrs ?? {},
+      // The yield-ancestor accepts whatever consumer-yielded content
+      // flows through, so it always behaves as having content (akin
+      // to a splatted root for child-content purposes).
+      hasSplat: true,
+    };
+  }
+  return { tag: res.tag, attrs: res.attrs, hasSplat: res.hasSplat };
+}
+
+// Tags whose role on the consumer's parent context is structurally
+// meaningful — they require specific parents (`<li>` requires
+// `<ul>`/`<ol>`/`<menu>`, etc.). When a component's outer wrapper is
+// one of these, KEEP the outer for substitution: dropping it would
+// break the consumer's parent-context validation (e.g. losing `<li>`
+// would let arbitrary content sit directly under `<ul>`).
+//
+// For other outer wrappers (`<div>`, `<span>`, `<form>`, etc. — tags
+// that accept flow content broadly), prefer the yield-nearest-
+// ancestor tag (when it differs and is more restrictive). The
+// children's content-model validation hinges on what wraps them at
+// runtime, which is the yield-ancestor in the addon's template, not
+// the outermost div.
+//
+// Mirrors `CONTENT_RESTRICTED_STRUCTURAL_CHILDREN` in blank.ts (these
+// are the same tags — kept here because lib/glint.ts shouldn't depend
+// on the heuristic-suppression set).
+const STRUCTURAL_CHILD_TAGS: ReadonlySet<string> = new Set([
+  'option',
+  'optgroup',
+  'th',
+  'td',
+  'tr',
+  'thead',
+  'tbody',
+  'tfoot',
+  'caption',
+  'colgroup',
+  'col',
+  'li',
+  'legend',
+  'summary',
+]);
+
 function buildElementTypeToTag(ts: typeof TS, program: TS.Program): Map<string, string> {
   const map = new Map<string, string>();
   const tagNameMaps = ['HTMLElementTagNameMap', 'SVGElementTagNameMap', 'MathMLElementTagNameMap'];
@@ -1064,22 +1137,14 @@ export function extractAttrTypeMap(filename: string, contents: string): Extracti
             const currentResolved = componentTagMap.get(key);
             sameTransitivePackageOuterRan = true;
             if (outerWrapper !== null && isNativeTag(outerWrapper.tag)) {
-              if (outerWrapper.tag !== currentResolved) {
-                componentTagMap.set(key, outerWrapper.tag);
+              const chosen = chooseSubstitutionFromResolution(outerWrapper);
+              if (chosen.tag !== currentResolved) {
+                componentTagMap.set(key, chosen.tag);
               }
-              // Always update componentAttrMap with the chain's
-              // accumulated attrs — even when the leaf tag matches the
-              // current resolution, the chain's deeper attrs (e.g. an
-              // `<a href={{@href}}>` in a wrapper's wrapper) are what
-              // make rules like `aria-label-misuse` pass. Without these,
-              // we'd inject only the SPLATTED-ROOT level's attrs (which
-              // for a non-native splatted root would be the wrapper's
-              // literal/mustache attrs only, missing the ultimately-
-              // rendered native's).
               componentAttrMap.set(key, {
-                tag: outerWrapper.tag,
-                attrs: outerWrapper.attrs,
-                hasSplat: outerWrapper.hasSplat,
+                tag: chosen.tag,
+                attrs: chosen.attrs,
+                hasSplat: chosen.hasSplat,
               });
             }
           }
@@ -1125,15 +1190,14 @@ export function extractAttrTypeMap(filename: string, contents: string): Extracti
         const outerFromImport = resolveOuterWrapperFromConsumerImport(filename, componentName);
         const currentResolved = componentTagMap.get(key);
         if (outerFromImport !== null && isNativeTag(outerFromImport.tag)) {
-          if (outerFromImport.tag !== currentResolved) {
-            componentTagMap.set(key, outerFromImport.tag);
+          const chosen = chooseSubstitutionFromResolution(outerFromImport);
+          if (chosen.tag !== currentResolved) {
+            componentTagMap.set(key, chosen.tag);
           }
-          // Override componentAttrMap with the chain's accumulated
-          // attrs (see same-package branch above for rationale).
           componentAttrMap.set(key, {
-            tag: outerFromImport.tag,
-            attrs: outerFromImport.attrs,
-            hasSplat: outerFromImport.hasSplat,
+            tag: chosen.tag,
+            attrs: chosen.attrs,
+            hasSplat: chosen.hasSplat,
           });
         }
       }
diff --git a/lib/outer-wrapper-resolver.ts b/lib/outer-wrapper-resolver.ts
index a9e537a..c2489a6 100644
--- a/lib/outer-wrapper-resolver.ts
+++ b/lib/outer-wrapper-resolver.ts
@@ -73,6 +73,34 @@ export interface OuterWrapperResolution {
   // logic that depends on splat-presence (e.g. `lookupComponentAttr`'s
   // builtin-fallback in blank.ts) sees the right value.
   hasSplat: boolean;
+  // Optional: the native tag that is the NEAREST ancestor of `{{yield}}`
+  // in the addon's template chain. When this differs from `tag`
+  // (the outer wrapper), the consumer's children are validated
+  // against `yieldAncestorTag` at runtime — substituting to `tag`
+  // alone would put children directly inside it instead of the
+  // intermediate structure.
+  //
+  // Example:
+  //   HdsTabs's template:
+  //     <div ...attributes>
+  //       <div class="...">
+  //         <ul role="tablist">{{yield (hash Tab=...)}}</ul>
+  //       </div>
+  //     </div>
+  //
+  //   tag = 'div' (outermost native).
+  //   yieldAncestorTag = 'ul' ({{yield}}'s nearest native ancestor).
+  //
+  // For `<HdsAppFooterLink>` whose template is
+  //   <HdsAppFooterItem><HdsLinkInline ...>{{yield}}</HdsLinkInline></HdsAppFooterItem>
+  // tag = 'li' (via recursing into HdsAppFooterItem) and
+  // yieldAncestorTag = 'a' (via recursing into HdsLinkInline).
+  //
+  // null when {{yield}} isn't found or its ancestor chain is
+  // unresolvable. In that case the caller falls back to using `tag`
+  // for both contexts.
+  yieldAncestorTag?: string | null;
+  yieldAncestorAttrs?: Record<string, string>;
 }
 
 // Cache resolved outer-wrappers per absolute filename. Process-
@@ -104,6 +132,78 @@ const MAX_DEPTH = 8;
 //   2. Else the first resolvable PascalCase wrapper.
 //
 // Returns null if no usable element exists.
+// Find the NEAREST native-element ancestor of any `{{yield}}` (or
+// `{{has-block}}`) mustache in the template. Walks the AST tracking
+// the element-node stack; when a yield mustache is encountered,
+// looks at the most-recently-pushed native element.
+//
+// If the yield's nearest element ancestor is a PascalCase wrapper
+// (not native), returns that wrapper — the caller recurses into it
+// (the wrapper passes consumer-yielded content through ITS own
+// yield, so the actual native ancestor is reached transitively).
+//
+// Returns:
+//   - { tag: nativeTag, attrs: literal/mustache attrs } when found.
+//   - { wrapperTag: 'PascalCase' } when nearest is a wrapper —
+//     caller recurses.
+//   - null when no yield in template, or yield has no element ancestor.
+type YieldAncestorRaw =
+  | { kind: 'native'; node: AST.ElementNode }
+  | { kind: 'wrapper'; tag: string }
+  | null;
+
+function findYieldNearestElement(ast: AST.Template): YieldAncestorRaw {
+  let result: YieldAncestorRaw = null;
+  const elementStack: AST.ElementNode[] = [];
+  function isUnresolvable(tag: string): boolean {
+    return tag.includes('.') || tag.startsWith(':');
+  }
+  function visit(stmts: ReadonlyArray<AST.Statement | AST.TopLevelStatement>): void {
+    for (const stmt of stmts) {
+      if (result !== null) return;
+      if (stmt.type === 'MustacheStatement') {
+        if (
+          stmt.path.type === 'PathExpression' &&
+          (stmt.path.original === 'yield' || stmt.path.original === 'has-block')
+        ) {
+          // Find nearest native ancestor on the stack. If none is
+          // native, take the nearest non-unresolvable PascalCase
+          // wrapper (caller will recurse into it).
+          for (let i = elementStack.length - 1; i >= 0; i--) {
+            const node = elementStack[i]!;
+            if (isNativeTag(node.tag)) {
+              result = { kind: 'native', node };
+              return;
+            }
+            if (!isUnresolvable(node.tag)) {
+              result = { kind: 'wrapper', tag: node.tag };
+              return;
+            }
+          }
+          // Yield with no element ancestor (top-level yield) — leave
+          // result null.
+          return;
+        }
+        continue;
+      }
+      if (stmt.type === 'ElementNode') {
+        elementStack.push(stmt);
+        visit(stmt.children);
+        elementStack.pop();
+        continue;
+      }
+      if (stmt.type === 'BlockStatement') {
+        visit(stmt.program.body);
+        if (result !== null) return;
+        if (stmt.inverse) visit(stmt.inverse.body);
+        continue;
+      }
+    }
+  }
+  visit(ast.body);
+  return result;
+}
+
 function findOutermostElement(ast: AST.Template): AST.ElementNode | null {
   let firstNative: AST.ElementNode | null = null;
   let firstResolvableWrapper: AST.ElementNode | null = null;
@@ -439,6 +539,20 @@ function resolveOuterWrapperTagInner(
     return null;
   }
 
+  // Multi-template-file guard: when a file contains MULTIPLE
+  // `<template>` blocks (e.g. several TOC declarations + a default
+  // export), we'd have to match each block to the component the
+  // caller is asking about — which we can't do without a component-
+  // name → block index mapping. Picking the first block silently
+  // returns the WRONG component's resolution. Bail to null instead;
+  // the cross-file path (one-template-per-file is the dominant
+  // shape) still works.
+  const templateBlocks = blocks.filter((b) => b.tagName === 'template');
+  if (templateBlocks.length !== 1) {
+    cache.set(filename, null);
+    return null;
+  }
+
   for (const block of blocks) {
     if (block.tagName !== 'template') continue;
     let ast: AST.Template;
@@ -463,12 +577,52 @@ function resolveOuterWrapperTagInner(
     // chain wrapper.
     const levelAttrs = literalAttrs(outermost);
 
+    // Find {{yield}}'s nearest native ancestor IN THIS LEVEL'S
+    // template (separate from the outer-wrapper resolution). May be:
+    //   - A native: that's our yield-ancestor, period.
+    //   - A PascalCase wrapper: we need to recurse into it (the
+    //     wrapper passes consumer-yielded content through its own
+    //     yield, so the actual native ancestor is reached
+    //     transitively).
+    //   - null: no yield in this template.
+    const yieldRaw = findYieldNearestElement(ast);
+    let yieldAncestorTag: string | null = null;
+    let yieldAncestorAttrs: Record<string, string> = {};
+    if (yieldRaw?.kind === 'native') {
+      yieldAncestorTag = yieldRaw.node.tag;
+      yieldAncestorAttrs = literalAttrs(yieldRaw.node);
+    } else if (yieldRaw?.kind === 'wrapper') {
+      const wrapperImport = resolveComponentImport(filename, yieldRaw.tag);
+      if (wrapperImport) {
+        // Clone the `visited` set so the wrapper's recursion doesn't
+        // pollute the outer-wrapper recursion that runs below in the
+        // same call. The two recursions are distinct cycle-tracking
+        // concerns; sharing `visited` would mark already-walked files
+        // as cyclic when re-entered for the outer-wrapper search.
+        const wrapperRes = resolveOuterWrapperTagInner(wrapperImport, new Set(visited), depth + 1);
+        if (wrapperRes) {
+          // The recursed wrapper's `yieldAncestorTag` (if known) is
+          // the actual native ancestor of consumer-yielded content.
+          // Fall back to the wrapper's `tag` if it didn't compute
+          // a yield ancestor.
+          yieldAncestorTag = wrapperRes.yieldAncestorTag ?? wrapperRes.tag;
+          yieldAncestorAttrs = wrapperRes.yieldAncestorTag
+            ? wrapperRes.yieldAncestorAttrs ?? {}
+            : wrapperRes.attrs;
+        }
+      }
+    }
+
     if (isNativeTag(outermost.tag)) {
-      const result = {
+      const result: OuterWrapperResolution = {
         tag: outermost.tag,
         attrs: levelAttrs,
         hasSplat: elementHasSplat(outermost),
       };
+      if (yieldAncestorTag !== null) {
+        result.yieldAncestorTag = yieldAncestorTag;
+        result.yieldAncestorAttrs = yieldAncestorAttrs;
+      }
       cache.set(filename, result);
       return result;
     }
@@ -488,11 +642,22 @@ function resolveOuterWrapperTagInner(
       // Merge attrs: outer wrapper level's attrs UNDER the recursed
       // attrs (inner wins on conflicts — closer to the rendered DOM).
       const merged = { ...levelAttrs, ...recursed.attrs };
-      const result = {
+      const result: OuterWrapperResolution = {
         tag: recursed.tag,
         attrs: merged,
         hasSplat: recursed.hasSplat,
       };
+      // Prefer THIS level's yield-ancestor when present (our yield
+      // is wrapped by THIS template's elements). Fall back to the
+      // recursed wrapper's yieldAncestor if our level didn't have
+      // its own yield.
+      if (yieldAncestorTag !== null) {
+        result.yieldAncestorTag = yieldAncestorTag;
+        result.yieldAncestorAttrs = yieldAncestorAttrs;
+      } else if (recursed.yieldAncestorTag) {
+        result.yieldAncestorTag = recursed.yieldAncestorTag;
+        result.yieldAncestorAttrs = recursed.yieldAncestorAttrs;
+      }
       cache.set(filename, result);
       return result;
     }