blank.ts

import { traverse } from '@glimmer/syntax';
import { parseTemplate } from './lib/parse-template.js';
import type { AST } from '@glimmer/syntax';

// At runtime, AST node `loc` fields are `SourceSpan` instances that
// expose `getStart()` / `getEnd()` returning a `SourceOffset` with a
// `.offset` byte-position. The public `SourceLocation` type only
// declares `start`/`end` as `Position { line, column }` (no offset),
// and `SourceSpan` itself isn't re-exported at the package's top level.
// We need byte offsets for length-preserved rewrites — declare the
// minimum shape we rely on and cast through it at access points.
interface SpanLike {
  getStart(): { offset: number };
  getEnd(): { offset: number };
}
function startOffset(node: { loc: AST.SourceLocation }): number {
  return (node.loc as unknown as SpanLike).getStart().offset;
}
function endOffset(node: { loc: AST.SourceLocation }): number {
  return (node.loc as unknown as SpanLike).getEnd().offset;
}

// Register an attribute injection at the given source-text offset.
// First-write-wins on (offset, attr) — matches the prior `*SplatOffsets`
// channels' behavior (which were Sets by construction or used .has()
// checks before .set()).
function addAttrInjection(
  registry: Map<number, AttrInjection[]>,
  offset: number,
  attr: string,
  value: string | null,
): void {
  let arr = registry.get(offset);
  if (!arr) {
    arr = [];
    registry.set(offset, arr);
  }
  if (!arr.some((a) => a.attr === attr)) {
    arr.push({ attr, value });
  }
}

function hasAttrInjection(
  registry: Map<number, AttrInjection[]>,
  offset: number,
  attr: string,
): boolean {
  return registry.get(offset)?.some((a) => a.attr === attr) ?? false;
}
import htmlTags from 'html-tags';
import svgTags from 'svg-tags';
import { mathmlTagNames } from 'mathml-tag-names';
import html5Schema from 'html-validate/elements/html5';
import type { MetaDataTable } from 'html-validate';

import { lookupBuiltinComponent } from './lib/builtin-components.js';
import type { ComponentAttrs } from './lib/builtin-components.js';
import { STRUCTURAL_CHILD_TAGS as CONTENT_RESTRICTED_STRUCTURAL_CHILDREN } from './lib/element-sets.js';
import type { AttrTypeInfo } from './lib/cache.js';
import { DYNAMIC_VALUE_PLACEHOLDER, isDynamicValuePlaceholder } from './lib/dynamic-value.js';

// ---------------------------------------------------------------------------
// Schema-derived metadata (computed once at module load).
// ---------------------------------------------------------------------------

// Native boolean attributes per HTML5. Sourced from html-validate's
// elements/html5 schema (the same data we use for attribute-allowed-values).
// Used to decide how a bare-mustache value gets emitted: a boolean attr
// resolves at runtime to either presence-only (when truthy) or omit (when
// falsy), per docs/glimmer-attribute-behavior.md. We emit presence-only —
// the canonical "rendered" form — letting attribute-boolean-style stay
// enabled. Non-boolean bare-mustache attrs use the empty-quoted +
// processAttribute DynamicValue path.
const html5: MetaDataTable = html5Schema;

const BOOLEAN_ATTR_KEYS: ReadonlySet<string> = (() => {
  const set = new Set<string>();
  for (const [tag, schema] of Object.entries(html5)) {
    const attrs = schema?.attributes ?? {};
    for (const [name, meta] of Object.entries(attrs)) {
      if (meta && (meta as { boolean?: boolean }).boolean === true) {
        set.add(`${tag}/${name}`);
      }
    }
  }
  return set;
})();

// Same authoritative element-name list as eslint-plugin-ember's
// `isNativeElement` util (lib/utils/is-native-element.js).
const NATIVE_TAGS: ReadonlySet<string> = new Set([
  ...htmlTags,
  ...svgTags,
  ...mathmlTagNames,
]);

// HTML5 void elements (no closing tag, no children). Used to choose
// between in-place tag rename (void: keeps parent attrs visible) and
// open+close-pair emission (non-void: needs explicit content).
// Derived from html-validate's HTML5 metadata so we follow its
// `void: true` flag rather than maintaining a parallel list.
const VOID_ELEMENTS: ReadonlySet<string> = new Set(
  Object.entries(html5Schema as MetaDataTable)
    .filter(([, meta]) => (meta as { void?: boolean })?.void === true)
    .map(([tag]) => tag),
);

function isBooleanAttr(tagName: string, attrName: string): boolean {
  return BOOLEAN_ATTR_KEYS.has(`${tagName}/${attrName}`) || BOOLEAN_ATTR_KEYS.has(`*/${attrName}`);
}

// Returns the html-validate enum constraint for an attribute on a given
// element, or null when the attribute has no enum or isn't in the schema.
// Filters out regex-string entries (which html-validate uses for numerics
// like maxlength) — we only handle pure-string enums for branch validation.
function attrEnumFor(tagName: string, attrName: string): string[] | null {
  const schemas = [html5[tagName], html5['*']];
  for (const schema of schemas) {
    const meta = schema?.attributes?.[attrName] as { enum?: unknown[] } | undefined;
    if (meta && Array.isArray(meta.enum)) {
      const strings = meta.enum.filter(
        (v): v is string => typeof v === 'string' && !v.startsWith('/'),
      );
      if (strings.length > 0) {
        return strings;
      }
    }
  }
  return null;
}

// For a string-literal-union from Glint (e.g. ['text','select','number','date']),
// against an html-validate enum (e.g. valid <input type> values), return the
// first union member NOT in the enum — that's the bug we surface. If all
// values are valid, return the first (status quo).
//
// Example: `<input type={{@x}}>` where @x: 'text'|'select' → enum has
// 'text' but not 'select' → emit 'select' so attribute-allowed-values fires.
function pickRevealingValue(unionValues: string[], tagName: string, attrName: string): string {
  const fallback = unionValues[0] ?? '';
  const enumValues = attrEnumFor(tagName, attrName);
  if (!enumValues) {
    return fallback;
  }
  const enumSet = new Set(enumValues.map((v) => v.toLowerCase()));
  for (const value of unionValues) {
    if (!enumSet.has(value.toLowerCase())) {
      return value;
    }
  }
  return fallback;
}

function isNativeTag(tag: string): boolean {
  return NATIVE_TAGS.has(tag);
}

// Predicate for "this ElementNode is a Glimmer component invocation
// the resolver should attempt to handle" — covers PascalCase
// (`<HdsButton>`), dotted (`<X.Y>`, `<o.Section>`), `<this.X>`, and
// let-element bindings. Excludes:
//   - Known HTML5 tags (`<div>`, `<span>`, …) — pure native elements.
//   - Named-block slots (`<:body>`, `<:header>`) — Glimmer slot syntax
//     that's a placeholder for yielded content, not a component.
//   - `@`-prefixed tags (`<@foo>`) — arg-bound invocations; we can't
//     name-resolve them and Glimmer normalizes them via consumerArgs
//     flow, not the resolver.
// Mirrors Glimmer's internal `isComponent` predicate at
// @glimmer/syntax/lib/v2/normalize.ts:818 (not exported); the
// ember-eslint-parser carries its own local copy at src/parser/
// transforms.js:76 for the same reason.
function isComponentTag(tag: string): boolean {
  if (!tag) return false;
  if (tag.startsWith(':') || tag.startsWith('@')) return false;
  return !isNativeTag(tag);
}

// ---------------------------------------------------------------------------
// AST predicates and small utilities.
// ---------------------------------------------------------------------------

function isGlimmerOnlyAttr(name: string | undefined | null): boolean {
  if (!name) return false;
  return name.startsWith('@') || name === '...attributes' || name === 'as' || name.startsWith('|');
}

type Range = [number, number];

interface NodeWithLoc {
  loc: AST.SourceLocation;
}

function rangeOf(node: NodeWithLoc): Range {
  return [startOffset(node), endOffset(node)];
}

// True when any of the element's children is a Glimmer dynamic construct
// OR a non-native component invocation (PascalCase / dotted-path).
// Used to flag the element for `processElement`'s DynamicValue text content
// — even mixed-content cases (e.g. `<button>{{t 'Save'}} <kbd>⌘S</kbd></button>`)
// where a real label is dynamic but other static markup is also present;
// without the marker, rules like `text-content` may treat the static portion
// as the accessible name and miss issues with the dynamic portion.
//
// Component-child case: `<a><FormattedText @value={{x}} /></a>` — the
// component renders text at runtime, but our transparent substitution
// blanks the component's tags entirely, leaving the anchor empty in the
// output we hand html-validate. Without flagging the parent as dynamic,
// `wcag/h30` / `text-content` / `empty-heading` FP-fire. Trade-off: we
// also silence those rules when the component genuinely renders no text
// (icon-only via component, e.g. `<a><MyIcon /></a>`) — but icon-only
// patterns are usually native (`<svg>`, `<i>`) and still get caught.
function elementHasDynamicContent(node: AST.ElementNode): boolean {
  const children = node.children ?? [];
  for (const child of children) {
    if (
      child.type === 'MustacheStatement' ||
      child.type === 'BlockStatement' ||
      child.type === 'MustacheCommentStatement'
    ) {
      return true;
    }
    if (child.type === 'ElementNode' && !isNativeTag(child.tag)) {
      return true;
    }
  }
  return false;
}

// Recursively walk a Glimmer subtree (Block / Element children) looking for
// a submit-style form control: `<button type='submit'>` or `<input
// type='submit'|'image'>`. Used by the BlockStatement handler to decide
// which branch of `{{#if}}/{{else}}` to emit when one branch is the
// "submitting" branch — single-branch emission would otherwise hide the
// submit button and FP-fire `wcag/h32`.
function blockHasSubmitButton(programOrInverse: AST.Block | null | undefined): boolean {
  if (!programOrInverse?.body) return false;
  for (const child of programOrInverse.body) {
    if (nodeHasSubmitButton(child)) return true;
  }
  return false;
}

function nodeHasSubmitButton(node: AST.Statement | AST.TopLevelStatement): boolean {
  if (node.type === 'ElementNode') {
    if (node.tag === 'button' || node.tag === 'input') {
      for (const attr of node.attributes ?? []) {
        if (attr.name === 'type' && attr.value.type === 'TextNode') {
          const v = attr.value.chars;
          if (v === 'submit' || v === 'image') return true;
        }
      }
    }
    for (const child of node.children ?? []) {
      if (nodeHasSubmitButton(child)) return true;
    }
  } else if (node.type === 'BlockStatement') {
    if (blockHasSubmitButton(node.program)) return true;
    if (node.inverse && blockHasSubmitButton(node.inverse)) return true;
  }
  return false;
}

// Returns the literal value if `node` is a string literal whose contents are
// safe to embed into our blanked HTML output (no chars that would alter HTML
// structure or shift columns).
function safeLiteralString(node: AST.Expression | undefined): string | null {
  if (!node || node.type !== 'StringLiteral' || typeof node.value !== 'string') {
    return null;
  }
  if (/[<>&"'\\\n\r]/u.test(node.value)) {
    return null;
  }
  return node.value;
}

interface AttrCtx {
  attrTagName?: string;
  attrName?: string;
}

// Returns the static string a MustacheStatement would render to, or null
// when we can't resolve. Handles:
//   `{{t 'Key'}}`          → 'Key'  (ember-intl translation key as placeholder)
//   `{{if cond 'a' 'b'}}`  → 'a'   (pick the truthy branch when both literals)
//   `{{NAME}}`             → lookup NAME in `scope` (top-level string consts
//                             extracted from the .gts JS portion).
//   Glint type lookup     → string-literal or string-literal-union from
//                             component Signature. For unions, picks a value
//                             that exposes the bug — see pickRevealingValue.
function tryStaticText(
  node: AST.MustacheStatement,
  scope: ReadonlyMap<string, string> | undefined,
  glintTypeMap: ReadonlyMap<string, AttrTypeInfo> | undefined | null,
  attrCtx?: AttrCtx,
): string | null {
  // Glint type lookup: when @glint/ember-tsc resolves the mustache to a
  // string-literal type (or string-literal union), use the literal as the
  // static-text substitute. For unions in attribute positions where the
  // attribute has an html-validate enum, pick a union member NOT in the
  // enum (if any) so the user's union-type definition surfaces as a real
  // attribute-allowed-values violation. Otherwise pick the first branch.
  if (glintTypeMap && node.loc.start) {
    const key = `${node.loc.start.line}:${node.loc.start.column}`;
    const typeInfo = glintTypeMap.get(key);
    if (
      typeInfo &&
      (typeInfo.kind === 'string-literal' || typeInfo.kind === 'string-literal-union')
    ) {
      let value: string | undefined = typeInfo.values[0];
      if (
        typeInfo.kind === 'string-literal-union' &&
        attrCtx?.attrTagName &&
        attrCtx.attrName
      ) {
        value = pickRevealingValue(typeInfo.values, attrCtx.attrTagName, attrCtx.attrName);
      }
      if (typeof value === 'string' && !/[<>&"'\\\n\r]/u.test(value)) {
        return value;
      }
    }
  }

  const path = node.path;
  if (
    !path ||
    path.type !== 'PathExpression' ||
    (path.head.type !== 'VarHead' && path.head.type !== 'ThisHead')
  ) {
    return null;
  }
  const helper = path.original;

  // Bare reference — no params, no hash. Resolve against `scope`.
  // The map is keyed by the path's `original` text:
  //   - `{{NAME}}`         → scope.get('NAME')         (top-level const)
  //   - `{{this.field}}`   → scope.get('this.field')   (class field)
  if (
    scope &&
    (!node.params || node.params.length === 0) &&
    (!node.hash || !node.hash.pairs || node.hash.pairs.length === 0)
  ) {
    const value = scope.get(helper);
    if (value !== undefined && !/[<>&"'\\\n\r]/u.test(value)) {
      return value;
    }
  }

  // Helper-form lookups (`{{t 'Key'}}` / `{{if cond 'a' 'b'}}`) are only
  // meaningful for VarHead; `{{this.t 'Key'}}` would be a method call,
  // not the t-helper.
  if (path.head.type === 'VarHead') {
    if (helper === 't') {
      return safeLiteralString(node.params[0]);
    }
    if (helper === 'if') {
      const truthy = safeLiteralString(node.params[1]);
      if (truthy !== null) return truthy;
      return safeLiteralString(node.params[2]);
    }
  }
  return null;
}

// Position-finding helpers. We re-scan the source string rather than rely
// solely on AST locs because the AST doesn't directly expose the "open tag
// end" / "close tag start" offsets we need for byte-accurate substitution.
//
// Skip past:
//   - Quoted strings (`"..."` and `'...'`)
//   - Mustache pairs (`{{...}}`, including `{{!-- --}}` and `{{! }}`)
// so a `>` character inside any of those doesn't false-trigger.
function findOpenTagEnd(content: string, openStart: number): number {
  for (let i = openStart + 1; i < content.length; i++) {
    const ch = content[i];
    if (ch === '>') {
      return i;
    }
    if (ch === '"' || ch === "'") {
      const close = content.indexOf(ch, i + 1);
      if (close < 0) return -1;
      i = close;
      continue;
    }
    if (ch === '{' && content[i + 1] === '{') {
      // Skip past matching `}}`. Glimmer mustaches don't nest at the
      // top level here (we're inside an HTML element open tag, not
      // inside another mustache), so a flat `indexOf` is fine. Long-
      // form comments `{{!-- ... --}}` end with `--}}` which still
      // ends in `}}`, so the same scan works.
      const close = content.indexOf('}}', i + 2);
      if (close < 0) return -1;
      i = close + 1;
      continue;
    }
  }
  return -1;
}

function findCloseTagStart(content: string, elementEnd: number): number {
  for (let i = elementEnd - 1; i >= 0; i--) {
    if (content[i] === '<') {
      return i;
    }
  }
  return -1;
}

// ---------------------------------------------------------------------------
// Per-element handlers. Each takes the AST node + a mutable `ctx` object
// that accumulates the rewrite plan (blank ranges, renames, etc.).
// ---------------------------------------------------------------------------

type BranchChoice = 'program' | 'inverse';

interface Context {
  content: string;
  scope: ReadonlyMap<string, string> | undefined;
  glintTypeMap: ReadonlyMap<string, AttrTypeInfo> | null | undefined;
  glintComponentTagMap: ReadonlyMap<string, string> | null | undefined;
  glintComponentAttrMap: ReadonlyMap<string, ComponentAttrs> | null | undefined;
  blankRanges: Range[];
  renames: Array<[number, number, string]>;
  fullyBlankedRanges: Range[];
  dynamicContentOffsets: number[];
  // Per-offset attribute injections, applied at parse-time by
  // transform.ts's `processElement` hook via `setAttribute`. Each
  // entry pairs an attribute name with either a literal value or
  // null (inject the DynamicValue placeholder).
  //
  // Used when the component-substituted source can't carry an
  // attribute through a narrow Glimmer-attr slot — e.g.:
  //   - `<img>` rooted in a component template: `src`/`alt` need to
  //     be present so `wcag/h37` and required-attr rules don't FP-fire.
  //   - `<a>` rooted in a chain: `href` must be present so
  //     `attribute-misuse` (target/rel) doesn't FP-fire on an
  //     anchor-without-href.
  //   - `<input>`/`<button>`: `type` must carry a value (literal when
  //     the chain pinned one, else DynamicValue) so
  //     `no-implicit-input-type` and `attribute-allowed-values`
  //     don't fire on a substituted void element.
  //
  // Replaces four separate `*SplatOffsets` channels.
  attrInjections: Map<number, AttrInjection[]>;
  effectiveComponentAttrMap?: Map<string, ComponentAttrs>;
  // When set, `handleBlockStatement` uses the selection from this map
  // (keyed by the BlockStatement's source-start offset) instead of the
  // default form-submit-aware heuristic. Drives `blankTemplateContentMultipass`,
  // which enumerates branch combinations to validate each independently.
  branchSelections?: ReadonlyMap<number, BranchChoice>;
  inFullyBlankedRange(offset: number): boolean;
}

// Default fallback for component invocations without Glint resolution
// (or as a fallback when source is too short for native substitution).
//
// Blank the open and close tags ENTIRELY — children float to the actual
// parent for content-model checks. This is the same treatment Glint uses
// when `Signature['Element']` resolves to `unknown`/`any`.
//
// Example: `<table><TheadComponent><tr>...</tr></TheadComponent></table>`
// becomes `<table>                  <tr>...</tr>                   </table>`
// — html-validate sees `<tr>` as a direct child of `<table>` (which IS
// allowed), so `element-permitted-content` doesn't fire.
//
// Trade-off: we lose content-model verification ON the component itself
// (we can't say "this component renders block content; it shouldn't be
// inside a phrasing-only parent" without Glint type info). The previous
// `<x-c>` placeholder approach also couldn't do that — and additionally
// FP-fired in strict-content parents like `<table>` / `<ul>` / `<dl>` /
// `<select>` / `<menu>` because `<x-c>` itself isn't an allowed child
// there. Transparent treatment avoids those FPs at the cost of some
// detection power for clearly-misnested components.
function neutralizeComponent(node: AST.ElementNode, ctx: Context): void {
  blankComponentTagsTransparent(node, ctx);
}

// Attempt Glint-driven component substitution. Returns the resolved native
// tag name when handled (caller should treat the element as a native tag
// for attribute processing) or null when the caller should fall back to
// neutralizeComponent. Three cases based on what Glint resolves for the
// component's `Signature['Element']`:
//
//   1. Known DOM tag (e.g. HTMLButtonElement → 'button') — rename in place
//      (block form) or emit `<RESOLVED type=' '>...</RESOLVED>` (self-
//      closing form, FP-fix for empty-element rules).
//   2. 'transparent' (Element === unknown / any) — yields-only / no
//      Element declared. Blank open/close tags, keep children. They float
//      into the parent's content model.
//   3. Anything else — caller falls back to neutralizeComponent (transparent).
function handleGlintSubstitution(node: AST.ElementNode, ctx: Context): string | null {
  if (isNativeTag(node.tag) || !node.loc.start) {
    return null;
  }
  const key = `${node.loc.start.line}:${node.loc.start.column}`;

  // Glint-driven resolution takes precedence (per-invocation accurate).
  // Fall back to the built-in Ember component map for canonical
  // components Glint either can't see (`.hbs` runs) or didn't surface
  // (running without `--glint`). The built-ins also seed `attrCtx` so
  // splatted-root attribute injection works for them without a real
  // file walk (we ship the metadata). Glint can return a tag-only
  // entry for canonical components (e.g. `LinkTo` resolved via
  // `@ember/routing` types — no project `.gts` to read for the
  // splatted root); in that case we still need the builtin's
  // attrs as long as its canonical tag matches what Glint resolved.
  //
  // Trade-off: a project that shadows a built-in name (a user-defined
  // component literally called `LinkTo` resolving to `<a>` but not
  // necessarily rendering `href`) gets the canonical builtin's
  // attrs applied here, masking any anchor/aria errors on the
  // shadow. This is the same FN risk the `.hbs` path has always
  // carried (no Glint there, so the built-in wins by name); we
  // accept it for consistency rather than leave canonical `<LinkTo>`
  // in `.gts` permanently FP-flagged.
  let resolved: string | undefined = ctx.glintComponentTagMap?.get(key);
  let attrCtx: ComponentAttrs | undefined = ctx.glintComponentAttrMap?.get(key);
  if (!resolved || !attrCtx) {
    const builtin = lookupBuiltinComponent(node.tag);
    if (builtin) {
      if (!resolved) resolved = builtin.tag;
      if (!attrCtx && resolved === builtin.tag) attrCtx = builtin;
    }
  }

  if (resolved === 'transparent') {
    blankComponentTagsTransparent(node, ctx);
    return 'transparent';
  }

  if (typeof resolved !== 'string' || resolved.length > node.tag.length) {
    return null;
  }

  // Stash the resolved attrCtx in ctx for later lookup helpers
  // (lookupComponentAttr) — they currently key off
  // ctx.glintComponentAttrMap, but we want builtin-derived attrCtx to
  // be visible too. Rather than threading a parameter through several
  // call sites, write the entry into a per-call effective map.
  if (attrCtx && !ctx.glintComponentAttrMap?.has(key)) {
    if (!ctx.effectiveComponentAttrMap) {
      ctx.effectiveComponentAttrMap = new Map(ctx.glintComponentAttrMap ?? []);
    }
    ctx.effectiveComponentAttrMap.set(key, attrCtx);
  }

  if (node.selfClosing) {
    // Two paths depending on whether the resolved native is void:
    //   - Void natives (input, img, br, hr, …): in-place tag rename keeps
    //     the parent's non-Glimmer attrs (id, class, name, data-*) visible
    //     for validation. Glimmer-only attrs (`@arg`, modifiers,
    //     `...attributes`) are blanked. For <input>, we additionally
    //     inject `type=' '` into a Glimmer-attr blank area so
    //     `no-implicit-input-type` doesn't FP-fire (the actual `type`
    //     comes from the component's internal template, which we can't
    //     see).
    //   - Non-void natives (button, span, …): open+close-pair emission.
    //     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, attrCtx) ? resolved : null;
    }
    return substituteSelfClosingComponent(node, ctx, resolved, attrCtx) ? resolved : null;
  }

  // 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;
  const padding = ' '.repeat(node.tag.length - resolved.length);
  ctx.renames.push([tagStart, tagStart + node.tag.length, resolved + padding]);
  const closeTagStart = elementEnd - node.tag.length - 1;
  ctx.renames.push([closeTagStart, closeTagStart + node.tag.length, resolved + padding]);
  // Erase any `as |…|` block-param clause from the renamed open tag.
  // Block params are a Glimmer-side binding for yielded content — they
  // never appear as attributes in the rendered DOM. Without this blank,
  // the in-place rename leaves `as |item|` in the open tag and html-
  // validate's parser treats `|item|` as an attribute, firing `attr-case`
  // (and downstream rules cascade).
  //
  // Take the LAST regex match: per Glimmer syntax the block-params clause
  // is always the rightmost thing before `>`, so the last match is
  // unambiguously it — defends against the (rare) case where an attribute
  // value happens to contain a literal `as |x|`.
  if (node.blockParams.length > 0) {
    const openTagEnd = findOpenTagEnd(ctx.content, elementStart);
    if (openTagEnd >= 0) {
      const openTagText = ctx.content.slice(elementStart, openTagEnd + 1);
      const re = /\bas\s+\|[^|]*\|/g;
      let last: RegExpExecArray | null = null;
      let m: RegExpExecArray | null;
      while ((m = re.exec(openTagText)) !== null) last = m;
      if (last) {
        ctx.blankRanges.push([elementStart + last.index, elementStart + last.index + last[0].length]);
      }
    }
  }
  // Yield-ancestor substitution: the chosen tag is an inner element of
  // the wrapper's own template (e.g. `<nav><ol>{{yield}}</ol></nav>`
  // resolved as `<ol>` to put yielded `<li>` children under the correct
  // structural parent). At runtime, the consumer's attributes splat onto
  // the outer wrapper via `...attributes`, NOT onto the inner — so the
  // in-place tag rename produces `<ol aria-label='X'>` even though
  // `aria-label='X'` lands on `<nav>` at runtime. Strip `aria-*` from
  // the substituted open tag so html-validate doesn't fire
  // aria-label-misuse / aria-labelledby-misuse against the wrong tag.
  // Scoped to `aria-*` because that's where the observed FP class lives
  // (ARIA-in-HTML rules differ per host element); other consumer attrs
  // (id, class, data-*, role) generally validate the same against
  // either tag.
  if (attrCtx?.fromYieldAncestor) {
    for (const attr of node.attributes ?? []) {
      if (!attr.name.startsWith('aria-')) continue;
      const r: [number, number] = [startOffset(attr), endOffset(attr)];
      ctx.blankRanges.push(r);
      // Mark fully blanked so the later `emitAttribute` loop skips this
      // attribute. Without this, ConcatStatement/MustacheStatement value
      // rewrites would inject `"` quotes back into the blanked region.
      ctx.fullyBlankedRanges.push(r);
    }
  }
  // Inject the resolved component's static attrs into Glimmer-attr blank
  // regions in the open tag (mirrors the self-closing input-type
  // injection). Without this, e.g. <LinkTo>...</LinkTo> resolves to a
  // bare <a> with no href — html-validate then treats it as
  // non-interactive and FP-fires `aria-label-misuse` and other
  // role-dependent rules. The same mechanism gives Glint-resolved
  // components a way to surface canonical attrs (e.g. a custom
  // <SubmitButton> that always renders <button type='submit'>).
  if (attrCtx && Object.keys(attrCtx.attrs).length > 0) {
    tryInjectComponentAttrs(node, ctx, resolved, attrCtx.attrs);
  }
  // Block-form `<button>` substitutions (typically curried hash-yielded
  // components like `<RT.Toggle>...</RT.Toggle>` resolved to
  // `<button>`) reach here without a chain `attrCtx` populated. The
  // in-place tag rename produces `<button   ...>` with no `type`,
  // FP-firing `no-implicit-button-type` even though the addon's
  // template literally writes `<button type="button" ...attributes>`.
  // Register the offset so the `processElement` hook calls
  // setAttribute('type', DynamicValue) at parse time. Skipped when
  // the consumer wrote `type=` themselves.
  if (resolved === 'button') {
    const present = new Set((node.attributes ?? []).map((a) => a.name));
    if (!present.has('type') && !hasAttrInjection(ctx.attrInjections, startOffset(node), 'type')) {
      addAttrInjection(ctx.attrInjections, startOffset(node), 'type', null);
    }
  }
  return resolved;
}

// Self-closing component substituted to a void native (input, img, br,
// …). In-place tag-name rename — the existing attribute-processing loop
// in handleElementNode then preserves non-Glimmer attrs (id, class,
// name, …) and blanks Glimmer-only attrs. For <input>, additionally
// inject `type=' '` into a Glimmer-attr blank area so
// `no-implicit-input-type` doesn't FP-fire.
//
// Returns true on successful substitution; false when source is too
// short to fit the resolved tag name (caller falls back to transparent
// neutralization).
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).
  if (node.tag.length < resolved.length) return false;
  const tagStart = elementStart + 1;
  const padding = ' '.repeat(node.tag.length - resolved.length);
  ctx.renames.push([tagStart, tagStart + node.tag.length, resolved + padding]);
  // For <input>, find a Glimmer-attr blank area to inject `type=' '`.
  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 per-attr in that case.
  //
  // Per-attr precision matters here: a component whose template
  // binds `src={{this.src}}` but not `alt` registers only `src` in
  // `attrInjections` — `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) {
    addAttrInjection(ctx.attrInjections, offset, 'src', null);
  }
  if (!present.has('alt') && attrCtx.attrs['alt'] !== undefined) {
    addAttrInjection(ctx.attrInjections, offset, 'alt', null);
  }
}

// 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
// stays in `blankRanges` (added by emitAttribute), so the area outside
// our injection becomes spaces.
//
// Two strategies for the value:
//   1. If `glintComponentAttrMap` has a literal `type` for this
//      component (the splatted-root has a literal `type='range'`-style
//      attribute), inject the actual value: `<input type='range' ...`.
//      Lets html-validate validate the value against the enum.
//   2. Otherwise, inject `type='   '` (3-space placeholder). The
//      `processAttribute` hook converts the whitespace value to
//      DynamicValue (its >=3-char threshold), so `attribute-allowed-
//      values` doesn't fire on the placeholder.
//
// No-op when no suitable attr area is found — `no-implicit-input-type`
// will still fire in that case, but the user can silence per-site.

// Symmetric to tryInjectInputType but for void natives whose required attrs
// can be supplied by the consumer via `...attributes`. Without injection,
// `<img ...attributes>` blanks to an attribute-less `<img>` and html-validate
// FP-fires `element-required-attributes` (src) and `wcag/h37` (alt) even
// though both come from the splat at runtime.
//
// We don't rewrite the source — the minimal `...attributes` slot is 13
// chars and html-validate accepts no two-attr form that fits (bare
// `src alt` triggers `attribute-allowed-values`-missing-value, empty
// quoted `src=''` triggers `attribute-allowed-values`-invalid-value,
// and the wide whitespace form `src='   ' alt='   '` is 19+ chars).
//
// Instead, record the element's start offset; the transformer's
// `processElement` hook reads this list and calls `setAttribute` with
// a DynamicValue at parse time, sidestepping source-side slot width
// entirely. Skipped when the consumer already wrote `src=` / `alt=`
// explicitly (no FP to suppress).
//
// Currently scoped to <img>; the same shape applies to
// <source>/<track>/<area>/<iframe> if real-world FPs surface there.
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));
  // 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')) addAttrInjection(ctx.attrInjections, offset, 'src', null);
  if (!present.has('alt')) addAttrInjection(ctx.attrInjections, offset, 'alt', null);
}

function tryInjectInputType(node: AST.ElementNode, ctx: Context): void {
  const literalType = lookupComponentAttr(node, ctx, 'type');
  // Build the injected text. Prefer a literal value when known and
  // safe (no embedded quotes / HTML-altering chars).
  const valueLiteral = isLiteralSafeForAttr(literalType) ? literalType : null;
  const TYPE_TEXT =
    valueLiteral !== null ? `type='${valueLiteral}'` : `type='${DYNAMIC_VALUE_PLACEHOLDER}'`;
  const candidates: Range[] = [];
  for (const attr of node.attributes ?? []) {
    if (isGlimmerOnlyAttr(attr.name)) {
      candidates.push([startOffset(attr), endOffset(attr)]);
    }
  }
  for (const m of node.modifiers ?? []) {
    candidates.push([startOffset(m), endOffset(m)]);
  }
  for (const [s, e] of candidates) {
    if (e - s < TYPE_TEXT.length) continue;
    const slice = ctx.content.slice(s, s + TYPE_TEXT.length);
    if (/[\n\r]/.test(slice)) continue;
    ctx.renames.push([s, s + TYPE_TEXT.length, TYPE_TEXT]);
    return;
  }
  // No suitable Glimmer-attr slot — register the consumer's element
  // offset so the `processElement` hook synthesizes `type` at parse
  // time. Mirrors the imgSplat / aSplatHref hook-time fallback.
  // Registering the offset is unconditional once source-side fitting
  // failed: even when `lookupComponentAttr` returned null, injecting
  // a DynamicValue clears `no-implicit-input-type` and leaves
  // `attribute-allowed-values` to the parent invocation that owns
  // the value (the consumer can still pass an explicit `type=` to
  // override the projection).
  addAttrInjection(ctx.attrInjections, startOffset(node), 'type', valueLiteral);
}

// Generalized attr injection for block-form component substitution.
// For each `(name, value)` in `attrs`, find a Glimmer-only attribute
// or modifier blank region in the open tag with enough room for
// `name='value'` (no newlines), and rewrite it. Each region is used
// by at most one injected attr.
//
// Used today for `<LinkTo>...</LinkTo>` to surface its computed
// `href` so html-validate sees an interactive `<a>`. Generalized
// because the same mechanism applies to any block-form component
// substitution where a Glint-resolved or builtin entry has static
// attrs (e.g. `<SubmitButton>` that always renders
// `<button type='submit'>`).
//
// Value sourcing per attr: prefer a literal looked up via
// `lookupComponentAttr` (matches the self-closing input-type path),
// fall back to a 3-space placeholder so the `processAttribute` hook
// converts the value to `DynamicValue`. The placeholder length must
// be >= 3 to clear that hook's threshold.
function tryInjectComponentAttrs(
  node: AST.ElementNode,
  ctx: Context,
  resolvedTag: string,
  attrs: Readonly<Record<string, string>>,
): void {
  const candidates: Range[] = [];
  // Names already present as non-Glimmer attrs on the invocation; skip
  // injecting these so the substituted tag doesn't carry duplicates
  // (e.g. `<SubmitButton type='button'>` against a splatted root with
  // `type='submit'` would otherwise emit two `type` attrs and trip
  // html-validate's `no-dup-attr`).
  //
  // Limitation: `componentAttrMap` records the literal but not the
  // position of `...attributes` in the splatted root. Two layouts
  // are common in Glimmer:
  //   1. `<button class='primary' type='submit' ...attributes>`
  //      — caller-wins. Conventional, dominant in real code.
  //   2. `<button ...attributes type='submit'>`
  //      — component-wins. Forces a literal regardless of caller.
  // We default to layout (1): drop the canonical attr when the
  // caller supplies the same name. Layout (2) would render the
  // component's value at runtime, which we then misrepresent as
  // the caller's value — but emitting both attrs doesn't actually
  // help: HTML5 parsing also takes the first one, so the validator's
  // DOM view is identical to the caller-wins path. We just avoid
  // the spurious `no-dup-attr` noise for the dominant layout.
  const existingNonGlimmer = new Set<string>();
  for (const attr of node.attributes ?? []) {
    if (isGlimmerOnlyAttr(attr.name)) {
      candidates.push([startOffset(attr), endOffset(attr)]);
    } else {
      existingNonGlimmer.add(attr.name);
    }
  }
  for (const m of node.modifiers ?? []) {
    candidates.push([startOffset(m), endOffset(m)]);
  }
  // Build the injection plan first, then place longer texts before
  // shorter ones. Otherwise a short attr visited first can claim the
  // only candidate slot wide enough for a longer attr, silently
  // dropping it. Per-attr emission rules (boolean → presence-only,
  // safe literal → embedded, otherwise → DynamicValue placeholder)
  // are documented in the .map below.
  const plan = Object.keys(attrs)
    .filter((name) => !existingNonGlimmer.has(name))
    .map((attrName) => {
      // Boolean attrs (`disabled`, `required`, `selected`, …) emit
      // presence-only regardless of the recorded value. Per HTML5 any
      // value (including `''`, `'disabled'`, the DynamicValue
      // placeholder, etc.) is equivalent to "true"; emitting
      // `name='value'` would unnecessarily fire `attribute-boolean-style`.
      if (isBooleanAttr(resolvedTag, attrName)) return { name: attrName, text: attrName };
      const literal = lookupComponentAttr(node, ctx, attrName);
      if (isLiteralSafeForAttr(literal))
        return { name: attrName, text: `${attrName}='${literal}'` };
      return { name: attrName, text: `${attrName}='${DYNAMIC_VALUE_PLACEHOLDER}'` };
    });
  // Two-phase placement:
  //   Phase 1: any attr in `ANCHOR_ATTRS` (currently just `role`).
  //     These authorize aria-* attrs on otherwise-incompatible
  //     elements (e.g. `<div role="dialog" aria-labelledby="…">`
  //     is valid; `<div aria-labelledby="…">` alone trips
  //     `aria-label-misuse`). Place anchors first so dependents
  //     have authorization context; if an anchor doesn't fit,
  //     drop its dependents from phase 2 to avoid landing the
  //     dependent without its anchor.
  //   Phase 2: everything else, longest-first (the original
  //     behavior — longer attrs need wider slots and would
  //     otherwise be starved by shorter ones grabbing slots).
  //
  // Rationale: aria-labelledby on `<HdsAppSideNav>`-style
  // wrappers (whose splatted root is `<div role={{…}}
  // aria-labelledby={{…}}>`) was getting injected without role
  // because role was shorter and lost the slot-fitting race —
  // FP-firing `aria-label-misuse` ("aria-labelledby cannot be
  // used on this element").
  // Anchor → dependents: when an aria-* injection lands on a
  // substituted element WITHOUT its anchoring `role`, html-validate
  // rules (`aria-label-misuse`, the metadata-driven role-property
  // permission checks, etc.) fire because the element-without-role
  // doesn't accept the aria-* attr.
  //
  // Drift-proof: rather than enumerate which aria-* are role-
  // dependent (the list lives inside individual html-validate rules
  // and may grow over versions), gate the entire `aria-*` prefix on
  // the presence of `role` in the same injection. When the addon's
  // splatted-root literally writes `<div role="dialog"
  // aria-labelledby="…">`, both attrs are recorded; we inject them
  // together or not at all.
  const ANCHOR_ATTRS = new Set(['role']);
  function isAriaDependent(name: string): boolean {
    return name.startsWith('aria-');
  }
  const used = new Set<number>();
  const unfitted = new Set<string>();
  function placeOne(text: string, name: string): boolean {
    for (let i = 0; i < candidates.length; i++) {
      if (used.has(i)) continue;
      const [s, e] = candidates[i]!;
      if (e - s < text.length) continue;
      const slice = ctx.content.slice(s, s + text.length);
      if (/[\n\r]/.test(slice)) continue;
      ctx.renames.push([s, s + text.length, text]);
      used.add(i);
      return true;
    }
    unfitted.add(name);
    return false;
  }
  // Phase 1: anchors.
  const anchorPlan = plan.filter((p) => ANCHOR_ATTRS.has(p.name));
  anchorPlan.sort((a, b) => b.text.length - a.text.length);
  for (const { text, name } of anchorPlan) placeOne(text, name);
  // If `role` didn't fit, drop all aria-dependents from the rest of
  // the plan: injecting them on a plain element would fire
  // `aria-label-misuse`. Mark them unfitted so downstream channels
  // see they were skipped.
  const roleFitted = ANCHOR_ATTRS.has('role') && !unfitted.has('role') &&
    plan.some((p) => p.name === 'role');
  const restPlan = plan.filter((p) => {
    if (ANCHOR_ATTRS.has(p.name)) return false;
    if (!roleFitted && isAriaDependent(p.name)) {
      unfitted.add(p.name);
      return false;
    }
    return true;
  });
  restPlan.sort((a, b) => b.text.length - a.text.length);
  // (legacy single-pass placement for the rest)
  for (const { text, name } of restPlan) {
    let placed = false;
    for (let i = 0; i < candidates.length; i++) {
      if (used.has(i)) continue;
      const [s, e] = candidates[i]!;
      if (e - s < text.length) continue;
      const slice = ctx.content.slice(s, s + text.length);
      if (/[\n\r]/.test(slice)) continue;
      ctx.renames.push([s, s + text.length, text]);
      used.add(i);
      placed = true;
      break;
    }
    if (!placed) unfitted.add(name);
  }
  // Hook-time fallback for `<a>`: when the chain records `href` but the
  // consumer's narrow Glimmer-attr slots couldn't fit it, the substituted
  // `<a target='_blank' >` lacks `href` — html-validate then fires
  // `attribute-misuse` ("target requires href"). Register via the
  // unified `attrInjections` registry so the `processElement` hook
  // calls setAttribute('href', DynamicValue) at parse time (the same
  // mechanism the `<img>` src/alt and `<button>` type fallbacks use).
  // Scoped to `<a>` because that's where the observed FP class lives;
  // extend if other element/attr pairs surface.
  if (resolvedTag === 'a' && unfitted.has('href') && !existingNonGlimmer.has('href')) {
    addAttrInjection(ctx.attrInjections, startOffset(node), 'href', null);
  }
  // Same fallback for `<button>`: when the chain records `type` (typical
  // canonical addon shape: `<button type="button" ...attributes>`) but
  // the narrow open-tag Glimmer slots can't fit `type='button'`, the
  // substituted `<button>` reaches html-validate without a `type` and
  // `no-implicit-button-type` FP-fires.
  if (resolvedTag === 'button' && unfitted.has('type') && !existingNonGlimmer.has('type')) {
    const literal = lookupComponentAttr(node, ctx, 'type');
    const value = isLiteralSafeForAttr(literal) ? literal : null;
    addAttrInjection(ctx.attrInjections, startOffset(node), 'type', value);
  }
}

// Look up a literal attribute value from the component's splatted-root.
// Sources, in order of precedence:
//   1. Per-invocation Glint-extracted attrs (`glintComponentAttrMap`).
//   2. Built-in Ember component fallback (Input / Textarea / LinkTo),
//      seeded into `effectiveComponentAttrMap` by handleGlintSubstitution.
// Returns the string value or null when not available.
function lookupComponentAttr(
  node: AST.ElementNode,
  ctx: Context,
  attrName: string,
): string | null {
  if (!node.loc.start) return null;
  const key = `${node.loc.start.line}:${node.loc.start.column}`;
  const map = ctx.effectiveComponentAttrMap ?? ctx.glintComponentAttrMap;
  if (!map) return null;
  const entry = map.get(key);
  return entry?.attrs[attrName] ?? null;
}

// True when the value is safe to embed verbatim into a single-quoted
// HTML attribute: must be a string with no characters that would alter
// HTML structure or shift columns.
//
// Rejects the DynamicValue placeholder (whitespace-only of length >=
// 3): that's the chain-attr extractor's marker for "value is dynamic
// at runtime", not a real literal. Embedding it verbatim would mean
// the consumer-side attribute value LOOKS like a 3-space literal to
// html-validate, which is invalid for enum-checked attrs (`type=` on
// `<input>`/`<button>`, `dir=`, etc.) and trips
// `attribute-allowed-values` with a confusing "invalid value '   '"
// message. Callers must fall through to the DynamicValue path
// instead so the `processAttribute` hook converts at parse time.
function isLiteralSafeForAttr(value: string | null): value is string {
  if (typeof value !== 'string') return false;
  if (value.length === 0) return false;
  if (isDynamicValuePlaceholder(value)) return false;
  return !/[<>&"'\\\n\r]/u.test(value);
}

// Transparent treatment: blank the component's open and close tags
// entirely. Children float into the parent's content model — more accurate
// than wrapping in `<x-c>` for components that render no DOM (e.g. yield-
// only data-fetcher components).
//
// When `findOpenTagEnd` fails (e.g., the open tag contains a complex
// `{{! ... }}` short-form Glimmer comment that the byte-scan heuristic
// can't reason about), fall back to blanking the entire element so the
// PascalCase tag name doesn't reach html-validate's parser. Trade-off:
// children are also blanked in that fallback case, but that's safer
// than leaking PascalCase tags into the output.
function blankComponentTagsTransparent(node: AST.ElementNode, ctx: Context): void {
  const { content, blankRanges, fullyBlankedRanges } = ctx;
  const elementStart = startOffset(node);
  const elementEnd = endOffset(node);
  const openTagEnd = findOpenTagEnd(content, elementStart);
  if (openTagEnd < 0) {
    blankRanges.push([elementStart, elementEnd]);
    fullyBlankedRanges.push([elementStart, elementEnd]);
    return;
  }
  blankRanges.push([elementStart, openTagEnd + 1]);
  fullyBlankedRanges.push([elementStart, openTagEnd + 1]);
  if (!node.selfClosing) {
    const closeTagStart = findCloseTagStart(content, elementEnd);
    if (closeTagStart >= 0) {
      blankRanges.push([closeTagStart, elementEnd]);
      fullyBlankedRanges.push([closeTagStart, elementEnd]);
    } else {
      // Couldn't locate the close tag — blank to end of element.
      blankRanges.push([elementStart, elementEnd]);
      fullyBlankedRanges.push([elementStart, elementEnd]);
    }
  }
}

// Self-closing component substituted to a non-void native (e.g.
// `<AccessGrant />` resolved to `<button>` because the component declares
// `Signature['Element'] = HTMLButtonElement`). Emit as
// `<RESOLVED type=' '>...</RESOLVED>` open+close pair (length-preserved)
// and register the element offset for DynamicValue text content via
// `processElement`. Without this, the substituted self-closing tag would
// look empty + untyped to html-validate, FP-firing `text-content` and
// `no-implicit-button-type`. The component's actual rendered button has
// both — we just can't see them from the parent template.
//
// Returns true when the substitution succeeded; false when the source span
// is too short and the caller should fall back to transparent neutralization.
function substituteSelfClosingComponent(
  node: AST.ElementNode,
  ctx: Context,
  resolved: string,
  attrCtx: ComponentAttrs | undefined,
): boolean {
  const elementStart = startOffset(node);
  const elementEnd = endOffset(node);
  // Three-space placeholder (not one) so the existing `processAttribute`
  // hook converts it to DynamicValue. A 1-char value would be treated as
  // a literal `' '` and trigger `attribute-allowed-values` (`' '` isn't
  // in `<button type>`'s enum). When Glint has resolved the component's
  // splatted root and exposes a literal `type` attribute, prefer that —
  // gives html-validate the actual value to enum-check.
  let typeAttr = '';
  if (resolved === 'button') {
    const literal = lookupComponentAttr(node, ctx, 'type');
    typeAttr = isLiteralSafeForAttr(literal)
      ? ` type='${literal}'`
      : ` type='${DYNAMIC_VALUE_PLACEHOLDER}'`;
  }
  // Embed the rest of the splatted-root attrs (other than type, handled
  // above for button). Without this, components whose Signature['Element']
  // resolves to a non-void native carrying *required* attrs sourced from
  // arg-bindings (e.g. `<iframe title={{@label}} src={{@src}}>`) would
  // emit a bare `<iframe></iframe>` and FP-fire
  // `element-required-attributes`.
  let extraAttrs = '';
  for (const [name, value] of Object.entries(attrCtx?.attrs ?? {})) {
    if (resolved === 'button' && name === 'type') continue; // already in typeAttr
    // Boolean attrs emit presence-only; see tryInjectComponentAttrs's
    // matching branch for the rationale.
    if (isBooleanAttr(resolved, name)) {
      extraAttrs += ` ${name}`;
      continue;
    }
    const safeValue = isLiteralSafeForAttr(value) ? value : DYNAMIC_VALUE_PLACEHOLDER;
    extraAttrs += ` ${name}='${safeValue}'`;
  }
  const openTag = `<${resolved}${typeAttr}${extraAttrs}>`;
  const closeTag = `</${resolved}>`;
  const minLen = openTag.length + closeTag.length;
  const sourceLen = elementEnd - elementStart;
  if (sourceLen < minLen) {
    return false;
  }
  // Keep the span's newlines inside the element, so later lines keep
  // their line numbers.
  const newlines = ctx.content.slice(elementStart, elementEnd).replace(/[^\r\n]/g, '').slice(0, sourceLen - minLen);
  const inner = newlines + ' '.repeat(sourceLen - minLen - newlines.length);
  ctx.renames.push([elementStart, elementEnd, openTag + inner + closeTag]);
  ctx.fullyBlankedRanges.push([elementStart, elementEnd]);
  ctx.dynamicContentOffsets.push(elementStart);
  if (process.env['HVE_DEBUG_SUB']) {
    process.stderr.write(
      `[sub-sc-non-void:done] resolved=${resolved} range=[${elementStart},${elementEnd}] replacement.length=${(openTag + inner + closeTag).length}\n`,
    );
  }
  return true;
}

// Emit the rewrite plan for an attribute on a native (or substituted-as-
// native) element. Handles:
//
//   - Glimmer-only attrs (`@arg`, `...attributes`, `as`, `|x|`) — fully blanked.
//   - Concat-mustache values (`class='prefix-{{x}}'`) — blanked to `""<sp>"`,
//     yields DynamicValue via processAttribute; for boolean attrs, presence-only.
//   - Bare-mustache values (`id={{x}}`) — try static-text resolution; else
//     blanked to DynamicValue (or presence-only for boolean attrs).
function emitAttribute(attr: AST.AttrNode, ctx: Context, effectiveTag: string): void {
  const { blankRanges, fullyBlankedRanges, renames, scope, glintTypeMap } = ctx;

  // Skip attributes whose source range was already fully blanked by an
  // earlier path (e.g. aria-* strip on yield-ancestor-substituted tag).
  // Without this guard, `emitAttribute`'s ConcatStatement/MustacheStatement
  // value-rewriting would re-emit stray `"` quotes into the blanked
  // region, producing un-tokenizable open tags.
  if (ctx.inFullyBlankedRange(startOffset(attr))) {
    return;
  }

  if (isGlimmerOnlyAttr(attr.name)) {
    const r = rangeOf(attr);
    blankRanges.push(r);
    fullyBlankedRanges.push(r);
    return;
  }

  if (attr.value.type === 'ConcatStatement') {
    // Concat-mustache: literal portions mix with dynamic. Emit whole value
    // as `""<spaces>` to yield DynamicValue (loses validation of literal
    // portions but avoids false matches on partial literals).
    const valueStart = startOffset(attr.value);
    const valueEnd = endOffset(attr.value);
    const valueLen = valueEnd - valueStart;
    if (isBooleanAttr(effectiveTag, attr.name)) {
      const eqStart = valueStart - 1;
      blankRanges.push([eqStart, valueEnd]);
      fullyBlankedRanges.push([eqStart, valueEnd]);
    } else if (valueLen >= 2) {
      blankRanges.push([valueStart, valueEnd]);
      renames.push([valueStart, valueStart + 1, '"']);
      renames.push([valueEnd - 1, valueEnd, '"']);
      fullyBlankedRanges.push([valueStart, valueEnd]);
    } else {
      const r = rangeOf(attr);
      blankRanges.push(r);
      fullyBlankedRanges.push(r);
    }
    return;
  }

  if (attr.value.type === 'MustacheStatement') {
    // Bare-mustache attribute value. For boolean attrs, emit presence-only
    // (canonical "rendered" form per glimmer attribute coercion). For non-
    // boolean attrs, try static-text resolution (t-helper, if-helper, const,
    // Glint type) and embed if it fits; otherwise blank to DynamicValue.
    const valueStart = startOffset(attr.value);
    const valueEnd = endOffset(attr.value);
    const valueLen = valueEnd - valueStart;
    if (isBooleanAttr(effectiveTag, attr.name)) {
      const eqStart = valueStart - 1;
      blankRanges.push([eqStart, valueEnd]);
      fullyBlankedRanges.push([eqStart, valueEnd]);
    } else if (valueLen >= 2) {
      const resolved = tryStaticText(attr.value, scope, glintTypeMap, {
        attrTagName: effectiveTag,
        attrName: attr.name,
      });
      const innerLen = valueLen - 2;
      if (resolved !== null && resolved.length <= innerLen) {
        // Embed the resolved literal so html-validate sees the actual value
        // (enables enum validation). Shorter values appear with trailing
        // whitespace outside the closing quote.
        blankRanges.push([valueStart, valueEnd]);
        renames.push([valueStart, valueStart + 1, '"']);
        renames.push([valueStart + 1, valueStart + 1 + resolved.length, resolved]);
        renames.push([valueStart + 1 + resolved.length, valueStart + 2 + resolved.length, '"']);
        fullyBlankedRanges.push([valueStart, valueEnd]);
      } else {
        blankRanges.push([valueStart, valueEnd]);
        renames.push([valueStart, valueStart + 1, '"']);
        renames.push([valueEnd - 1, valueEnd, '"']);
        fullyBlankedRanges.push([valueStart, valueEnd]);
      }
    } else {
      const r = rangeOf(attr);
      blankRanges.push(r);
      fullyBlankedRanges.push(r);
    }
  }
}

// Handle an `<element>` AST node: drive Glint substitution / neutralization
// and process attributes / modifiers / inline comments.
function handleElementNode(node: AST.ElementNode, ctx: Context): void {
  const start = startOffset(node);
  if (ctx.inFullyBlankedRange(start)) {
    return;
  }

  // Glint substitution path. When it returns non-null, the element has
  // been handled (transparent, self-closing-substituted, or block-form
  // tag rename).
  //   - 'transparent': open/close blanked, return.
  //   - Non-void self-closing substitution (button, span, …): whole span
  //     is rewritten as <RESOLVED>...</RESOLVED>, skip attr processing.
  //   - Void self-closing substitution (input, img, br, …): only the
  //     tag-name was renamed; attrs still need blanking/preserving.
  //     Fall through to attribute processing.
  //   - Block-form: tag-name renamed in place; fall through to attribute
  //     processing.
  let effectiveTag = node.tag;
  const resolved = handleGlintSubstitution(node, ctx);
  if (resolved === 'transparent') {
    return;
  }
  if (resolved !== null) {
    effectiveTag = resolved;
    if (node.selfClosing && !VOID_ELEMENTS.has(resolved)) {
      // Non-void self-closing: the whole span is in fullyBlankedRanges;
      // attribute children are guarded out via inFullyBlankedRange.
      return;
    }
    // Void self-closing OR block-form: fall through to attr processing.
  }

  if (effectiveTag === node.tag && !isNativeTag(node.tag)) {
    // No Glint-resolved native equivalent — fall back to transparent
    // neutralization (open/close tags blanked; children float to parent).
    neutralizeComponent(node, ctx);
    return;
  }

  // Native element (or block-form Glint-substituted as native).
  if (elementHasDynamicContent(node)) {
    ctx.dynamicContentOffsets.push(start);
  }
  // For void natives whose required attrs can come from `...attributes`,
  // inject placeholders before the splat is blanked. Currently <img>; see
  // tryInjectImgRequiredAttrs for the rationale and scope.
  if (effectiveTag === 'img') {
    tryInjectImgRequiredAttrs(node, ctx);
  }
  for (const attr of node.attributes ?? []) {
    emitAttribute(attr, ctx, effectiveTag);
  }
  for (const modifier of node.modifiers ?? []) {
    const r = rangeOf(modifier);
    ctx.blankRanges.push(r);
    ctx.fullyBlankedRanges.push(r);
  }
  for (const comment of node.comments ?? []) {
    const r = rangeOf(comment);
    ctx.blankRanges.push(r);
    ctx.fullyBlankedRanges.push(r);
  }
}

// Handle a `{{mustache}}` AST node: try static-text resolution for embed,
// else blank.
function handleMustacheStatement(node: AST.MustacheStatement, ctx: Context): void {
  const { content, blankRanges, renames, scope, glintTypeMap } = ctx;
  const start = startOffset(node);
  if (ctx.inFullyBlankedRange(start)) {
    return;
  }
  const wholeStart = start;
  const wholeEnd = endOffset(node);
  const mustacheSrc = content.slice(wholeStart, wholeEnd);
  const text = tryStaticText(node, scope, glintTypeMap);
  // Skip embedding when the mustache spans multiple lines — overwriting
  // internal newlines would shift html-validate's line/column tracking
  // for everything after this point.
  const safeToEmbed = text !== null && text.length <= mustacheSrc.length && !/[\n\r]/u.test(mustacheSrc);
  if (safeToEmbed) {
    blankRanges.push([wholeStart, wholeEnd]);
    renames.push([wholeStart, wholeStart + text.length, text]);
  } else {
    blankRanges.push([wholeStart, wholeEnd]);
  }
}

// Handle a `{{!-- ... --}}` (long form) or `{{! ... }}` (short form)
// MustacheCommentStatement. If it's an html-validate directive, rewrite
// as an HTML comment in place (length-preserved) so html-validate's
// parser sees the directive. Otherwise blank.
function handleMustacheCommentStatement(
  node: AST.MustacheCommentStatement,
  ctx: Context,
): void {
  const { content, blankRanges, renames } = ctx;
  const start = startOffset(node);
  if (ctx.inFullyBlankedRange(start)) {
    return;
  }
  const wholeStart = start;
  const wholeEnd = endOffset(node);
  const fullText = content.slice(wholeStart, wholeEnd);

  if (
    !/\[html-validate-(?:disable|enable)/.test(fullText) ||
    /[\n\r]/.test(fullText)
  ) {
    blankRanges.push(rangeOf(node));
    return;
  }

  // Long form: `{{!--` (5) → `<!-- ` (5) and `--}}` (4) → ` -->` (4) —
  // marker swap preserves byte length, inner content untouched.
  if (fullText.startsWith('{{!--') && fullText.endsWith('--}}')) {
    rewriteCommentMarkers(fullText, wholeStart, wholeEnd, '<!-- ', ' -->', renames);
    return;
  }

  // Short form: `{{! ` (4) → `<!--` (4) and ` }}` (3) → `-->` (3) — we
  // steal the inner padding spaces Prettier always emits to absorb the
  // 2-byte marker delta. Requires the Prettier-normalized
  // `{{! <content> }}` shape (single space on each side); other shapes
  // fall through to blank.
  //
  // Why we need this: Prettier's glimmer printer hard-codes the collapse
  // from `{{!-- ... --}}` to `{{! ... }}` whenever the inner content
  // doesn't itself contain `}}`. There is no opt-out, so users running
  // Prettier could not previously place inline directives without
  // dropping to raw `<!-- -->` HTML comments (which `ember/template-no-
  // html-comments` then flags).
  if (fullText.startsWith('{{! ') && fullText.endsWith(' }}')) {
    rewriteCommentMarkers(fullText, wholeStart, wholeEnd, '<!--', '-->', renames);
    return;
  }

  blankRanges.push(rangeOf(node));
}

function rewriteCommentMarkers(
  fullText: string,
  wholeStart: number,
  wholeEnd: number,
  newPrefix: string,
  newSuffix: string,
  renames: Array<[number, number, string]>,
): void {
  for (let i = 0; i < newPrefix.length; i++) {
    if (fullText[i] !== newPrefix[i]) {
      renames.push([wholeStart + i, wholeStart + i + 1, newPrefix[i]!]);
    }
  }
  const totalLen = wholeEnd - wholeStart;
  for (let i = 0; i < newSuffix.length; i++) {
    const idx = totalLen - newSuffix.length + i;
    if (fullText[idx] !== newSuffix[i]) {
      renames.push([wholeStart + idx, wholeStart + idx + 1, newSuffix[i]!]);
    }
  }
}

// Handle a `{{#if}}/{{else}}/{{/if}}` (and `{{#each}}` / `{{#unless}}` /
// `{{#let}}`) AST node.
//
// Branch selection:
//   - When `ctx.branchSelections` has an entry for this block's start
//     offset (multipass driver), honor that choice.
//   - Otherwise, fall back to the form-submit-aware heuristic: emit the
//     program (truthy) branch by default, switch to the inverse only
//     when it's the only branch with a `<button type='submit'>`. Avoids
//     the most common single-branch FP (wcag/h32) without needing the
//     full multipass machinery.
function handleBlockStatement(node: AST.BlockStatement, ctx: Context): void {
  const { blankRanges, fullyBlankedRanges } = ctx;
  const wholeStart = startOffset(node);
  if (ctx.inFullyBlankedRange(wholeStart)) {
    return;
  }
  const programStart = startOffset(node.program);
  const programEnd = endOffset(node.program);
  const inverse = node.inverse;
  const wholeEnd = endOffset(node);

  if (!inverse) {
    blankRanges.push([wholeStart, programStart]);
    blankRanges.push([programEnd, wholeEnd]);
    return;
  }

  // Branch selection: caller-driven (multipass) or heuristic.
  let preferInverse: boolean;
  const explicit = ctx.branchSelections?.get(wholeStart);
  if (explicit !== undefined) {
    preferInverse = explicit === 'inverse';
  } else {
    const programHasSubmit = blockHasSubmitButton(node.program);
    const inverseHasSubmit = blockHasSubmitButton(inverse);
    preferInverse = inverseHasSubmit && !programHasSubmit;
  }

  if (preferInverse) {
    const inverseFirst = inverse.body[0]?.loc?.getStart().offset;
    const inverseLast = inverse.body[inverse.body.length - 1]?.loc?.getEnd().offset;
    if (typeof inverseFirst === 'number' && typeof inverseLast === 'number') {
      blankRanges.push([wholeStart, inverseFirst]);
      fullyBlankedRanges.push([wholeStart, inverseFirst]);
      blankRanges.push([inverseLast, wholeEnd]);
      fullyBlankedRanges.push([inverseLast, wholeEnd]);
      return;
    }
    // Fall through to default if we couldn't locate the inverse body.
  }

  // Default: emit program, blank inverse + closing marker.
  blankRanges.push([wholeStart, programStart]);
  blankRanges.push([programEnd, wholeEnd]);
  fullyBlankedRanges.push([programEnd, wholeEnd]);
}

// ---------------------------------------------------------------------------
// Public entry point.
// ---------------------------------------------------------------------------

export interface AttrInjection {
  attr: string;
  // null → inject DynamicValue placeholder at parse time.
  // string → inject this literal value (e.g. 'checkbox' for <input type>).
  value: string | null;
}

export interface BlankResult {
  content: string;
  error: Error | null;
  dynamicContentOffsets: number[];
  // Per-offset attribute injections — applied at parse-time by
  // transform.ts's `processElement` hook via `setAttribute`. See
  // `Context.attrInjections` for rationale.
  attrInjections: Map<number, AttrInjection[]>;
  // Per-element rule disables — applied at parse-time by transform.ts's
  // `processElement` hook via `el.disableRules(...)`. Keys are template-
  // relative source offsets of the element start (matching the
  // `dynamicContentOffsets` / `attrInjections` coordinate system); values
  // are rule IDs to disable on that element. Used for surgical per-
  // element suppression that doesn't bleed across siblings — e.g., one
  // `<table>` with a cell-loop FP doesn't silence a real `wcag/h63`
  // violation on a sibling `<table>`.
  //
  // All structural-rule suppressions (wcag/h32, wcag/h63, wcag/h67,
  // wcag/h71, element-permitted-content, element-permitted-parent,
  // element-required-content) currently land here, not as file-level
  // disable directives. The non-multipass branched directive prefix is
  // empty for these sources.
  //
  // For rules that fire on descendants (e.g. wcag/h63 reports on each
  // `<th>` inside a `<table>`), the entry is keyed by the DESCENDANT
  // offsets, not the container's — html-validate's `disableRules` only
  // affects the node it's called on, not its children.
  disablePerElement: Map<number, Set<string>>;
}

export interface BlankErrorResult {
  content: string;
  error: Error;
  dynamicContentOffsets?: undefined;
  attrInjections?: undefined;
  disablePerElement?: undefined;
}

function blankTemplateContent(
  content: string,
  scope?: ReadonlyMap<string, string>,
  glintTypeMap?: ReadonlyMap<string, AttrTypeInfo> | null,
  glintComponentTagMap?: ReadonlyMap<string, string> | null,
  glintComponentAttrMap?: ReadonlyMap<string, ComponentAttrs> | null,
  branchSelections?: ReadonlyMap<number, BranchChoice>,
): BlankResult | BlankErrorResult {
  let ast: AST.Template;
  try {
    // `mode: 'codemod'` preserves source-level distinctions we care about
    // (e.g. long-form `{{!-- ... --}}` vs short-form `{{! ... }}` comments;
    // exact whitespace) — same flag `ember-estree` uses for its
    // `templateOnly: true` path.
    ast = parseTemplate(content);
  } catch (err) {
    return { content, error: err instanceof Error ? err : new Error(String(err)) };
  }

  const ctx: Context = {
    content,
    scope,
    glintTypeMap,
    glintComponentTagMap,
    glintComponentAttrMap,
    blankRanges: [],
    renames: [],
    fullyBlankedRanges: [],
    dynamicContentOffsets: [],
    attrInjections: new Map(),
    branchSelections,
    inFullyBlankedRange(offset: number): boolean {
      for (const [s, e] of ctx.fullyBlankedRanges) {
        if (offset >= s && offset < e) {
          return true;
        }
      }
      return false;
    },
  };

  traverse(ast, {
    ElementNode(node) {
      handleElementNode(node, ctx);
    },
    MustacheStatement(node) {
      handleMustacheStatement(node, ctx);
    },
    MustacheCommentStatement(node) {
      handleMustacheCommentStatement(node, ctx);
    },
    BlockStatement(node) {
      handleBlockStatement(node, ctx);
    },
  });

  // Apply the rewrite plan. Blank ranges first (everything overwritten
  // becomes spaces, except newlines which we preserve for line accounting),
  // then renames, which override blanks at overlapping positions.
  const buf = content.split('');

  ctx.blankRanges.sort((a, b) => a[0] - b[0]);
  const merged: Range[] = [];
  for (const [s, e] of ctx.blankRanges) {
    const last = merged[merged.length - 1];
    if (last && last[1] >= s) {
      last[1] = Math.max(last[1], e);
    } else {
      merged.push([s, e]);
    }
  }
  for (const [start, end] of merged) {
    for (let i = start; i < end && i < buf.length; i++) {
      if (buf[i] !== '\n' && buf[i] !== '\r') {
        buf[i] = ' ';
      }
    }
  }

  for (const [start, end, replacement] of ctx.renames) {
    if (replacement.length !== end - start) {
      continue;
    }
    for (let i = 0; i < replacement.length; i++) {
      buf[start + i] = replacement[i]!;
    }
  }

  return {
    content: buf.join(''),
    error: null,
    dynamicContentOffsets: ctx.dynamicContentOffsets,
    attrInjections: ctx.attrInjections,
    disablePerElement: detectSuppressions(
      ast,
      branchSelections,
      glintComponentTagMap,
      glintComponentAttrMap,
    ),
  };
}

// Detect cases where a structural rule would FP-fire on the blanked
// output, and register per-element `disableRules` entries so the
// transformer's `processElement` hook calls them at parse time on the
// specific nodes whose rule-firing would be a Glimmer-opacity FP.
//
// FP classes covered today:
//
//   1. Yield-bearing `<form>`/`<fieldset>` that lacks a statically-
//      detectable submit/legend (the suppression target rule fires
//      because the yield was blanked away).
//
//   2. Input-driven `<form {{on "input" …}}>` — search-as-you-type /
//      live-filter pattern; submit button would be ceremonial.
//
//   3. Curried-via-yield-hash patterns the resolver can't pin: an
//      unresolvable PascalCase wrapper containing structural children
//      (`<li>`/`<option>`/`<th>`/...), OR a structural-content-parent
//      wrapper (`<ol>`/`<select>`/...) with a transparent dotted
//      direct child. The runtime DOM has the structurally-correct
//      parent via a yield chain we can't statically follow (e.g.
//      `(yield (hash X=PassThrough))` where PassThrough yields
//      without producing an element). Suppress
//      `element-permitted-content` / `element-permitted-parent` on
//      the affected children.
//
//   4. wcag/h63 on `<table>` shapes the blanker has flattened —
//      cell-generating `{{#each}}` / `{{#if}}` blocks, or PascalCase
//      row components Glint resolves to `<tr>`/`<td>`/`<th>`. The
//      per-`<th>` disable lands on each header cell descendant.
//
//   5. wcag/h67 on `<img alt='' title='{{x}}'>`-shaped patterns
//      (incl. ConcatStatement titles with whitespace-only literals).
//      The per-`<img>` disable lands on the element itself.
//
//   6. wcag/h32 on `<form>`s whose only submit candidate is dynamic-
//      typed or splatted. The per-`<form>` disable lands on the form.
//
//   7. element-required-content on self-closing component invocations
//      that resolve to native elements with required content (e.g.
//      `<details>` requires `<summary>`).
//
// 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
// `handleBlockStatement` uses) so each emitted Source's per-element
// disables match its own blanked content. When no selection is
// present (HVE_MAX_CONDITIONAL_BRANCHES=0 single-pass mode) we mirror
// `handleBlockStatement`'s heuristic: prefer program, switch to
// inverse only when inverse has a static submit and program doesn't.
//
// Component-aware. Component invocations that resolve to native
// `<button>`/`<input>` via Glint or builtin maps count as static
// submit when their splatted-root attrs make them submit-style — a
// `<MyButton>` resolving to `<button type='submit' ...attributes>`
// means wcag/h32 wouldn't fire on the blanked output (substitution
// emits a real submit), so registering a per-element disable for it
// would be unnecessary.
//
// Dynamic types as positive suppression signal. `<button type={{x}}>`
// and `<input type={{x}}>` set `hasAmbiguousSubmit` in
// `elementYieldsAndLacksSubmit`, triggering wcag/h32 suppression on
// the form (per Mel #38: when the validator can't determine code
// structure, the technique-rule shouldn't fire). The prior trade-off
// — treating these as "MAYBE-submit" that DISqualifies suppression to
// avoid `no-unused-disable` cascades — no longer applies under the
// per-element migration: there's no directive comment to be "unused",
// and the rule WOULD fire on the blanked output regardless (the
// placeholder isn't recognized as 'submit'), so the per-element
// `disableRules` is load-bearing.
//
// Returns the per-element suppression map (`Map<offset, Set<rule>>`)
// — keys are template-relative source offsets, values are the rules
// to disable on that element via `processElement → el.disableRules`.
// Per-element scope is used for every FP class listed above; a
// Glimmer-opacity FP on one element doesn't silence real violations
// on its siblings.
function detectSuppressions(
  ast: AST.Template,
  branchSelections?: ReadonlyMap<number, BranchChoice>,
  glintComponentTagMap?: ReadonlyMap<string, string> | null,
  glintComponentAttrMap?: ReadonlyMap<string, ComponentAttrs> | null,
): Map<number, Set<string>> {
  const perElement = new Map<number, Set<string>>();
  function addPer(offset: number, rule: string): void {
    const set = perElement.get(offset);
    if (set) {
      set.add(rule);
    } else {
      perElement.set(offset, new Set([rule]));
    }
  }
  function collectThOffsets(
    stmts: ReadonlyArray<AST.Statement>,
    into: number[],
  ): void {
    for (const stmt of stmts) {
      if (stmt.type === 'BlockStatement') {
        const arm = selectBranch(stmt, branchSelections);
        if (arm) collectThOffsets(arm.body, into);
        continue;
      }
      if (stmt.type === 'ElementNode') {
        if (stmt.tag === 'th') {
          into.push(startOffset(stmt));
        } else if (!isNativeTag(stmt.tag) && glintComponentTagMap && stmt.loc.start) {
          // Component invocation resolving to `<th>` via Glint (e.g.
          // `<MyHeaderCell />` with `Element: HTMLTableCellElement` and
          // a `<th>` root). `tableHasGlimmerObscuredCells` treats these
          // as cell tags that trigger suppression; without collecting
          // their offsets here the per-`<th>` `disableRules` wouldn't
          // land on the substituted output.
          const key = `${stmt.loc.start.line}:${stmt.loc.start.column}`;
          if (glintComponentTagMap.get(key) === 'th') into.push(startOffset(stmt));
        }
        collectThOffsets(stmt.children, into);
      }
    }
  }
  // For the STRUCTURAL_CONTENT_PARENT + transparent-dotted-child
  // branch only: collect offsets of the element children of any
  // transparent dotted node — these "float up" to the wrapper after
  // the dotted node's open/close tags are blanked away, and the
  // wrapper's content-model rule fires on them. The transparent
  // dotted node itself is blanked away, so `disableRules` on its
  // offset never runs at parse time — register on the floating
  // children instead. Skips siblings of transparent dotted children
  // (those stay as their own non-transparent parent's content; any
  // rule fire on them is a real-bug shape that must still surface).
  function collectTransparentDottedChildOffsets(
    node: AST.ElementNode,
    into: number[],
  ): void {
    if (!glintComponentTagMap) return;
    const tagMap = glintComponentTagMap;
    function isTransparentDotted(el: AST.ElementNode): boolean {
      if (!el.tag.includes('.')) return false;
      if (!el.loc.start) return false;
      return tagMap.get(`${el.loc.start.line}:${el.loc.start.column}`) === 'transparent';
    }
    function collectFloatingChildren(stmts: ReadonlyArray<AST.Statement>): void {
      // Direct element children of a transparent dotted node float
      // up to the wrapper. If a floating child is ITSELF transparent
      // dotted, its own direct children float further up to the same
      // wrapper — recurse.
      for (const stmt of stmts) {
        if (stmt.type === 'BlockStatement') {
          const arm = selectBranch(stmt, branchSelections);
          if (arm) collectFloatingChildren(arm.body);
          continue;
        }
        if (stmt.type !== 'ElementNode') continue;
        if (stmt.tag.startsWith(':')) {
          // Named block (`<:body>`) renders nothing itself; its content
          // floats into the parent slot — descend without recording it.
          collectFloatingChildren(stmt.children);
          continue;
        }
        into.push(startOffset(stmt));
        if (isTransparentDotted(stmt)) collectFloatingChildren(stmt.children);
      }
    }
    function walk(stmts: ReadonlyArray<AST.Statement>): void {
      for (const stmt of stmts) {
        if (stmt.type === 'BlockStatement') {
          const arm = selectBranch(stmt, branchSelections);
          if (arm) walk(arm.body);
          continue;
        }
        if (stmt.type !== 'ElementNode') continue;
        if (stmt.tag.startsWith(':')) {
          // Named block (`<:body as |B|>`) — descend to find the
          // transparent dotted cells (`<B.Tr>`) nested inside.
          walk(stmt.children);
          continue;
        }
        if (isTransparentDotted(stmt)) {
          collectFloatingChildren(stmt.children);
        }
        // Don't descend into non-transparent children — they keep
        // their own non-transparent parent at runtime, so the
        // wrapper's content-model concern doesn't apply to their
        // descendants.
      }
    }
    walk(node.children);
  }

  // For wrapper-with-content-restricted-children cases (element-
  // permitted-content / -parent): walk the wrapper's descendants and
  // record every child element that html-validate would flag. The
  // rules fire on the CHILD, not on the wrapper, so per-element
  // disable must land on each child.
  function collectContentRestrictedChildOffsets(
    node: AST.ElementNode,
    into: number[],
  ): void {
    function walk(stmts: ReadonlyArray<AST.Statement>): void {
      for (const stmt of stmts) {
        if (stmt.type === 'ElementNode') {
          if (CONTENT_RESTRICTED_STRUCTURAL_CHILDREN.has(stmt.tag)) {
            into.push(startOffset(stmt));
          }
          if (stmt.tag.includes('.') && glintComponentTagMap && stmt.loc.start) {
            const resolved = glintComponentTagMap.get(
              `${stmt.loc.start.line}:${stmt.loc.start.column}`,
            );
            if (
              resolved &&
              (CONTENT_RESTRICTED_STRUCTURAL_CHILDREN.has(resolved) || resolved === 'transparent')
            ) {
              into.push(startOffset(stmt));
            }
          }
          walk(stmt.children);
        } else if (stmt.type === 'BlockStatement') {
          const arm = selectBranch(stmt, branchSelections);
          if (arm) walk(arm.body);
        }
      }
    }
    walk(node.children);
  }
  // Top-level elements the consumer passes into the listed blocks.
  // Children outside any `<:named>` block belong to `default`.
  function collectNestedBlockContentOffsets(
    node: AST.ElementNode,
    blocks: ReadonlyArray<string>,
    into: number[],
  ): void {
    function collect(stmts: ReadonlyArray<AST.Statement>): void {
      for (const stmt of stmts) {
        if (stmt.type === 'BlockStatement') {
          const arm = selectBranch(stmt, branchSelections);
          if (arm) collect(arm.body);
        } else if (stmt.type === 'ElementNode') {
          into.push(startOffset(stmt));
        }
      }
    }
    const defaultContent: AST.Statement[] = [];
    for (const child of node.children) {
      if (child.type === 'ElementNode' && child.tag.startsWith(':')) {
        if (blocks.includes(child.tag.slice(1))) collect(child.children);
      } else {
        defaultContent.push(child);
      }
    }
    if (blocks.includes('default')) collect(defaultContent);
  }
  // Custom walk — the off-the-shelf `traverse` would visit forms /
  // fieldsets that live entirely in a blanked-out branch for the
  // current pass, leaking their suppression rules into
  // `disablePerElement` and silently suppressing real violations on
  // the actually-emitted output (false negatives). At every
  // BlockStatement we descend ONLY into the selected arm — the same
  // selection `handleBlockStatement` makes, so this matches what the
  // blanker actually emits in this pass.
  function walk(stmts: ReadonlyArray<AST.TopLevelStatement | AST.Statement>): void {
    for (const stmt of stmts) {
      if (stmt.type === 'BlockStatement') {
        const arm = selectBranch(stmt, branchSelections);
        if (arm) walk(arm.body);
        continue;
      }
      if (stmt.type === 'ElementNode') {
        // 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') {
          // `stmtResolved === 'form'` is reached two ways: the consumer
          // wrote a literal `<form>` (native tag), OR a PascalCase /
          // dotted component invocation resolved to `<form>` via the
          // tag map. In the latter case the form's body — including any
          // submit button — lives in the COMPONENT's own template, not
          // at this call site. The blanker only substitutes the root
          // tag, so the substituted `<form>` carries at most the
          // consumer's own children (none for `<MyForm />`; whatever
          // the consumer wrote for `<MyForm>…</MyForm>`) and never the
          // component's own submit. `wcag/h32` fires on the substituted
          // <form>; per-form disable scopes the suppression to this
          // specific form.
          const formTagFromComponentSubstitution = !isNativeTag(stmt.tag);
          if (
            formHasInputModifier(stmt) ||
            elementYieldsAndLacksSubmit(
              stmt,
              branchSelections,
              glintComponentTagMap,
              glintComponentAttrMap,
              formTagFromComponentSubstitution,
            )
          ) {
            addPer(startOffset(stmt), 'wcag/h32');
          }
        } else if (
          stmtResolved === 'fieldset' &&
          elementYieldsAndLacksLegend(stmt, branchSelections)
        ) {
          // wcag/h71 fires on the <fieldset>; per-fieldset disable.
          addPer(startOffset(stmt), 'wcag/h71');
        } else if (
          !isNativeTag(stmt.tag) &&
          !lookupBuiltinComponent(stmt.tag) &&
          containsContentRestrictedStructuralChild(stmt, glintComponentTagMap, branchSelections)
        ) {
          // 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 we
          // can't statically pin. element-permitted-content and
          // element-permitted-parent fire on the offending CHILDREN;
          // per-child disable.
          const offsets: number[] = [];
          collectContentRestrictedChildOffsets(stmt, offsets);
          for (const off of offsets) {
            addPer(off, 'element-permitted-content');
            addPer(off, 'element-permitted-parent');
          }
        } else if (
          stmt.selfClosing &&
          stmtResolved &&
          ELEMENTS_WITH_REQUIRED_CONTENT.has(stmtResolved)
        ) {
          // Self-closing component invocation that resolves to a
          // native element with required content (`<details>` requires
          // `<summary>`, `<head>` requires `<title>`, etc.). The
          // blanker substitutes the self-closing form to a
          // `<resolved>...</resolved>` paired-tag pair around an
          // empty body — element-required-content fires on the
          // substituted element itself.
          addPer(startOffset(stmt), 'element-required-content');
        } else if (
          stmtResolved &&
          STRUCTURAL_CONTENT_PARENTS.has(stmtResolved) &&
          hasTransparentCurriedChild(stmt, glintComponentTagMap, branchSelections)
        ) {
          // Mirror: WRAPPER is a structural-content-restrictive native
          // (`<ol>`, `<select>`, …) AND has a dotted direct child that
          // resolves to 'transparent' (curried-via-yield-hash —
          // `<HdsStepperList as |S|><S.Step>...`). Static blanking
          // can't see through `<S.Step>`. Per-child disable on the
          // transparent dotted children themselves and on any
          // structural-child descendants nested INSIDE them — never on
          // sibling structural-child literals elsewhere under the
          // wrapper (those are real-bug shapes that should still fire).
          const offsets: number[] = [];
          collectTransparentDottedChildOffsets(stmt, offsets);
          for (const off of offsets) {
            addPer(off, 'element-permitted-content');
            addPer(off, 'element-permitted-parent');
          }
        }
        // wcag/h63 & wcag/h67: per-element. h63 fires on each <th>
        // descendant, so disable per-<th>; h67 fires on the <img>.
        if (stmtResolved === 'img' && imgHasDynamicTitle(stmt)) {
          addPer(startOffset(stmt), 'wcag/h67');
        } else if (
          stmtResolved === 'table' &&
          tableHasGlimmerObscuredCells(stmt, branchSelections, glintComponentTagMap)
        ) {
          const thOffsets: number[] = [];
          collectThOffsets(stmt.children, thOffsets);
          for (const off of thOffsets) addPer(off, 'wcag/h63');
        }
        const nestedYieldBlocks = stmtKey ? glintComponentAttrMap?.get(stmtKey)?.nestedYieldBlocks : undefined;
        if (nestedYieldBlocks) {
          // Content of a block whose `{{yield}}` sits below the component's
          // root lands under the root in the blanked output, but under a
          // deeper element at runtime (`<table>` vs its `<td>`/`<tbody>`).
          const offsets: number[] = [];
          collectNestedBlockContentOffsets(stmt, nestedYieldBlocks, offsets);
          for (const off of offsets) {
            for (const rule of PARENT_DEPENDENT_RULES) addPer(off, rule);
          }
        }
        walk(stmt.children);
      }
    }
  }
  walk(ast.body);
  return perElement;
}

// Pick a single arm of `{{#if}}/{{else}}` to walk — mirrors the
// selection in `handleBlockStatement` so the decision matches what the
// blanker actually emits in each pass.
function selectBranch(
  block: AST.BlockStatement,
  branchSelections: ReadonlyMap<number, BranchChoice> | undefined,
): AST.Block | null {
  if (!block.inverse) return block.program;
  const explicit = branchSelections?.get(startOffset(block));
  if (explicit !== undefined) {
    return explicit === 'inverse' ? block.inverse : block.program;
  }
  const programHasSubmit = blockHasSubmitButton(block.program);
  const inverseHasSubmit = blockHasSubmitButton(block.inverse);
  return inverseHasSubmit && !programHasSubmit ? block.inverse : block.program;
}

// True when a `<form>` has an opaque body source AND no statically-
// detectable submit-style child. Two opaque sources:
//
//   - `{{yield}}` / `{{has-block}}` somewhere in the body: the consumer
//     might supply a submit button at runtime (PR #17).
//   - `formTagFromComponentSubstitution`: the `<form>` tag is itself
//     the resolved root of a component invocation (`<MyForm />` or
//     `<MyForm>…</MyForm>` → `<form>`). The form's real body lives in
//     the component's own template; the blanker only substitutes the
//     root tag, so the substituted `<form>` carries at most the
//     consumer's own children and never the component's submit button,
//     regardless of what the component renders inside (issue #34).
//
// Either way the absence of a static submit means wcag/h32 would
// FP-fire on the blanked output, so the suppression is needed.
//
// If a static submit DOES exist (here, among the children the consumer
// projects through the component's `{{yield}}`), wcag/h32 wouldn't
// fire and the per-element disable would target a form that doesn't
// need it. So we bail in that case.
//
// "Statically-detectable submit" means a `<button>` whose `type` is
// absent (default `submit` inside a form) or statically equals
// `submit` (ASCII case-insensitive); a `<button type='button'>` /
// `type='reset'` is explicitly non-submit and does NOT disqualify.
// For `<input>`, `type='submit'` / `type='image'` (case-insensitive)
// counts. Bare-mustache types are NOT static submit — they're handled
// separately as `hasAmbiguousSubmit` (positive suppression trigger).
// True when a `<form>` carries an event modifier that signals
// input-event-driven UX (rather than submission-driven). Two events
// trigger the suppression:
//   - `{{on "input" …}}` — search-as-you-type / live-filter; updates
//     on every keystroke.
//   - `{{on "change" …}}` — commit-on-blur / per-field-commit; the
//     form's action runs as fields are committed individually rather
//     than on a final submit.
//
// Both patterns make a separate submit button ceremonial. Conservative
// on the event-name argument: we require a static string literal;
// bare-mustache event names like `{{on @event …}}` could resolve to
// anything at runtime, so we don't trust them as a suppression signal.
const INPUT_DRIVEN_FORM_EVENTS: ReadonlySet<string> = new Set(['input', 'change']);

// Rules that judge an element by its parent or ancestors.
const PARENT_DEPENDENT_RULES: ReadonlyArray<string> = [
  'element-permitted-content',
  'element-permitted-parent',
  'element-permitted-order',
  'element-required-ancestor',
  'prefer-tbody',
];

const STRUCTURAL_CONTENT_PARENTS: ReadonlySet<string> = new Set([
  'ol', 'ul', 'menu', 'select', 'optgroup', 'table', 'thead', 'tbody',
  'tfoot', 'tr', 'colgroup', 'fieldset', 'details', 'picture', 'ruby', 'dl',
]);

// Native elements with `requiredContent` per html-validate's HTML5
// metadata. When a PascalCase component invocation resolves to one of
// these AND is self-closing at the consumer's call site, the blanker
// substitutes to `<resolved>...</resolved>` paired tags around an
// empty body — html-validate fires `element-required-content` because
// it can't see the required child the addon's template renders.
const ELEMENTS_WITH_REQUIRED_CONTENT: ReadonlySet<string> = (() => {
  const out = new Set<string>();
  for (const [tag, meta] of Object.entries(html5Schema as MetaDataTable)) {
    if (tag === '*' || tag.startsWith('#')) continue;
    const required = (meta as { requiredContent?: ReadonlyArray<unknown> })?.requiredContent;
    if (Array.isArray(required) && required.length > 0) out.add(tag);
  }
  return out;
})();

(function validateStructuralSetsAgainstHtml5Schema(): void {
  const namedChildren = new Set<string>();
  const parentsWithNamedChildren = new Set<string>();
  for (const [tag, meta] of Object.entries(html5Schema as MetaDataTable)) {
    if (tag === '*' || tag.startsWith('#')) continue;
    const permitted = (meta as { permittedContent?: ReadonlyArray<unknown> })?.permittedContent;
    if (!Array.isArray(permitted)) continue;
    let hasNamed = false;
    for (const entry of permitted) {
      if (typeof entry !== 'string') continue;
      if (entry.startsWith('@')) continue;
      namedChildren.add(entry.replace(/[?*+]$/, ''));
      hasNamed = true;
    }
    if (hasNamed) parentsWithNamedChildren.add(tag);
  }
  for (const c of CONTENT_RESTRICTED_STRUCTURAL_CHILDREN) {
    if (!namedChildren.has(c)) {
      throw new Error(
        `[html-validate-ember] '${c}' is no longer a named-child entry in any HTML5 element's permittedContent — html-validate metadata may have changed`,
      );
    }
  }
  for (const p of STRUCTURAL_CONTENT_PARENTS) {
    if (!parentsWithNamedChildren.has(p)) {
      throw new Error(
        `[html-validate-ember] '${p}' no longer lists named children in HTML5 permittedContent — html-validate metadata may have changed`,
      );
    }
  }
})();

// True when an `<img>` element has a `title` attribute whose value
// is entirely dynamic in a way the blanker can't faithfully model.
// Three shapes count:
//
//   1. `title={{x}}` (MustacheStatement)
//   2. `title='{{x}}'` / `title='{{x}}{{y}}'` (ConcatStatement with
//      only MustacheStatement parts)
//   3. `title=' {{x}} '` (ConcatStatement with MustacheStatement
//      parts plus TextNode parts that are only whitespace) — the
//      runtime title is effectively `<whitespace><value><whitespace>`,
//      which AT typically trim; treat as semantically dynamic
//
// In all three, the runtime title may legitimately be empty (or
// effectively empty after AT trimming), but the blanker substitutes
// a whitespace placeholder that html-validate's H67 treats as non-
// empty. ConcatStatement values with any non-whitespace TextNode
// part (e.g., `title='pre-{{x}}'`) keep a literal portion that pins
// them as non-empty at runtime, so those stay in scope for the rule.
function imgHasDynamicTitle(node: AST.ElementNode): boolean {
  for (const attr of node.attributes) {
    if (attr.name !== 'title') continue;
    if (attr.value.type === 'MustacheStatement') return true;
    if (attr.value.type === 'ConcatStatement') {
      return attr.value.parts.every(
        (p) => p.type === 'MustacheStatement' || (p.type === 'TextNode' && p.chars.trim() === ''),
      );
    }
    return false;
  }
  return false;
}

// True when a `<table>` descendant has cells whose runtime shape the
// blanker can't faithfully represent. Two sources of obscurity:
//
//   1. A block (`{{#each}}`, `{{#if}}`, `{{#unless}}`) whose body's
//      top-level children include a `<td>` / `<th>` / `<tr>` — the
//      block iterates/conditionally renders cells (or rows). After
//      blanking, only the single representative iteration survives,
//      so row widths observed by html-validate diverge from runtime
//      widths.
//
//   2. A PascalCase / dotted component invocation that resolves (via
//      Glint or the canonical resolver) to `<tr>` / `<td>` / `<th>`.
//      The blanker substitutes the tag but the cell content lives in
//      the component's own template — so substituted rows come out
//      empty (`<tr></tr>` with no children), mismatching the static
//      `<thead>` row widths.
//
// Either way, `wcag/h63`'s `isSimpleTable` check sees an irregular
// table, decides "not simple", and requires `scope` on every `<th>` —
// FP-firing on the static header cells of what's a structurally-regular
// runtime table. Suppress when our blanker has demonstrably collapsed
// cell information; the same conditional-suppression pattern as
// `wcag/h32` / `wcag/h71` here.
//
// We walk into nested elements (`<thead>`, `<tbody>`, `<tr>`) and into
// block arms (using the same selectBranch convention as the rest of
// this file) so that, e.g., `{{#if cond}}<tr>…</tr>{{/if}}` inside a
// `<tbody>` is detected, as is `{{#each cols}}<th>…</th>{{/each}}`
// inside a `<thead>` `<tr>`, and `<MyRow />` inside a `<tbody>`.
function tableHasGlimmerObscuredCells(
  table: AST.ElementNode,
  branchSelections?: ReadonlyMap<number, BranchChoice>,
  glintComponentTagMap?: ReadonlyMap<string, string> | null,
): boolean {
  function resolveTag(node: AST.ElementNode): string | null {
    if (isNativeTag(node.tag)) return node.tag.toLowerCase();
    if (!glintComponentTagMap || !node.loc.start) return null;
    const key = `${node.loc.start.line}:${node.loc.start.column}`;
    return glintComponentTagMap.get(key) ?? null;
  }
  function isCellTag(tag: string | null): boolean {
    return tag === 'td' || tag === 'th' || tag === 'tr';
  }
  function inspect(stmts: ReadonlyArray<AST.Statement>): boolean {
    for (const stmt of stmts) {
      if (stmt.type === 'BlockStatement') {
        const arm = selectBranch(stmt, branchSelections);
        if (!arm) continue;
        // Direct cells inside the block body — the block IS the
        // cell-loop we're looking for.
        for (const child of arm.body) {
          if (child.type === 'ElementNode' && isCellTag(resolveTag(child))) return true;
        }
        // Nested blocks (`{{#if}}` inside `{{#each}}`, etc.).
        if (inspect(arm.body)) return true;
      } else if (stmt.type === 'ElementNode') {
        // PascalCase / dotted component that resolves to a cell tag —
        // the substituted output has the cell tag but the content
        // lives in the component's own template.
        if (!isNativeTag(stmt.tag) && isCellTag(resolveTag(stmt))) return true;
        if (inspect(stmt.children)) return true;
      }
    }
    return false;
  }
  return inspect(table.children);
}

// True when `node` has at least one direct child that is a dotted
// PascalCase invocation (`<S.Step>`, `<This.Foo>`) whose resolution
// is 'transparent' — i.e. a curried-via-yield-hash component the
// resolver couldn't pin to a specific native tag.
function hasTransparentCurriedChild(
  node: AST.ElementNode,
  glintComponentTagMap: ReadonlyMap<string, string> | null | undefined,
  branchSelections?: ReadonlyMap<number, BranchChoice>,
): boolean {
  if (!glintComponentTagMap) return false;
  const tagMap = glintComponentTagMap;
  function check(stmts: ReadonlyArray<AST.Statement>): boolean {
    for (const stmt of stmts) {
      if (stmt.type === 'ElementNode') {
        // Named block (`<:body as |B|>`) renders nothing itself; descend
        // to find transparent dotted cells (`<B.Tr>`) nested inside.
        if (stmt.tag.startsWith(':')) {
          if (check(stmt.children)) return true;
          continue;
        }
        if (!stmt.tag.includes('.')) continue;
        if (!stmt.loc.start) continue;
        const childKey = `${stmt.loc.start.line}:${stmt.loc.start.column}`;
        const childResolved = tagMap.get(childKey);
        if (childResolved === 'transparent') return true;
      } else if (stmt.type === 'BlockStatement') {
        const arm = selectBranch(stmt, branchSelections);
        if (arm && check(arm.body)) return true;
      }
    }
    return false;
  }
  return check(node.children);
}

// True when the element node has a direct child that is either a
// native structural-child element (literal `<li>`/`<th>`/...) under
// an unpinned wrapper, OR a dotted curried sub-component that resolved
// to a structural tag. Two cases:
//
//  A) Wrapper unresolved/transparent: literal structural children
//     suggest the wrapper renders the structurally-correct parent at
//     runtime via yield chain. Trigger.
//
//  B) Wrapper pinned to a native tag, dotted child resolves to a
//     structural tag (HdsTabs as |T|<T.Tab>): the curried child's
//     runtime parent may be a different native ancestor in the parent
//     template (the `(hash Tab=...)` lands inside `<ul role="tablist">`
//     not the wrapper's outer `<div>`). Gate to DOTTED tag names —
//     a non-dotted child like `<HdsListItem>` under a pinned wrapper
//     IS the wrapper's runtime parent, so suppressing there would
//     mask real bugs.
function containsContentRestrictedStructuralChild(
  node: AST.ElementNode,
  glintComponentTagMap: ReadonlyMap<string, string> | null | undefined,
  branchSelections?: ReadonlyMap<number, BranchChoice>,
): boolean {
  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) && !wrapperPinned) {
          return true;
        }
        if (glintComponentTagMap && stmt.loc.start && stmt.tag.includes('.')) {
          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;
          }
          // (B') Descend through dotted children to find structural-
          // child literals NESTED inside, when the dotted child's
          // resolution doesn't pin it to a tag whose runtime DOM is
          // believably the structural parent of the literal.
          //
          // We TRUST the dotted child's resolution when it lands on a
          // structural-content-parent (`<select>`/`<ul>`/`<tr>`/...).
          // In that case structural-literal mismatches are real bugs
          // we want surfaced (the `glint-resolved-no-suppression`
          // fixture: `<C.Options>` resolved to `<select>`, contains
          // `<th>` literal — `<th>` under `<select>` is a real bug,
          // don't suppress).
          //
          // We DON'T trust when:
          //   - childResolved === 'transparent' / undefined: the
          //     resolver couldn't pin it; runtime tag is the curried
          //     yield-hash target which we can't trace.
          //   - childResolved is a NON-structural-parent tag (e.g.
          //     'div'): Glint's chain may have narrowed to an outer
          //     wrapper's element type. The structural literals
          //     inside still go to their canonical structural parent
          //     at runtime via the yield chain.
          const trustsResolution =
            typeof childResolved === 'string' &&
            STRUCTURAL_CONTENT_PARENTS.has(childResolved);
          if (!trustsResolution && containsLiteralStructuralChild(stmt, branchSelections)) {
            return true;
          }
        }
      } else if (stmt.type === 'BlockStatement') {
        const arm = selectBranch(stmt, branchSelections);
        if (arm && check(arm.body)) return true;
      }
    }
    return false;
  }
  return check(node.children);
}

// Recursive descent looking for a literal structural-child tag
// (`<option>`, `<li>`, etc.) anywhere inside `node`. Used to detect
// when a transparent/unresolved curried dotted child wraps content
// that the runtime DOM puts in a structural parent, even though our
// immediate-children check missed it.
function containsLiteralStructuralChild(
  node: AST.ElementNode,
  branchSelections: ReadonlyMap<number, BranchChoice> | undefined,
): boolean {
  function walk(stmts: ReadonlyArray<AST.Statement>): boolean {
    for (const stmt of stmts) {
      if (stmt.type === 'ElementNode') {
        if (CONTENT_RESTRICTED_STRUCTURAL_CHILDREN.has(stmt.tag)) return true;
        if (walk(stmt.children)) return true;
      } else if (stmt.type === 'BlockStatement') {
        const arm = selectBranch(stmt, branchSelections);
        if (arm && walk(arm.body)) return true;
      }
    }
    return false;
  }
  return walk(node.children);
}

// HTML elements with restrictive content models — they only accept
// specific native parents. When these appear as children of an
function formHasInputModifier(form: AST.ElementNode): boolean {
  for (const modifier of form.modifiers ?? []) {
    if (modifier.path.type !== 'PathExpression') continue;
    if (modifier.path.original !== 'on') continue;
    const firstParam = modifier.params?.[0];
    if (firstParam?.type === 'StringLiteral' && INPUT_DRIVEN_FORM_EVENTS.has(firstParam.value)) {
      return true;
    }
  }
  return false;
}

function elementYieldsAndLacksSubmit(
  form: AST.ElementNode,
  branchSelections: ReadonlyMap<number, BranchChoice> | undefined,
  glintComponentTagMap: ReadonlyMap<string, string> | null | undefined,
  glintComponentAttrMap: ReadonlyMap<string, ComponentAttrs> | null | undefined,
  // True when this `<form>` is the substituted root of a component
  // invocation rather than a literal consumer-written `<form>`. The
  // component owns the form body, so the blanked call site can never
  // show the component's own submit button. Treated as an opaque body
  // source — same role as `{{yield}}`. See the header comment.
  formTagFromComponentSubstitution = false,
): boolean {
  let hasYield = false;
  let hasStaticSubmit = false;
  // Form contains a dynamic-typed `<button>` / `<input>`, an `<input
  // ...attributes>` / `<button ...attributes>`, or a PascalCase /
  // dotted component invocation whose Glint resolution lands on a
  // button/input with ambiguous type. In all three cases the actual
  // runtime type could be 'submit' (no FP, no real bug) or anything
  // else (real bug). The blanker can't determine the structure →
  // suppress wcag/h32 per Mel #38's principle. The per-element
  // disable lands on a form that WOULD have fired wcag/h32 anyway
  // (the placeholder type isn't recognized as 'submit'), so the
  // suppression is well-targeted.
  let hasAmbiguousSubmit = 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;
      if (stmt.type === 'MustacheStatement') {
        if (
          stmt.path.type === 'PathExpression' &&
          (stmt.path.original === 'yield' || stmt.path.original === 'has-block')
        ) {
          hasYield = true;
        }
        continue;
      }
      if (stmt.type === 'BlockStatement') {
        const arm = selectBranch(stmt, branchSelections);
        if (arm) walk(arm.body);
        continue;
      }
      if (stmt.type === 'ElementNode') {
        if (isStaticSubmitButton(stmt) || isSubmitInput(stmt)) {
          hasStaticSubmit = true;
          return;
        }
        if (isAmbiguouslyTypedInputOrButton(stmt) || isInputOrButtonWithSplat(stmt)) {
          // Dynamic-type (`<button type='{{x}}'>`) or splatted
          // (`<input ...attributes>`) submit candidate. We can't
          // know the runtime type → wcag/h32 fires on the blanked
          // output (the placeholder isn't recognized as 'submit').
          // Trigger per-element suppression on the form.
          hasAmbiguousSubmit = true;
        }
        const componentSubmit = classifyComponentSubmit(
          stmt,
          glintComponentTagMap,
          glintComponentAttrMap,
        );
        if (componentSubmit === 'static-submit') {
          hasStaticSubmit = true;
          return;
        }
        if (componentSubmit === 'ambiguous') {
          hasAmbiguousSubmit = true;
        }
        // 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. 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 (isDotted || resolved === undefined || resolved === 'transparent') {
            hasUnresolvedComponent = true;
          }
        }
        walk(stmt.children);
        continue;
      }
    }
  }
  walk(form.children);
  // Suppress wcag/h32 for an opaque-source form: yield-bearing (PR #17),
  // a form whose only "candidates" for submit are unresolved component
  // invocations (heuristic above), an ambiguous-typed inline submit
  // candidate (`hasAmbiguousSubmit`), OR a `<form>` that is itself a
  // component substitution whose body lives in the component's
  // template (issue #34) — in every case the blanked call site can't
  // show a real submit. A static submit among the consumer's own
  // children still disqualifies (the per-element disable would target
  // a form that wouldn't have fired wcag/h32 anyway).
  return (
    (hasYield ||
      hasUnresolvedComponent ||
      formTagFromComponentSubstitution ||
      hasAmbiguousSubmit) &&
    !hasStaticSubmit
  );
}

// True when a `<fieldset>` body has opaque legend-source content AND
// no statically-detectable `<legend>` child. "Opaque legend-source"
// means either a literal `{{yield}}` / `{{has-block}}` mustache OR a
// non-native tag (component invocation) — components may render their
// own `<legend>` at runtime, and we can't see inside them, so we err
// toward suppression rather than letting wcag/h71 FP-fire.
//
// The component-invocation case handles ember-primitives' OTP-input
// pattern: `<fieldset>{{#if (has-block)}}{{yield}}{{else}}<C />{{/if}}`.
// In multipass the inverse arm produces `<C />` only — without this
// rule the walker would see no yield, no legend, and let h71 fire.
function elementYieldsAndLacksLegend(
  fieldset: AST.ElementNode,
  branchSelections: ReadonlyMap<number, BranchChoice> | undefined,
): boolean {
  let hasOpaqueLegendSource = false;
  let hasStaticLegend = false;
  function walk(stmts: ReadonlyArray<AST.Statement>): void {
    for (const stmt of stmts) {
      if (hasStaticLegend) return;
      if (stmt.type === 'MustacheStatement') {
        if (
          stmt.path.type === 'PathExpression' &&
          (stmt.path.original === 'yield' || stmt.path.original === 'has-block')
        ) {
          hasOpaqueLegendSource = true;
        }
        continue;
      }
      if (stmt.type === 'BlockStatement') {
        const arm = selectBranch(stmt, branchSelections);
        if (arm) walk(arm.body);
        continue;
      }
      if (stmt.type === 'ElementNode') {
        if (stmt.tag === 'legend') {
          hasStaticLegend = true;
          return;
        }
        // Component invocation (PascalCase / dotted / `:slot`) may
        // render `<legend>` at runtime — treat as legend-source.
        if (!isNativeTag(stmt.tag)) {
          hasOpaqueLegendSource = true;
        }
        walk(stmt.children);
        continue;
      }
    }
  }
  walk(fieldset.children);
  return hasOpaqueLegendSource && !hasStaticLegend;
}

// `<button>` with no `type` attribute (default = submit inside a form)
// or with a static `type='submit'` (ASCII case-insensitive). Explicit
// `type='button'` / `type='reset'` returns false.
function isStaticSubmitButton(node: AST.ElementNode): boolean {
  if (node.tag !== 'button') return false;
  for (const attr of node.attributes ?? []) {
    if (attr.name !== 'type') continue;
    if (attr.value.type === 'TextNode') {
      return attr.value.chars.toLowerCase() === 'submit';
    }
    // Dynamic value — handled by isAmbiguouslyTypedInputOrButton.
    return false;
  }
  return true;
}

function isSubmitInput(node: AST.ElementNode): boolean {
  if (node.tag !== 'input') return false;
  for (const attr of node.attributes ?? []) {
    if (attr.name !== 'type') continue;
    if (attr.value.type === 'TextNode') {
      const v = attr.value.chars.toLowerCase();
      return v === 'submit' || v === 'image';
    }
    return false;
  }
  return false;
}

function isAmbiguouslyTypedInputOrButton(node: AST.ElementNode): boolean {
  if (node.tag !== 'input' && node.tag !== 'button') return false;
  for (const attr of node.attributes ?? []) {
    if (attr.name !== 'type') continue;
    // Bare-mustache or concat-mustache value: type unknown statically;
    // could be 'submit' at runtime. Bail conservatively.
    if (attr.value.type !== 'TextNode') return true;
  }
  return false;
}

// True for `<input ...attributes>` / `<button ...attributes>`. The
// consumer can pass `type='submit'` / `type='image'` through the
// splat at runtime; the blanker can't see the splatted attrs.
function isInputOrButtonWithSplat(node: AST.ElementNode): boolean {
  if (node.tag !== 'input' && node.tag !== 'button') return false;
  return (node.attributes ?? []).some((a) => a.name === '...attributes');
}

// Classification of a component invocation's relationship to "this
// might satisfy `<form>`'s submit requirement at runtime." Returned
// by `classifyComponentSubmit`, which examines Glint's resolved tag
// and recorded `type` attribute for the invocation.
//
//   'static-submit'  — the component definitively renders a submit
//                      control (e.g. `<button>` with no type, or
//                      `<button type='submit'>`). Triggers
//                      `hasStaticSubmit`, blocking suppression so we
//                      don't register a per-element disable on a
//                      form that wouldn't have fired wcag/h32 anyway.
//   'ambiguous'      — the component might or might not be a submit
//                      at runtime (e.g. `<button>` with dynamic
//                      `type='{{x}}'`). Triggers `hasAmbiguousSubmit`
//                      → suppress wcag/h32 via per-element disable
//                      on the form (the rule WILL fire on the
//                      blanked output because the placeholder isn't
//                      recognized as 'submit', so the disable is
//                      well-targeted).
//   'not-submit'     — definitively non-submit OR not a button/input
//                      at all. Doesn't affect suppression decisions.
//
// Glint-only on purpose: the implementation bails to 'not-submit'
// when `glintComponentTagMap` is falsy. The plugin's builtin map
// (used by `handleGlintSubstitution` for `<Input>` / `<Textarea>` /
// `<LinkTo>` in non-Glint runs) doesn't currently feed into submit
// detection here. In practice the builtins that map to `<input>` are
// rarely used as submit buttons, so the missing fallback hasn't
// surfaced as a real FP. Add it if a real-world target hits this case.
function classifyComponentSubmit(
  node: AST.ElementNode,
  glintComponentTagMap: ReadonlyMap<string, string> | null | undefined,
  glintComponentAttrMap: ReadonlyMap<string, ComponentAttrs> | null | undefined,
): 'static-submit' | 'ambiguous' | 'not-submit' {
  if (isNativeTag(node.tag)) return 'not-submit';
  if (!glintComponentTagMap || !node.loc.start) return 'not-submit';
  const key = `${node.loc.start.line}:${node.loc.start.column}`;
  const resolvedTag = glintComponentTagMap.get(key);
  if (resolvedTag !== 'button' && resolvedTag !== 'input') return 'not-submit';
  const recordedType = glintComponentAttrMap?.get(key)?.attrs?.['type'];
  if (recordedType === undefined) {
    // No static type recorded by the component-attrs extractor.
    // For <button>: default IS submit per HTML → static submit.
    // For <input>: default is 'text' → not submit.
    return resolvedTag === 'button' ? 'static-submit' : 'not-submit';
  }
  if (/^\s+$/u.test(recordedType)) {
    // DynamicValue placeholder — type is bare-mustache at the splatted
    // root; could resolve to 'submit' at runtime.
    return 'ambiguous';
  }
  const v = recordedType.toLowerCase();
  if (resolvedTag === 'button') {
    return v === 'submit' ? 'static-submit' : 'not-submit';
  }
  return v === 'submit' || v === 'image' ? 'static-submit' : 'not-submit';
}

// True when the branch's body contains nothing the validator can see —
// only mustaches (`{{yield}}`, helpers, dynamic values), mustache
// comments, and whitespace. Selecting such a branch in multipass would
// emit a blanked DOM with no real children; presence-style rules
// (`wcag/h32` "form must have submit", `empty-heading`, `text-content`)
// then FP-fire because they don't know the runtime DOM might contain
// anything via the yield.
//
// Anything structural — native elements, component invocations, nested
// blocks — counts as real content and disqualifies the branch from
// "opaque-only".
function isBranchOpaqueOnly(branch: AST.Block): boolean {
  for (const stmt of branch.body) {
    if (stmt.type === 'TextNode') {
      if (stmt.chars.trim() !== '') return false;
      continue;
    }
    if (stmt.type === 'MustacheStatement' || stmt.type === 'MustacheCommentStatement') {
      continue;
    }
    return false;
  }
  return true;
}

// Multipass branch validation.
//
// Single-branch emission (`blankTemplateContent` without
// `branchSelections`) silently drops errors that live in unselected
// branches of a `{{#if}}/{{else}}` (or `{{else if}}` chain). Multipass
// fixes that by enumerating branch combinations and emitting one
// `BlankResult` per combination — each represents one possible runtime
// DOM. The caller (typically `transform.ts`) yields one html-validate
// `Source` per result so each combination is validated independently.
//
// Combinations are capped at maxConditionalBranches (count, not
// combinations) — templates with more conditional branches fall back
// to the first maxConditionalBranches in pre-order document order
// and ignore the rest. A "conditional branch" here is any block that
// has both a program and an `{{else}}` clause — `{{#if}}/{{else}}`,
// `{{#unless}}/{{else}}`, `{{#each}}/{{else}}` (empty fallback).
// Worst-case work is 2^maxConditionalBranches blanker calls when all
// branches are siblings; nested branches enumerate fewer combinations
// (see "Tree-aware enumeration" below).
//
// maxConditionalBranches defaults to 10 (worst case 2^10 = 1024
// blanker calls — cheap on real templates because nesting is more
// common than wide sibling lists, so tree-aware enumeration usually
// produces far fewer combinations). Override via the
// `HVE_MAX_CONDITIONAL_BRANCHES` env var. The env var is read
// per-call (not cached at module load) so flag-driven changes from
// the CLI take effect even when this module is imported eagerly.
// N=0 yields a single combination with no explicit selections,
// making multipass equivalent to the single-branch heuristic.
//
// Tree-aware enumeration: branches are organized into a tree where
// inner branches are children of the arm they're nested in. When a
// branch's program is selected, only its `programChildren` are
// enumerated; when its inverse is selected, only `inverseChildren`.
// The "blanked-out arm" is invisible to validation regardless of
// inner choices, so enumerating those choices would just produce
// duplicates that the dedupe collapses. Skipping them up front is
// strictly faster on nested templates: e.g. 6 branches chained
// down through `{{else}}` arms produces 7 combinations rather than
// 64.
//
// Identical outputs are still deduped via the `seen` Set — covers
// degenerate cases where two arms produce the same blanked text
// (e.g., both arms render `<div/>`).
//
// Trade-off vs single-pass: each yielded source is independently
// validated, so an error that's stable across branches (e.g., a
// misnested element OUTSIDE the if/else) gets reported once per
// combination. The caller may want to dedupe by (line, column,
// ruleId, message). Branch-internal errors land at distinct positions
// per branch and don't dedup.
function readMaxConditionalBranches(): number {
  const raw = process.env['HVE_MAX_CONDITIONAL_BRANCHES'];
  if (raw === undefined) return 10;
  // Strict integer parse — `parseInt` accepts partial numerics
  // (`"5abc"` → 5) which would silently change behavior on typos,
  // including accidentally disabling multipass when someone meant
  // to set a small cap (e.g. `"0abc"` → 0).
  if (!/^\d+$/.test(raw)) return 10;
  const n = Number(raw);
  return Number.isSafeInteger(n) ? n : 10;
}
function blankTemplateContentMultipass(
  content: string,
  scope?: ReadonlyMap<string, string>,
  glintTypeMap?: ReadonlyMap<string, AttrTypeInfo> | null,
  glintComponentTagMap?: ReadonlyMap<string, string> | null,
  glintComponentAttrMap?: ReadonlyMap<string, ComponentAttrs> | null,
): Array<BlankResult | BlankErrorResult> {
  // Cap=0 disables multipass — the tree would be empty anyway, and
  // every fallback path below ends in a single `blankTemplateContent`
  // call. Short-circuit before the local `parseTemplate()` so the
  // disable path parses once instead of twice.
  const cap = readMaxConditionalBranches();
  if (cap === 0) {
    return [
      blankTemplateContent(content, scope, glintTypeMap, glintComponentTagMap, glintComponentAttrMap),
    ];
  }
  let ast: AST.Template;
  try {
    ast = parseTemplate(content);
  } catch (err) {
    return [{ content, error: err instanceof Error ? err : new Error(String(err)) }];
  }

  // Collect conditional branches as a tree, preserving nesting. A
  // conditional branch is any `BlockStatement` with both a program
  // and an inverse (`{{#if/else}}`, `{{#unless/else}}`,
  // `{{#each/else}}`). Children of a branch are split by the arm
  // they live in: `programChildren` if nested in the program arm,
  // `inverseChildren` if nested in the inverse arm. The enumerator
  // below uses this split to skip enumerating an arm's nested
  // branches when that arm is blanked — i.e., when the *other* arm
  // is selected. Those nested choices can't influence the blanked
  // output, so enumerating them would just produce duplicates that
  // the `seen` dedupe later collapses. For deeply-nested templates
  // this turns exponential waste into a single pass per reachable
  // runtime DOM.
  //
  // The cap is on total branch count in pre-order document order —
  // surplus branches don't appear in the tree at all and the
  // form-submit-aware single-branch heuristic decides for them.
  // Opaque-only arms are recorded so the enumerator can skip them
  // (avoids presence-style FPs).
  interface ConditionalBranch {
    offset: number;
    opaqueProgram: boolean;
    opaqueInverse: boolean;
    programChildren: ConditionalBranch[];
    inverseChildren: ConditionalBranch[];
  }
  let included = 0;

  function collect(
    nodes: ReadonlyArray<AST.Statement | AST.TopLevelStatement>,
    out: ConditionalBranch[],
  ): void {
    for (const node of nodes) {
      if (included >= cap) return;
      if (node.type === 'BlockStatement') {
        if (node.inverse) {
          included++;
          const branch: ConditionalBranch = {
            offset: startOffset(node),
            opaqueProgram: isBranchOpaqueOnly(node.program),
            opaqueInverse: isBranchOpaqueOnly(node.inverse),
            programChildren: [],
            inverseChildren: [],
          };
          collect(node.program.body, branch.programChildren);
          collect(node.inverse.body, branch.inverseChildren);
          out.push(branch);
        } else {
          // Non-branching block (`{{#each}}` without `{{else}}`,
          // `{{#let}}`, etc.) — its body may contain branches, but
          // they belong to the current arm.
          collect(node.program.body, out);
        }
      } else if (node.type === 'ElementNode') {
        collect(node.children, out);
      }
    }
  }

  const tree: ConditionalBranch[] = [];
  collect(ast.body, tree);

  if (tree.length === 0) {
    return [
      blankTemplateContent(content, scope, glintTypeMap, glintComponentTagMap, glintComponentAttrMap),
    ];
  }

  // Tree-aware enumeration: for each sibling list, take the cross
  // product of (this branch's reachable sub-combinations) × (the
  // remaining siblings' enumerations). Choosing `program` for a
  // branch unlocks its `programChildren`; choosing `inverse` unlocks
  // its `inverseChildren`. Opaque-only arms are skipped — and if
  // both arms are opaque the branch contributes nothing, leaving
  // its parent enumeration empty for that path.
  //
  // Subtlety: if a non-opaque arm's child enumeration yields no
  // combinations (e.g., the arm contains a nested branch whose
  // both arms are opaque-only), we still need to emit the outer
  // arm — its non-nested DOM content (`<div>X</div>` outside the
  // nested if/else) is reachable at runtime and must be validated.
  // The nested branch then falls to the single-branch heuristic
  // inside `blankTemplateContent`. Without this fall-through, the
  // outer.program selection would silently disappear and any DOM
  // outside the nested if/else would be permanently blanked.
  function* enumerate(
    siblings: ReadonlyArray<ConditionalBranch>,
  ): Iterable<ReadonlyMap<number, BranchChoice>> {
    if (siblings.length === 0) {
      yield new Map();
      return;
    }
    const first = siblings[0]!;
    const rest = siblings.slice(1);
    for (const restSel of enumerate(rest)) {
      if (!first.opaqueProgram) {
        let yielded = false;
        for (const innerSel of enumerate(first.programChildren)) {
          yielded = true;
          const sel = new Map<number, BranchChoice>(restSel);
          sel.set(first.offset, 'program');
          for (const [k, v] of innerSel) sel.set(k, v);
          yield sel;
        }
        if (!yielded) {
          const sel = new Map<number, BranchChoice>(restSel);
          sel.set(first.offset, 'program');
          yield sel;
        }
      }
      if (!first.opaqueInverse) {
        let yielded = false;
        for (const innerSel of enumerate(first.inverseChildren)) {
          yielded = true;
          const sel = new Map<number, BranchChoice>(restSel);
          sel.set(first.offset, 'inverse');
          for (const [k, v] of innerSel) sel.set(k, v);
          yield sel;
        }
        if (!yielded) {
          const sel = new Map<number, BranchChoice>(restSel);
          sel.set(first.offset, 'inverse');
          yield sel;
        }
      }
    }
  }

  const results: Array<BlankResult | BlankErrorResult> = [];
  const seen = new Set<string>();

  for (const selections of enumerate(tree)) {
    const result = blankTemplateContent(
      content,
      scope,
      glintTypeMap,
      glintComponentTagMap,
      glintComponentAttrMap,
      selections,
    );
    if (result.error) {
      // Parse failure is the same for every combination — no point
      // running the rest.
      return [result];
    }
    if (!seen.has(result.content)) {
      seen.add(result.content);
      results.push(result);
    }
  }

  // Every combination selected at least one opaque-only branch — fall
  // back to a single heuristic-driven pass so we still validate the
  // template's stable (outside-of-branch) content.
  if (results.length === 0) {
    return [
      blankTemplateContent(content, scope, glintTypeMap, glintComponentTagMap, glintComponentAttrMap),
    ];
  }

  return results;
}

export { blankTemplateContent, blankTemplateContentMultipass, isComponentTag, isNativeTag };