npm - @agent-native/core - Versions diffs - 0.134.0 → 0.135.0 - Mend

@agent-native/core 0.134.0 → 0.135.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (493) hide show

package/corpus/templates/design/shared/html-integrity.ts CHANGED Viewed

@@ -1,3 +1,6 @@
+import { parse as parseJavaScript } from "acorn";
+import { type DefaultTreeAdapterTypes, parse, type ParserError } from "parse5";
 import { isStandaloneHttpUrl } from "./html-content.js";
 /**
@@ -23,6 +26,8 @@ export type DesignHtmlIntegrityIssue =
   | "managed-marker-orphaned"
   | "managed-marker-duplicated"
   | "attribute-unterminated"
+  | "expression-invalid"
+  | "script-invalid"
   | "element-unclosed"
   | "close-tag-orphaned"
   | "content-truncated"
@@ -44,6 +49,8 @@ export interface DesignHtmlIntegrityIssueDetail {
   excerpt: string;
   tag?: string;
   attribute?: string;
+  /** The parser's reason, for `expression-invalid`. */
+  reason?: string;
   /** The tag that arrived where this element's close belonged, if any. */
   closedBy?: { tag: string; line: number };
 }
@@ -86,6 +93,21 @@ export function describeDesignHtmlIntegrityIssue(
 ): string {
   const at = `line ${detail.line} col ${detail.column}`;
   switch (detail.issue) {
+    case "expression-invalid":
+      return (
+        `the ${detail.attribute ? `\`${detail.attribute}\`` : "Alpine"} expression on ` +
+        `<${detail.tag ?? "element"}> at ${at} is not valid JavaScript: ` +
+        `${detail.reason ?? "it does not parse"}. The HTML attribute itself is ` +
+        `well-formed, so the document parses and the element renders — but Alpine ` +
+        `compiles this value and throws, which aborts every binding on the component.`
+      );
+    case "script-invalid":
+      return (
+        `the inline <script> at ${at} is not valid JavaScript: ` +
+        `${detail.reason ?? "it does not parse"}. The document still parses and ` +
+        `the page still renders, so nothing visibly fails — the script simply ` +
+        `never runs, and everything it was going to wire up stays dead.`
+      );
     case "attribute-unterminated":
       return (
         `the ${detail.attribute ? `\`${detail.attribute}\`` : "attribute"} value on ` +
@@ -155,14 +177,7 @@ export class DesignHtmlIntegrityError extends Error {
   }
 }
-/**
- * Bodies are text, not markup — mis-tokenizing these turns a `'</div>'` string
- * inside Alpine JavaScript into a phantom structural error. Both passes must
- * agree on this set: when only one treated `<title>`/`<textarea>` as raw text,
- * literal `<body>` text inside a title reached the root-tag count as real markup.
- */
 const RAW_TEXT_TAGS = new Set(["script", "style", "textarea", "title"]);
-type RawTextTag = "script" | "style" | "textarea" | "title";
 const MANAGED_RAW_TEXT_MARKERS = [
   { marker: "data-agent-native-breakpoints", tag: "style" },
@@ -172,232 +187,7 @@ const MANAGED_RAW_TEXT_MARKERS = [
   { marker: "data-agent-native-shader-runtime", tag: "script" },
 ] as const;
-interface RawTextScan {
-  severity: number;
-  bodyRanges: Array<{ start: number; end: number }>;
-}
-function matchFallsInsideRanges(
-  index: number,
-  ranges: RawTextScan["bodyRanges"],
-): boolean {
-  return ranges.some((range) => index >= range.start && index < range.end);
-}
-function countMatchesOutsideRanges(
-  value: string,
-  pattern: RegExp,
-  ranges: RawTextScan["bodyRanges"],
-  requireMarkupStart = false,
-): number {
-  return Array.from(value.matchAll(pattern)).filter((match) => {
-    // Root-tag-shaped strings inside quoted Alpine attributes and comments
-    // are data, not document structure. Counting them here made an otherwise
-    // valid document look like it had duplicate <html>/<body>/<head> roots.
-    // Every caller of this helper is counting a markup token, so require the
-    // tokenizer to agree that the candidate starts outside those contexts.
-    return (
-      match.index !== undefined &&
-      !matchFallsInsideRanges(match.index, ranges) &&
-      (!requireMarkupStart ||
-        matchStartsMarkupToken(value, match.index, ranges))
-    );
-  }).length;
-}
-function firstMatchOutsideRanges(
-  value: string,
-  pattern: RegExp,
-  ranges: RawTextScan["bodyRanges"],
-): { index: number; text: string } | null {
-  const match = Array.from(value.matchAll(pattern)).find(
-    (candidate) =>
-      candidate.index !== undefined &&
-      !matchFallsInsideRanges(candidate.index, ranges) &&
-      matchStartsMarkupToken(value, candidate.index, ranges),
-  );
-  return match?.index === undefined
-    ? null
-    : { index: match.index, text: match[0] };
-}
-function matchStartsMarkupToken(
-  value: string,
-  index: number,
-  rawTextBodyRanges: RawTextScan["bodyRanges"],
-): boolean {
-  if (matchFallsInsideRanges(index, rawTextBodyRanges)) return false;
-  // A bare regex also finds tag-shaped strings in Alpine attributes and HTML
-  // comments, for example `x-data="{ sample: '>' + '<html></html>' }"`.
-  // Walk the markup tokenizer state up to the candidate so a `>` inside a
-  // quoted attribute cannot fool a last-delimiter heuristic into treating the
-  // following string as a real root tag.
-  let inTag = false;
-  let quote: '"' | "'" | null = null;
-  let rawRangeIndex = 0;
-  for (let cursor = 0; cursor <= index; cursor += 1) {
-    while (
-      rawRangeIndex < rawTextBodyRanges.length &&
-      cursor >= rawTextBodyRanges[rawRangeIndex]!.end
-    ) {
-      rawRangeIndex += 1;
-    }
-    const rawRange = rawTextBodyRanges[rawRangeIndex];
-    if (!inTag && rawRange) {
-      if (cursor >= rawRange.start && cursor < rawRange.end) {
-        if (index < rawRange.end) return false;
-        cursor = rawRange.end - 1;
-        continue;
-      }
-    }
-    if (!inTag && value.startsWith("<!--", cursor)) {
-      const commentEnd = value.indexOf("-->", cursor + 4);
-      if (commentEnd === -1 || index < commentEnd + 3) return false;
-      cursor = commentEnd + 2;
-      continue;
-    }
-    const character = value[cursor];
-    if (!inTag) {
-      if (character !== "<") continue;
-      if (cursor === index) return true;
-      inTag = true;
-      quote = null;
-      continue;
-    }
-    if (quote) {
-      if (character === quote) quote = null;
-      continue;
-    }
-    if (character === '"' || character === "'") {
-      quote = character;
-    } else if (character === ">") {
-      inTag = false;
-    }
-  }
-  return false;
-}
-function isDocumentHtml(
-  value: string,
-  rawTextBodyRanges = scanRawTextTags(value).bodyRanges,
-): boolean {
-  return [
-    ...value.matchAll(/<!doctype\s+html\b/gi),
-    ...value.matchAll(/<html\b/gi),
-  ].some(
-    (match) =>
-      match.index !== undefined &&
-      matchStartsMarkupToken(value, match.index, rawTextBodyRanges),
-  );
-}
-function stripBoundaryNoise(value: string): string {
-  return value
-    .replace(/^\uFEFF/, "")
-    .replace(/<!--(?:[\s\S]*?)-->/g, "")
-    .trim();
-}
-function tagCount(
-  value: string,
-  tag: "html" | "head" | "body",
-  ranges: RawTextScan["bodyRanges"],
-) {
-  return {
-    open: countMatchesOutsideRanges(
-      value,
-      new RegExp(`<${tag}\\b[^>]*>`, "gi"),
-      ranges,
-      true,
-    ),
-    close: countMatchesOutsideRanges(
-      value,
-      new RegExp(`<\\s*\\/\\s*${tag}\\s*>`, "gi"),
-      ranges,
-      true,
-    ),
-  };
-}
-function scanRawTextTags(value: string): RawTextScan {
-  // HTML raw-text bodies may legitimately contain strings such as
-  // `<style>...</style>` inside JavaScript. Once a real style/script opener is
-  // seen, ignore every tag-like token except that element's own closer. This
-  // mirrors browser tokenization closely enough to avoid rejecting code-heavy
-  // Alpine documents while still detecting an orphaned closer/missing opener.
-  let active: RawTextTag | null = null;
-  let bodyStart = -1;
-  let severity = 0;
-  const bodyRanges: RawTextScan["bodyRanges"] = [];
-  let cursor = 0;
-  while (cursor < value.length) {
-    if (active) {
-      // HTML raw-text elements terminate at the first matching end-tag token,
-      // even when that text happens to look like a JavaScript/CSS string.
-      const closer = new RegExp(`<\\s*\\/\\s*${active}(?=[\\s/>])[^>]*>`, "gi");
-      closer.lastIndex = cursor;
-      const match = closer.exec(value);
-      if (!match) break;
-      bodyRanges.push({ start: bodyStart, end: match.index });
-      active = null;
-      bodyStart = -1;
-      cursor = match.index + match[0].length;
-      continue;
-    }
-    const nextOpen = value.indexOf("<", cursor);
-    if (nextOpen === -1) break;
-    if (value.startsWith("<!--", nextOpen)) {
-      const commentEnd = value.indexOf("-->", nextOpen + 4);
-      cursor = commentEnd === -1 ? value.length : commentEnd + 3;
-      continue;
-    }
-    // Consume one complete markup token while respecting quoted attributes.
-    // This is the important distinction from the former bare regex: an
-    // Alpine value such as x-data="{ sample: '<style></style>' }" must not
-    // open raw-text mode halfway through the surrounding start tag.
-    let quote: '"' | "'" | null = null;
-    let tokenEnd = nextOpen + 1;
-    for (; tokenEnd < value.length; tokenEnd += 1) {
-      const character = value[tokenEnd];
-      if (quote) {
-        if (character === quote) quote = null;
-      } else if (character === '"' || character === "'") {
-        quote = character;
-      } else if (character === ">") {
-        tokenEnd += 1;
-        break;
-      }
-    }
-    const token = value.slice(nextOpen, tokenEnd);
-    const match = token.match(/^<\s*(\/?)\s*([a-zA-Z][a-zA-Z0-9:-]*)\b/i);
-    if (match && RAW_TEXT_TAGS.has(match[2]!.toLowerCase())) {
-      const closing = match[1] === "/";
-      const tag = match[2]!.toLowerCase() as RawTextTag;
-      if (closing) severity += 1;
-      else {
-        active = tag;
-        bodyStart = tokenEnd;
-      }
-    }
-    cursor = Math.max(tokenEnd, nextOpen + 1);
-  }
-  if (active) bodyRanges.push({ start: bodyStart, end: value.length });
-  return { severity: severity + (active ? 1 : 0), bodyRanges };
-}
-// ---------------------------------------------------------------------------
-// Structural pass. Counting tokens is blind to order, so an unclosed <div> or
-// a stray </section> leaves every root count above intact — those need a stack
-// walk, and they are the defects browsers recover from most invisibly.
-// ---------------------------------------------------------------------------
-/** Closing tag is forbidden, so these never reach the stack. */
+/** Closing tag is forbidden, so the tree never records an end tag for these. */
 const VOID_TAGS = new Set([
   "area",
   "base",
@@ -416,8 +206,9 @@ const VOID_TAGS = new Set([
 ]);
 /**
- * Closing tag optional per HTML5, so omitting one is legal authoring.
- * `html`/`head`/`body` belong here because the counting pass already owns them.
+ * Closing tag optional per HTML5, so a missing end tag is legal authoring. The
+ * parser decides which element an implied close terminates; this set only
+ * decides what not to report.
  */
 const OPTIONAL_CLOSE_TAGS = new Set([
   "body",
@@ -443,21 +234,6 @@ const OPTIONAL_CLOSE_TAGS = new Set([
   "tr",
 ]);
-/** Opening one of these implicitly closes the listed open sibling. */
-const IMPLICIT_SIBLING_CLOSE = new Map<string, Set<string>>([
-  ["li", new Set(["li"])],
-  ["p", new Set(["p"])],
-  ["td", new Set(["td", "th"])],
-  ["th", new Set(["td", "th"])],
-  ["tr", new Set(["tr", "td", "th"])],
-  ["dt", new Set(["dt", "dd"])],
-  ["dd", new Set(["dt", "dd"])],
-  ["option", new Set(["option"])],
-  ["optgroup", new Set(["optgroup", "option"])],
-  ["tbody", new Set(["thead", "tbody", "tr", "td", "th"])],
-  ["tfoot", new Set(["thead", "tbody", "tr", "td", "th"])],
-]);
 const MAX_EXCERPT_CHARS = 120;
 /**
@@ -467,6 +243,26 @@ const MAX_EXCERPT_CHARS = 120;
 const USES_TAILWIND_UTILITIES =
   /\bclass\s*=\s*["'][^"']*(?:\b(?:flex|grid|hidden|absolute|relative|sticky)\b|\b(?:p|m|px|py|mx|my|pt|pb|pl|pr|gap|w|h|text|bg|border|rounded|shadow|items|justify|font|leading|tracking|space-x|space-y|min-h|max-w|opacity|ring|z)-[a-z0-9[\]./-]+)/i;
+/**
+ * Parse errors that mean the source was cut off or mis-delimited. The rest of
+ * what the spec reports is recoverable authoring the browser accepts, and
+ * `missing-doctype` fires on legitimate fragments and on real screens.
+ */
+/**
+ * Ordered by cause, not by offset: every one of these is reported at EOF, and an
+ * unterminated tag absorbs the rest of the document — including the closer of
+ * whatever raw-text element it sits in. Reporting the imbalance instead sends
+ * the fix to a `</script>` that is present and correct.
+ */
+const FATAL_PARSE_ERRORS = [
+  "eof-in-tag",
+  "eof-in-comment",
+  "eof-in-cdata",
+  "eof-in-script-html-comment-like-text",
+  "eof-in-element-that-can-contain-only-text",
+  "eof-before-tag-name",
+];
 type Locator = (index: number) => {
   line: number;
   column: number;
@@ -474,9 +270,9 @@ type Locator = (index: number) => {
 };
 /**
- * Scanning to the offset per call made validation quadratic on VALID documents,
- * not just malformed ones — a 117KB screen cost ~700ms on every save. Index the
- * line starts once, lazily, and binary search.
+ * Indexed once, lazily, then binary searched. Scanning to the offset per call
+ * made validation quadratic on VALID documents, not just malformed ones — a
+ * 117KB screen cost ~700ms on every save.
  */
 function createLocator(value: string): Locator {
   let starts: number[] | null = null;
@@ -509,230 +305,655 @@ function createLocator(value: string): Locator {
   };
 }
-interface TagScan {
-  end: number;
-  /** False when EOF arrived before the tag's `>`. */
-  terminated: boolean;
-  /** Whether EOF arrived inside a quoted value — the truncation cause. */
-  quoteOpen: boolean;
-  /** The attribute that quote belonged to, when one was named. */
-  unterminatedAttribute?: string;
+// ---------------------------------------------------------------------------
+// Parse layer
+// ---------------------------------------------------------------------------
+// One parse and one walk feed every check below, so no two can disagree about
+// whether a `<body>` inside a `<title>` was markup.
+type Parse5Node = DefaultTreeAdapterTypes.Node;
+type Parse5Element = DefaultTreeAdapterTypes.Element;
+type SourceRange = { start: number; end: number };
+type SourceOffsets = { startOffset: number; endOffset: number };
+interface ParsedDocument {
+  source: string;
+  document: DefaultTreeAdapterTypes.Document;
+  errors: ParserError[];
+  /** Source extents to exclude when looking for markup tokens in the source. */
+  rawTextBodies: SourceRange[];
+  comments: SourceRange[];
+  attributeRanges: SourceRange[];
+  /** Start offsets of the end tags the parser matched to an element. */
+  matchedEndTags: Set<number>;
+  elements: Parse5Element[];
+  textNodes: DefaultTreeAdapterTypes.TextNode[];
+  parents: Map<Parse5Node, Parse5Element>;
+}
+function isElement(node: Parse5Node): node is Parse5Element {
+  return typeof (node as Parse5Element).tagName === "string";
+}
+/** Only elements carry tag spans; the tree types every node's location as one union. */
+interface ElementSpan extends SourceOffsets {
+  startTag?: SourceOffsets;
+  endTag?: SourceOffsets;
+  attrs?: Record<string, SourceOffsets>;
+}
+function locationOf(element: Parse5Element | undefined): ElementSpan | null {
+  if (!element) return null;
+  return (element.sourceCodeLocation as ElementSpan | null) ?? null;
 }
 /**
- * A raw-text end tag only closes the element when the name is followed by
- * whitespace, `/`, or `>`. Matching on a word boundary instead treats script
- * text like `"</script=template>"` as the closer, which orphans the real one.
+ * A `<template>`'s children hang off `content`, not `childNodes`. Missing them
+ * leaves every element inside an `x-for`/`x-if` template unvisited, so its close
+ * tag looks like it belongs to nothing.
  */
-function rawTextCloser(tag: string): RegExp {
-  return new RegExp(`<\\s*/\\s*${tag}(?=[\\s/>])`, "gi");
-}
-/** Consume one markup token starting at `start` (the `<`), honoring quotes. */
-function scanTag(value: string, start: number): TagScan {
-  let quote: '"' | "'" | null = null;
-  let pendingAttribute: string | undefined;
-  let quotedAttribute: string | undefined;
-  let word = "";
-  for (let cursor = start; cursor < value.length; cursor += 1) {
-    const character = value[cursor]!;
-    if (quote) {
-      if (character === quote) {
-        quote = null;
-        quotedAttribute = undefined;
-      }
-      continue;
-    }
-    if (character === '"' || character === "'") {
-      quote = character;
-      quotedAttribute = pendingAttribute;
-      continue;
+function childrenOf(node: Parse5Node): Parse5Node[] {
+  const element = node as {
+    childNodes?: Parse5Node[];
+    content?: { childNodes?: Parse5Node[] };
+  };
+  return [
+    ...(element.childNodes ?? []),
+    ...(element.content?.childNodes ?? []),
+  ];
+}
+function parseDocument(source: string): ParsedDocument {
+  const errors: ParserError[] = [];
+  const document = parse(source, {
+    sourceCodeLocationInfo: true,
+    onParseError: (error) => errors.push(error),
+  });
+  const rawTextBodies: SourceRange[] = [];
+  const comments: SourceRange[] = [];
+  const attributeRanges: SourceRange[] = [];
+  const matchedEndTags = new Set<number>();
+  const elements: Parse5Element[] = [];
+  const textNodes: DefaultTreeAdapterTypes.TextNode[] = [];
+  const parents = new Map<Parse5Node, Parse5Element>();
+  const stack: Parse5Node[] = [document];
+  while (stack.length > 0) {
+    const node = stack.pop()!;
+    const location = node.sourceCodeLocation;
+    if (node.nodeName === "#comment" && location) {
+      comments.push({ start: location.startOffset, end: location.endOffset });
     }
-    if (character === ">") {
-      return { end: cursor + 1, terminated: true, quoteOpen: false };
+    if (node.nodeName === "#text") {
+      textNodes.push(node as DefaultTreeAdapterTypes.TextNode);
     }
-    if (character === "=") {
-      if (word) pendingAttribute = word;
-      word = "";
-      continue;
+    if (isElement(node)) {
+      elements.push(node);
+      const elementAt = locationOf(node);
+      for (const attribute of Object.values(elementAt?.attrs ?? {})) {
+        attributeRanges.push({
+          start: attribute.startOffset,
+          end: attribute.endOffset,
+        });
+      }
+      if (elementAt?.endTag) matchedEndTags.add(elementAt.endTag.startOffset);
+      if (RAW_TEXT_TAGS.has(node.tagName) && elementAt?.startTag) {
+        rawTextBodies.push({
+          start: elementAt.startTag.endOffset,
+          end: elementAt.endTag?.startOffset ?? elementAt.endOffset,
+        });
+      }
     }
-    if (character === "<" || character === "/" || /\s/.test(character)) {
-      word = "";
-      continue;
+    for (const child of childrenOf(node)) {
+      if (isElement(node)) parents.set(child, node);
+      stack.push(child);
     }
-    word += character;
   }
   return {
-    end: value.length,
-    terminated: false,
-    quoteOpen: quote !== null,
-    unterminatedAttribute: quotedAttribute,
+    source,
+    document,
+    errors,
+    rawTextBodies: rawTextBodies.sort(byStart),
+    comments: comments.sort(byStart),
+    attributeRanges: attributeRanges.sort(byStart),
+    matchedEndTags,
+    elements,
+    textNodes,
+    parents,
   };
 }
 /**
- * One parse for both facts. Deriving `isClose` separately let `< /div>` be read
- * as a close tag by one check and an open tag by the other.
+ * Binary search over sorted, non-overlapping ranges. This is called once per
+ * markup token, so a linear scan here is what turns a document carrying many
+ * <style>/<script> blocks quadratic.
  */
-function tagAt(
-  value: string,
-  index: number,
-): { tag: string; isClose: boolean } | null {
-  const match = /^<(\s*\/)?\s*([a-zA-Z][a-zA-Z0-9:-]*)/.exec(
-    value.slice(index, index + 64),
-  );
-  return match
-    ? { tag: match[2]!.toLowerCase(), isClose: match[1] !== undefined }
-    : null;
+function fallsInside(index: number, ranges: SourceRange[]): boolean {
+  let low = 0;
+  let high = ranges.length - 1;
+  while (low <= high) {
+    const mid = (low + high) >> 1;
+    const range = ranges[mid]!;
+    if (index < range.start) high = mid - 1;
+    else if (index >= range.end) low = mid + 1;
+    else return true;
+  }
+  return false;
+}
+function byStart(left: SourceRange, right: SourceRange): number {
+  return left.start - right.start;
+}
+function findElements(
+  parsed: ParsedDocument,
+  tagName: string,
+): Parse5Element[] {
+  return parsed.elements.filter((element) => element.tagName === tagName);
+}
+function attributeOf(element: Parse5Element, name: string): string | undefined {
+  return element.attrs.find((attribute) => attribute.name === name)?.value;
 }
 /**
- * Runs on fragments as well as documents — an unterminated quote is as
- * destructive in a `<template>` snippet as in a full page.
+ * `eof-in-tag` covers a tag cut off mid-name and one whose quote was never
+ * closed, and the fix differs: telling an author to close a quote that is
+ * already closed sends them to the wrong character. Only runs on input the
+ * parser has already rejected.
  */
-function collectStructuralIssues(
-  value: string,
-): DesignHtmlIntegrityIssueDetail[] {
-  const issues: DesignHtmlIntegrityIssueDetail[] = [];
-  const stack: Array<{ tag: string; start: number }> = [];
-  const locate = createLocator(value);
+function findUnterminatedTag(parsed: ParsedDocument): {
+  start: number;
+  tag?: string;
+  quote: boolean;
+  attribute?: string;
+} | null {
+  const value = parsed.source;
   let cursor = 0;
   while (cursor < value.length) {
     const open = value.indexOf("<", cursor);
-    if (open === -1) break;
-    if (value.startsWith("<!--", open)) {
-      const commentEnd = value.indexOf("-->", open + 4);
-      if (commentEnd === -1) {
-        issues.push({ issue: "content-truncated", ...locate(open) });
-        return issues;
-      }
-      cursor = commentEnd + 3;
+    if (open === -1) return null;
+    if (
+      fallsInside(open, parsed.rawTextBodies) ||
+      fallsInside(open, parsed.comments)
+    ) {
+      cursor = open + 1;
       continue;
     }
-    if (value.startsWith("<!", open)) {
-      cursor = Math.max(scanTag(value, open).end, open + 1);
+    if (value.startsWith("<!--", open)) {
+      const end = value.indexOf("-->", open + 4);
+      cursor = end === -1 ? value.length : end + 3;
       continue;
     }
-    const parsed = tagAt(value, open);
-    if (!parsed) {
-      // A bare `<` in text content. Not markup, not a defect.
+    if (!/^<\s*\/?\s*[a-zA-Z!]/.test(value.slice(open, open + 8))) {
       cursor = open + 1;
       continue;
     }
-    const { tag, isClose } = parsed;
-    const scan = scanTag(value, open);
-    if (!scan.terminated) {
-      // Anything after an unclosed tag would be invented structure. Stop here.
-      const located = locate(open);
-      issues.push(
-        scan.quoteOpen
-          ? {
-              issue: "attribute-unterminated",
-              ...located,
-              tag,
-              attribute: scan.unterminatedAttribute,
-            }
-          : { issue: "content-truncated", ...located, tag },
-      );
-      return issues;
-    }
-    if (isClose) {
-      let matched = -1;
-      for (let index = stack.length - 1; index >= 0; index -= 1) {
-        if (stack[index]!.tag === tag) {
-          matched = index;
-          break;
+    let quote: '"' | "'" | null = null;
+    let word = "";
+    let pending: string | undefined;
+    let quoted: string | undefined;
+    let terminated = false;
+    let scan = open;
+    for (; scan < value.length; scan += 1) {
+      const character = value[scan]!;
+      if (quote) {
+        if (character === quote) {
+          quote = null;
+          quoted = undefined;
         }
+        continue;
       }
-      if (matched === -1) {
-        if (!OPTIONAL_CLOSE_TAGS.has(tag) && !VOID_TAGS.has(tag)) {
-          issues.push({ issue: "close-tag-orphaned", ...locate(open), tag });
-        }
-      } else {
-        // Located lazily: computing this for every balanced close tag is what
-        // made a valid document quadratic.
-        let closeLine: number | null = null;
-        for (let index = stack.length - 1; index > matched; index -= 1) {
-          const abandoned = stack[index]!;
-          if (OPTIONAL_CLOSE_TAGS.has(abandoned.tag)) continue;
-          closeLine ??= locate(open).line;
-          issues.push({
-            issue: "element-unclosed",
-            ...locate(abandoned.start),
-            tag: abandoned.tag,
-            closedBy: { tag, line: closeLine },
-          });
-        }
-        stack.length = matched;
+      if (character === '"' || character === "'") {
+        quote = character;
+        quoted = pending;
+        continue;
       }
-      cursor = scan.end;
-      continue;
+      if (character === ">") {
+        terminated = true;
+        break;
+      }
+      if (character === "=") {
+        if (word) pending = word;
+        word = "";
+        continue;
+      }
+      if (character === "<" || character === "/" || /\s/.test(character)) {
+        word = "";
+        continue;
+      }
+      word += character;
+    }
+    if (!terminated) {
+      return {
+        start: open,
+        tag: tagNameAtOffset(value, open),
+        quote: quote !== null,
+        attribute: quote !== null ? quoted : undefined,
+      };
     }
+    cursor = scan + 1;
+  }
+  return null;
+}
-    const selfClosing = /\/\s*>$/.test(value.slice(open, scan.end));
-    if (RAW_TEXT_TAGS.has(tag) && !selfClosing) {
-      // Resume AT the closing tag so the close branch pops this element,
-      // rather than duplicating that logic here. An unterminated body is left
-      // to the raw-text-balance check, which names that cause correctly.
-      const closer = rawTextCloser(tag);
-      closer.lastIndex = scan.end;
-      const found = closer.exec(value);
-      if (!found) {
-        // Report here rather than deferring to the document-only raw-text
-        // balance check: fragments never reach that check, so an unclosed
-        // <script> would pass the well-formedness gate entirely.
-        issues.push({
-          issue: "raw-text-balance",
-          ...locate(open),
-          tag,
-        });
-        return issues;
-      }
-      stack.push({ tag, start: open });
-      cursor = found.index;
-      continue;
+function stripBoundaryNoise(value: string): string {
+  return value
+    .replace(/^/, "")
+    .replace(/<!--(?:[\s\S]*?)-->/g, "")
+    .trim();
+}
+// ---------------------------------------------------------------------------
+// Structural checks
+// ---------------------------------------------------------------------------
+function collectParseErrorIssues(
+  parsed: ParsedDocument,
+  locate: Locator,
+): DesignHtmlIntegrityIssueDetail[] {
+  const fatal = FATAL_PARSE_ERRORS.flatMap((code) =>
+    parsed.errors.filter((error) => error.code === code),
+  )[0];
+  if (!fatal) return [];
+  if (fatal.code === "eof-in-element-that-can-contain-only-text") {
+    const unterminated = parsed.elements.find(
+      (element) =>
+        RAW_TEXT_TAGS.has(element.tagName) &&
+        element.sourceCodeLocation &&
+        !element.sourceCodeLocation.endTag,
+    );
+    const anchor = unterminated?.sourceCodeLocation?.startOffset ?? 0;
+    return [
+      {
+        issue: "raw-text-balance",
+        ...locate(anchor),
+        ...(unterminated ? { tag: unterminated.tagName } : {}),
+      },
+    ];
+  }
+  return [{ issue: "content-truncated", ...locate(fatal.startOffset) }];
+}
+function tagNameAtOffset(value: string, offset: number): string | undefined {
+  return /^<\s*\/?\s*([a-zA-Z][a-zA-Z0-9:-]*)/
+    .exec(value.slice(offset, offset + 64))?.[1]
+    ?.toLowerCase();
+}
+const END_TAG_PATTERN = /<\s*\/\s*([a-zA-Z][a-zA-Z0-9:-]*)\s*>/g;
+/**
+ * The one structural fact the tree cannot supply: the parser drops an end tag
+ * that closes nothing without reporting it. Every exclusion range still comes
+ * from the tree rather than a second hand-rolled tokenizer.
+ */
+function collectOrphanEndTags(
+  parsed: ParsedDocument,
+  locate: Locator,
+): DesignHtmlIntegrityIssueDetail[] {
+  const issues: DesignHtmlIntegrityIssueDetail[] = [];
+  END_TAG_PATTERN.lastIndex = 0;
+  let match = END_TAG_PATTERN.exec(parsed.source);
+  while (match) {
+    const offset = match.index;
+    const tag = match[1]!.toLowerCase();
+    if (
+      !parsed.matchedEndTags.has(offset) &&
+      !OPTIONAL_CLOSE_TAGS.has(tag) &&
+      !VOID_TAGS.has(tag) &&
+      !fallsInside(offset, parsed.rawTextBodies) &&
+      !fallsInside(offset, parsed.comments) &&
+      !fallsInside(offset, parsed.attributeRanges)
+    ) {
+      issues.push({ issue: "close-tag-orphaned", ...locate(offset), tag });
     }
+    match = END_TAG_PATTERN.exec(parsed.source);
+  }
+  return issues;
+}
-    if (VOID_TAGS.has(tag) || selfClosing) {
-      cursor = scan.end;
+/**
+ * An element the parser closed for you carries no end-tag location. The nearest
+ * ancestor that does have one names the tag that arrived where this element's
+ * close belonged.
+ */
+function collectUnclosedElements(
+  parsed: ParsedDocument,
+  locate: Locator,
+): DesignHtmlIntegrityIssueDetail[] {
+  const issues: DesignHtmlIntegrityIssueDetail[] = [];
+  for (const element of parsed.elements) {
+    const location = element.sourceCodeLocation;
+    // A missing location means the parser invented the element; the document
+    // shape checks own that case, not this one.
+    if (!location || location.endTag) continue;
+    const tag = element.tagName;
+    if (VOID_TAGS.has(tag) || OPTIONAL_CLOSE_TAGS.has(tag)) continue;
+    const startTag = location.startTag;
+    if (
+      startTag &&
+      /\/\s*>$/.test(
+        parsed.source.slice(startTag.startOffset, startTag.endOffset),
+      )
+    ) {
       continue;
     }
-    // An implied close discards the target AND everything opened inside it —
-    // the browser closes those too, so popping only the stack top reports a
-    // still-open inline descendant (`<li><span>one<li>`) as unclosed.
-    const impliedClose = IMPLICIT_SIBLING_CLOSE.get(tag);
-    if (impliedClose) {
-      for (let index = stack.length - 1; index >= 0; index -= 1) {
-        if (!impliedClose.has(stack[index]!.tag)) continue;
-        stack.length = index;
+    let ancestor = parsed.parents.get(element);
+    let closedBy: { tag: string; line: number } | undefined;
+    let carriedByImpliedClose = false;
+    while (ancestor) {
+      const ancestorEnd = ancestor.sourceCodeLocation?.endTag;
+      if (ancestorEnd) {
+        closedBy = {
+          tag: ancestor.tagName,
+          line: locate(ancestorEnd.startOffset).line,
+        };
+        break;
+      }
+      // The ancestor's own close was legally omitted, which closes this element
+      // with it — `<li><span>one<li>` leaves no defect for the span. The
+      // ancestor must be authored: the parser invents <body> for every fragment,
+      // and accepting that as the carrier excuses every unclosed element there.
+      if (
+        ancestor.sourceCodeLocation &&
+        OPTIONAL_CLOSE_TAGS.has(ancestor.tagName)
+      ) {
+        carriedByImpliedClose = true;
         break;
       }
+      ancestor = parsed.parents.get(ancestor);
+    }
+    if (carriedByImpliedClose) continue;
+    issues.push({
+      issue: "element-unclosed",
+      ...locate(location.startOffset),
+      tag,
+      ...(closedBy ? { closedBy } : {}),
+    });
+  }
+  return issues;
+}
+/**
+ * Alpine compiles these attribute values as JavaScript. Nothing else may join
+ * this set on a hunch: `x-for` holds `item in items`, `x-transition:enter` holds
+ * a class list, and `x-ref`/`x-teleport` hold a name and a selector — reading
+ * any of those as an expression reports working markup as broken.
+ */
+const ALPINE_EXPRESSION_DIRECTIVES = new Set([
+  "x-bind",
+  "x-data",
+  "x-effect",
+  "x-html",
+  "x-id",
+  "x-if",
+  "x-init",
+  "x-modelable",
+  "x-model",
+  "x-show",
+  "x-text",
+]);
+/**
+ * Runs for every attribute in the document, so `class`/`style`/`href` must fall
+ * out before anything allocates.
+ */
+function isAlpineExpressionAttribute(name: string): boolean {
+  const first = name[0];
+  if (first === ":" || first === "@") return name.length > 1;
+  if (name.length < 3 || (first !== "x" && first !== "X") || name[1] !== "-") {
+    return false;
+  }
+  const lower = name.toLowerCase();
+  if (lower.startsWith("x-on:") || lower.startsWith("x-bind:")) return true;
+  let end = 2;
+  while (end < lower.length && lower[end] !== "." && lower[end] !== ":") {
+    end += 1;
+  }
+  return ALPINE_EXPRESSION_DIRECTIVES.has(lower.slice(0, end));
+}
+/** The shapes Alpine wraps in an async IIFE instead of assigning. */
+const ALPINE_STATEMENT_SHAPED = /^\s*(?:if\s*\(|let\s|const\s|var\s)/;
+const ASSIGNED_PREFIX = "__an_probe = ";
+interface ExpressionDefect {
+  /** Offset within the expression where the parser gave up. */
+  offset: number;
+  reason: string;
+}
+/**
+ * Parses the source Alpine generates, not the raw value: the assignment keeps
+ * `{ open: false }` an object literal rather than a block, and rejects trailing
+ * garbage that `parseExpressionAt` stops short of. Not `new Function` — this runs
+ * on the browser write path, where a CSP may forbid it.
+ */
+function findExpressionDefect(expression: string): ExpressionDefect | null {
+  if (!expression.trim()) return null;
+  const wrapped = ALPINE_STATEMENT_SHAPED.test(expression);
+  const source = wrapped
+    ? `(async()=>{ ${expression} })()`
+    : `${ASSIGNED_PREFIX}${expression}`;
+  try {
+    parseJavaScript(source, {
+      ecmaVersion: "latest",
+      allowAwaitOutsideFunction: true,
+      allowReturnOutsideFunction: true,
+    });
+    return null;
+  } catch (error) {
+    const failure = error as { message?: unknown; pos?: unknown };
+    const prefix = wrapped ? "(async()=>{ ".length : ASSIGNED_PREFIX.length;
+    return {
+      offset:
+        typeof failure.pos === "number"
+          ? Math.min(Math.max(failure.pos - prefix, 0), expression.length)
+          : 0,
+      reason:
+        typeof failure.message === "string"
+          ? failure.message.replace(/\s*\(\d+:\d+\)\s*$/, "")
+          : "the expression is not valid JavaScript",
+    };
+  }
+}
+/**
+ * The attribute location spans `name="value"`, and acorn's offset is relative to
+ * the value, so the name and opening quote have to be skipped or every reported
+ * column lands early.
+ */
+function attributeValueStart(
+  parsed: ParsedDocument,
+  location: SourceRange,
+): number {
+  const source = parsed.source.slice(location.start, location.end);
+  const equals = source.indexOf("=");
+  if (equals === -1) return location.start;
+  let cursor = equals + 1;
+  while (cursor < source.length && /\s/.test(source[cursor]!)) cursor += 1;
+  const quote = source[cursor];
+  return location.start + cursor + (quote === '"' || quote === "'" ? 1 : 0);
+}
+function collectExpressionIssues(
+  parsed: ParsedDocument,
+  locate: Locator,
+): DesignHtmlIntegrityIssueDetail[] {
+  const issues: DesignHtmlIntegrityIssueDetail[] = [];
+  for (const element of parsed.elements) {
+    for (const attribute of element.attrs) {
+      if (!isAlpineExpressionAttribute(attribute.name)) continue;
+      // The tree hands back the decoded value, which is what Alpine compiles.
+      const defect = findExpressionDefect(attribute.value);
+      if (!defect) continue;
+      const location = element.sourceCodeLocation?.attrs?.[attribute.name];
+      const valueStart = location
+        ? attributeValueStart(parsed, {
+            start: location.startOffset,
+            end: location.endOffset,
+          })
+        : (element.sourceCodeLocation?.startOffset ?? 0);
+      issues.push({
+        issue: "expression-invalid",
+        ...locate(valueStart + defect.offset),
+        tag: element.tagName,
+        attribute: attribute.name,
+        reason: defect.reason,
+      });
     }
-    stack.push({ tag, start: open });
-    cursor = scan.end;
   }
+  return issues;
+}
+/**
+ * The JavaScript MIME types a browser will execute, per the HTML spec. Anything
+ * else — `importmap`, `application/json`, an `x-template`, a bespoke
+ * `application/vnd.*` block — is inert data the browser never parses, so parsing
+ * it here reports working markup as broken.
+ */
+const EXECUTABLE_SCRIPT_TYPES = new Set([
+  "application/ecmascript",
+  "application/javascript",
+  "application/x-ecmascript",
+  "application/x-javascript",
+  "text/ecmascript",
+  "text/javascript",
+  "text/javascript1.0",
+  "text/javascript1.1",
+  "text/javascript1.2",
+  "text/javascript1.3",
+  "text/javascript1.4",
+  "text/javascript1.5",
+  "text/jscript",
+  "text/livescript",
+  "text/x-ecmascript",
+  "text/x-javascript",
+]);
+/** `null` when the browser treats the element as data rather than code. */
+function scriptGrammar(type: string): "script" | "module" | null {
+  const normalized = type.trim().toLowerCase();
+  if (normalized === "") return "script";
+  if (normalized === "module") return "module";
+  const base = normalized.split(";")[0]!.trim();
+  return EXECUTABLE_SCRIPT_TYPES.has(base) ? "script" : null;
+}
+/**
+ * Parsed with the grammar the browser will actually use. Retrying a classic
+ * script as a module accepts `import` and top-level `await` in an element the
+ * browser rejects outright.
+ */
+function findScriptDefect(
+  source: string,
+  sourceType: "script" | "module",
+): ExpressionDefect | null {
+  try {
+    parseJavaScript(source, {
+      ecmaVersion: "latest",
+      sourceType,
+      // A <script> body is a Program, not a function body: a browser rejects a
+      // top-level `return` with "Illegal return statement" and never runs the
+      // element. Alpine expressions are the opposite case — Alpine compiles them
+      // inside a function — which is why the expression parser allows it.
+      allowReturnOutsideFunction: false,
+      allowAwaitOutsideFunction: sourceType === "module",
+      allowHashBang: true,
+    });
+    return null;
+  } catch (error) {
+    const failure = error as { message?: unknown; pos?: unknown };
+    return {
+      offset: typeof failure.pos === "number" ? failure.pos : 0,
+      reason:
+        typeof failure.message === "string"
+          ? failure.message.replace(/\s*\(\d+:\d+\)\s*$/, "")
+          : "the script is not valid JavaScript",
+    };
+  }
+}
-  // Stack order is document order, so stopping at the cap keeps the earliest
-  // (outermost) unclosed elements without locating every one of them.
-  for (const abandoned of stack) {
-    if (issues.length >= MAX_REPORTED_ISSUES) break;
-    if (OPTIONAL_CLOSE_TAGS.has(abandoned.tag)) continue;
+/**
+ * A truncated string in an inline <script> is the same defect as one in an
+ * Alpine attribute and just as invisible: the document parses, the element
+ * renders, and the script silently never runs.
+ */
+function collectScriptBodyIssues(
+  parsed: ParsedDocument,
+  locate: Locator,
+): DesignHtmlIntegrityIssueDetail[] {
+  const issues: DesignHtmlIntegrityIssueDetail[] = [];
+  for (const element of parsed.elements) {
+    if (element.tagName !== "script") continue;
+    if (element.attrs.some((attribute) => attribute.name === "src")) continue;
+    const grammar = scriptGrammar(attributeOf(element, "type") ?? "");
+    if (!grammar) continue;
+    const body = element.childNodes.find((node) => node.nodeName === "#text");
+    if (!body) continue;
+    const text = (body as DefaultTreeAdapterTypes.TextNode).value;
+    if (!text.trim()) continue;
+    const defect = findScriptDefect(text, grammar);
+    if (!defect) continue;
+    const start =
+      body.sourceCodeLocation?.startOffset ??
+      locationOf(element)?.startOffset ??
+      0;
     issues.push({
-      issue: "element-unclosed",
-      ...locate(abandoned.start),
-      tag: abandoned.tag,
+      issue: "script-invalid",
+      ...locate(start + defect.offset),
+      tag: "script",
+      reason: defect.reason,
     });
   }
+  return issues;
+}
-  return issues
+/**
+ * Runs on fragments as well as documents — an unterminated quote is as
+ * destructive in a `<template>` snippet as in a full page.
+ */
+function collectStructuralIssues(
+  value: string,
+  parsed = parseDocument(value),
+): DesignHtmlIntegrityIssueDetail[] {
+  const locate = createLocator(value);
+  // Reported alone: everything after an unterminated tag is invented structure.
+  // Cannot be driven off the parser's errors — a runaway attribute quote
+  // swallows markup until a later quote resyncs the tokenizer, which then
+  // finishes the document without complaining.
+  const unterminated = findUnterminatedTag(parsed);
+  if (unterminated) {
+    return [
+      {
+        issue: unterminated.quote
+          ? "attribute-unterminated"
+          : "content-truncated",
+        ...locate(unterminated.start),
+        ...(unterminated.tag ? { tag: unterminated.tag } : {}),
+        ...(unterminated.attribute
+          ? { attribute: unterminated.attribute }
+          : {}),
+      },
+    ];
+  }
+  const truncation = collectParseErrorIssues(parsed, locate);
+  if (truncation.length > 0) return truncation;
+  return [
+    ...collectUnclosedElements(parsed, locate),
+    ...collectOrphanEndTags(parsed, locate),
+    ...collectExpressionIssues(parsed, locate),
+    ...collectScriptBodyIssues(parsed, locate),
+  ]
     .sort((left, right) =>
       left.line === right.line
         ? left.column - right.column
@@ -741,162 +962,187 @@ function collectStructuralIssues(
     .slice(0, MAX_REPORTED_ISSUES);
 }
+// ---------------------------------------------------------------------------
+// Document shape
+// ---------------------------------------------------------------------------
+const ROOT_TAG_PATTERN = /<\s*(\/?)\s*(html|head|body)\b/gi;
+/**
+ * The parser merges a second `<html>` into the first and reports nothing, so two
+ * full documents concatenated by a bad write are invisible in the tree.
+ */
+function countRootTags(
+  parsed: ParsedDocument,
+): Record<"html" | "head" | "body", { open: number; close: number }> {
+  const counts = {
+    html: { open: 0, close: 0 },
+    head: { open: 0, close: 0 },
+    body: { open: 0, close: 0 },
+  };
+  ROOT_TAG_PATTERN.lastIndex = 0;
+  let match = ROOT_TAG_PATTERN.exec(parsed.source);
+  while (match) {
+    const offset = match.index;
+    if (
+      !fallsInside(offset, parsed.rawTextBodies) &&
+      !fallsInside(offset, parsed.comments) &&
+      !fallsInside(offset, parsed.attributeRanges)
+    ) {
+      const tag = match[2]!.toLowerCase() as "html" | "head" | "body";
+      if (match[1] === "/") counts[tag].close += 1;
+      else counts[tag].open += 1;
+    }
+    match = ROOT_TAG_PATTERN.exec(parsed.source);
+  }
+  return counts;
+}
+/** An authored root, as opposed to one the parser supplied for a fragment. */
+function authoredRoot(
+  parsed: ParsedDocument,
+  tagName: "html" | "head" | "body",
+): Parse5Element | undefined {
+  return findElements(parsed, tagName).find(
+    (element) =>
+      element.sourceCodeLocation !== null &&
+      element.sourceCodeLocation !== undefined,
+  );
+}
+function hasDoctype(parsed: ParsedDocument): boolean {
+  return childrenOf(parsed.document).some(
+    (node) => node.nodeName === "#documentType" && node.sourceCodeLocation,
+  );
+}
+function isDocumentHtml(value: string, parsed = parseDocument(value)): boolean {
+  return hasDoctype(parsed) || authoredRoot(parsed, "html") !== undefined;
+}
+function collectDocumentShapeIssue(
+  parsed: ParsedDocument,
+): DesignHtmlIntegrityIssue | null {
+  const counts = countRootTags(parsed);
+  if (counts.html.open !== 1 || counts.html.close !== 1) return "document-root";
+  if (counts.body.open !== 1 || counts.body.close !== 1) return "document-body";
+  if (counts.head.open !== counts.head.close || counts.head.open > 1) {
+    return "document-head";
+  }
+  const htmlAt = locationOf(authoredRoot(parsed, "html"));
+  const htmlEnd = htmlAt?.endTag;
+  if (!htmlAt || !htmlEnd) return "document-root";
+  const bodyAt = locationOf(authoredRoot(parsed, "body"));
+  const bodyEnd = bodyAt?.endTag;
+  if (!bodyAt || !bodyEnd) return "document-body";
+  if (
+    bodyAt.startOffset <= htmlAt.startOffset ||
+    bodyEnd.startOffset >= htmlEnd.startOffset
+  ) {
+    return "document-boundary";
+  }
+  const prefix = stripBoundaryNoise(
+    parsed.source.slice(0, htmlAt.startOffset),
+  ).replace(/<!doctype\s+html\b[^>]*>/i, "");
+  const suffix = stripBoundaryNoise(parsed.source.slice(htmlEnd.endOffset));
+  if (prefix.trim() || suffix.trim()) return "document-boundary";
+  return null;
+}
+/**
+ * A marker that lost its element is not missing — it is sitting in the document
+ * as text, which is exactly how a partial edit leaves it.
+ */
+function collectManagedMarkerIssue(
+  parsed: ParsedDocument,
+): DesignHtmlIntegrityIssue | null {
+  for (const { marker, tag } of MANAGED_RAW_TEXT_MARKERS) {
+    const attached = parsed.elements.filter(
+      (element) =>
+        element.tagName === tag &&
+        element.attrs.some((attribute) => attribute.name === marker),
+    ).length;
+    const loose = parsed.textNodes.some(
+      (node) =>
+        node.value.includes(marker) &&
+        !RAW_TEXT_TAGS.has(parsed.parents.get(node)?.tagName ?? ""),
+    );
+    if (loose) return "managed-marker-orphaned";
+    if (attached > 1) return "managed-marker-duplicated";
+  }
+  return null;
+}
 /**
  * Reported, never enforced: legitimate fragments and token-only screens carry no
  * runtime of their own, so blocking here would reject valid work.
  */
 function collectAdvisoryIssues(
-  value: string,
-  rawTextBodyRanges: RawTextScan["bodyRanges"],
+  parsed: ParsedDocument,
+  locate: Locator,
 ): DesignHtmlIntegrityIssueDetail[] {
-  if (!isDocumentHtml(value, rawTextBodyRanges)) return [];
   // Only documents that actually depend on utility classes can be broken by a
   // missing runtime. A screen styled entirely through its own CSS needs no
   // Tailwind, and flagging it would train authors to ignore this warning.
-  if (!USES_TAILWIND_UTILITIES.test(value)) return [];
-  // Comments are not markup: a commented-out runtime tag is not a runtime.
-  const value_ = value.replace(/<!--[\s\S]*?-->/g, "");
-  const hasTailwindRuntime =
-    /<script\b[^>]*\bsrc\s*=\s*(?:"[^"]*tailwind[^"]*"|'[^']*tailwind[^']*')/i.test(
-      value_,
-    ) ||
-    /<style\b[^>]*\btype\s*=\s*(?:"text\/tailwindcss"|'text\/tailwindcss')/i.test(
-      value_,
-    ) ||
-    /<link\b[^>]*\bhref\s*=\s*(?:"[^"]*tailwind[^"]*"|'[^']*tailwind[^']*')/i.test(
-      value_,
-    );
-  if (hasTailwindRuntime) return [];
-  const headIndex = value.search(/<head\b/i);
+  if (!USES_TAILWIND_UTILITIES.test(parsed.source)) return [];
+  const hasRuntime = parsed.elements.some((element) => {
+    if (element.tagName === "script") {
+      return /tailwind/i.test(attributeOf(element, "src") ?? "");
+    }
+    if (element.tagName === "link") {
+      return /tailwind/i.test(attributeOf(element, "href") ?? "");
+    }
+    if (element.tagName === "style") {
+      return (
+        (attributeOf(element, "type") ?? "").toLowerCase() ===
+        "text/tailwindcss"
+      );
+    }
+    return false;
+  });
+  if (hasRuntime) return [];
+  const head = authoredRoot(parsed, "head");
   return [
     {
       issue: "runtime-missing",
-      ...createLocator(value)(headIndex === -1 ? 0 : headIndex),
+      ...locate(head?.sourceCodeLocation?.startOffset ?? 0),
     },
   ];
 }
-function markerCounts(
-  value: string,
-  marker: string,
-  tag: "style" | "script",
-  ranges: RawTextScan["bodyRanges"],
-): { raw: number; attached: number } {
-  const escapedMarker = marker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  return {
-    raw: countMatchesOutsideRanges(
-      value,
-      new RegExp(`\\b${escapedMarker}\\b`, "gi"),
-      ranges,
-    ),
-    attached: countMatchesOutsideRanges(
-      value,
-      new RegExp(`<${tag}\\b[^>]*\\b${escapedMarker}\\b[^>]*>`, "gi"),
-      ranges,
-      true,
-    ),
-  };
-}
 /**
- * Validate one complete Design HTML document without parsing/serializing it.
- * DOMParser is intentionally not used: it repairs exactly the missing
- * `<style>`/root boundaries this guard must detect. Alpine fragments and
- * `<template>` snippets are not documents and are handled by the transition
- * function below instead of being rejected here.
+ * Validate one complete Design HTML document. The HTML5 parser is the tokenizer,
+ * but never the verdict: it repairs the missing roots and unbalanced elements
+ * this guard exists to catch, so the checks read its tree and its parse errors
+ * rather than trusting that it produced a document.
  */
 export function inspectDesignHtmlDocumentIntegrity(
   value: string,
 ): DesignHtmlIntegrityResult {
-  const rawText = scanRawTextTags(value);
+  const parsed = parseDocument(value);
+  const locate = createLocator(value);
-  // Structure first, counting second. An unterminated quote swallows the root
-  // tags, so the counting pass would report `document-root` — sending the fix to
-  // a `<html>` tag that is present and correct instead of to the quote.
-  const structural = collectStructuralIssues(value);
+  // Structure first. An unterminated quote swallows the root tags, so a
+  // shape-first order would report `document-root` — sending the fix to an
+  // `<html>` tag that is present and correct instead of to the quote.
+  const structural = collectStructuralIssues(value, parsed);
   if (structural.length > 0) {
-    return {
-      valid: false,
-      issue: structural[0]!.issue,
-      detail: structural,
-    };
+    return { valid: false, issue: structural[0]!.issue, detail: structural };
   }
-  if (!isDocumentHtml(value, rawText.bodyRanges)) return { valid: true };
+  if (!isDocumentHtml(value, parsed)) return { valid: true };
-  // Before the root counts: an unbalanced raw-text element swallows the tags
-  // those counts look for, so checking order decides whether the report names
-  // the cause or its effect.
-  if (rawText.severity > 0) {
-    return { valid: false, issue: "raw-text-balance" };
-  }
+  const shape = collectDocumentShapeIssue(parsed);
+  if (shape) return { valid: false, issue: shape };
-  const html = tagCount(value, "html", rawText.bodyRanges);
-  if (html.open !== 1 || html.close !== 1) {
-    return { valid: false, issue: "document-root" };
-  }
-  const body = tagCount(value, "body", rawText.bodyRanges);
-  if (body.open !== 1 || body.close !== 1) {
-    return { valid: false, issue: "document-body" };
-  }
-  const head = tagCount(value, "head", rawText.bodyRanges);
-  if (head.open !== head.close || head.open > 1) {
-    return { valid: false, issue: "document-head" };
-  }
-  const htmlOpen = firstMatchOutsideRanges(
-    value,
-    /<html\b[^>]*>/gi,
-    rawText.bodyRanges,
-  );
-  const htmlClose = firstMatchOutsideRanges(
-    value,
-    /<\s*\/\s*html\s*>/gi,
-    rawText.bodyRanges,
-  );
-  const bodyOpen = firstMatchOutsideRanges(
-    value,
-    /<body\b[^>]*>/gi,
-    rawText.bodyRanges,
-  );
-  const bodyClose = firstMatchOutsideRanges(
-    value,
-    /<\s*\/\s*body\s*>/gi,
-    rawText.bodyRanges,
-  );
-  if (!htmlOpen || !htmlClose || !bodyOpen || !bodyClose) {
-    return { valid: false, issue: "document-root" };
-  }
-  if (
-    htmlOpen.index >= bodyOpen.index ||
-    bodyOpen.index >= bodyClose.index ||
-    bodyClose.index >= htmlClose.index
-  ) {
-    return { valid: false, issue: "document-boundary" };
-  }
-  const prefix = stripBoundaryNoise(value.slice(0, htmlOpen.index)).replace(
-    /<!doctype\s+html\b[^>]*>/i,
-    "",
-  );
-  const suffix = stripBoundaryNoise(
-    value.slice(htmlClose.index + htmlClose.text.length),
-  );
-  if (prefix.trim() || suffix.trim()) {
-    return { valid: false, issue: "document-boundary" };
-  }
-  for (const { marker, tag } of MANAGED_RAW_TEXT_MARKERS) {
-    const counts = markerCounts(value, marker, tag, rawText.bodyRanges);
-    if (counts.raw !== counts.attached) {
-      return { valid: false, issue: "managed-marker-orphaned" };
-    }
-    if (counts.attached > 1) {
-      return { valid: false, issue: "managed-marker-duplicated" };
-    }
-  }
+  const marker = collectManagedMarkerIssue(parsed);
+  if (marker) return { valid: false, issue: marker };
-  const advisory = collectAdvisoryIssues(value, rawText.bodyRanges);
+  const advisory = collectAdvisoryIssues(parsed, locate);
   return advisory.length > 0 ? { valid: true, advisory } : { valid: true };
 }