feat: validate compiles malformed HTML as an error, not a warning (#3099)

Once the validator fires, the emitted positional walk is guaranteed not
to match the browser-built DOM — crashed or silently misplaced bindings,
and desynced hydration under SSR — so warn-and-emit shipped certain
breakage with the diagnostic buried in server logs. Both compilers now
fail the build pointing at the offending JSX (code frame in Babel,
line:col in the native compiler); validate: false remains the opt-out.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: ryansolid

.changeset/validate-malformed-html-error.md

@@ -0,0 +1,6 @@
+---
+"@solidjs/babel-plugin-jsx": minor
+"@solidjs/compiler": minor
+---
+
+`validate` now fails the compile instead of warning when a template's markup would be restructured by the browser's HTML parser (#3099). Once the validator fires the emitted positional walk is guaranteed not to match the browser-built DOM (crashed or silently misplaced bindings; desynced hydration under SSR), so warn-and-emit shipped certain breakage with the diagnostic buried in server logs. Errors now point at the offending JSX (code frame in Babel, line:col in the native compiler). `validate: false` remains the opt-out.

packages/babel-plugin/src/dom/template.ts

@@ -129,7 +129,11 @@ function registerTemplate(path: NodePath, results: TransformResult) {
           templateWithClosingTags: results.templateWithClosingTags as string,
           isImportNode: results.isImportNode,
           isWrapped: results.isWrapped,
-          renderer: "dom"
+          renderer: "dom",
+          // templates dedupe on markup, so the FIRST site carries the blame
+          // for a validate failure (#3099) — good enough: every site with
+          // this markup has the same problem
+          path
         });
       }
     }

packages/babel-plugin/src/shared/postprocess.ts

@@ -32,13 +32,22 @@ export default (path: NodePath<t.Program>, state: PluginPass) => {
         if (typeof html === "string") {
           const result = isInvalidMarkup(html);
           if (result) {
+            // A compile ERROR, not a warning (#3099): once the validator has
+            // fired, the emitted template is guaranteed not to match its own
+            // positional walk — the browser rebuilds the DOM, and the walk
+            // binds against nodes that moved (crash or silent wrong-node
+            // bindings; under SSR the restructuring desyncs hydration too).
+            // Warn-and-emit put this diagnostic in server stdout while the
+            // browser failed with an unrelated-looking runtime crash. The
+            // error throws from the template's registration site, so
+            // bundlers surface it at the right file and line. `validate:
+            // false` remains the opt-out.
             const message =
-              "\nThe HTML provided is malformed and will yield unexpected output when evaluated by a browser.\n";
-            console.warn(message);
-            console.warn("User HTML:\n", result.html);
-            console.warn("Browser HTML:\n", result.browser);
-            console.warn("Original HTML:\n", html);
-            // throw path.buildCodeFrameError();
+              "The HTML provided is malformed and will yield unexpected output when evaluated by a browser.\n" +
+              `User HTML:\n ${result.html}\n` +
+              `Browser HTML:\n ${result.browser}\n` +
+              `Original HTML:\n ${html}`;
+            throw (template.path ?? path).buildCodeFrameError(message);
           }
         }
       }

packages/babel-plugin/src/types.ts

@@ -14,6 +14,8 @@ export interface TemplateRecord {
   isImportNode?: boolean;
   isWrapped?: boolean;
   renderer: RendererName;
+  /** First registration site, so `validate` failures point at the JSX (#3099). */
+  path?: NodePath;
 }
 
 export interface ProgramScopeData {

packages/compiler/__tests__/validate-parity.test.js

@@ -1,73 +1,99 @@
-// Parity checks for the `validate` option's malformed-HTML warnings.
+// Parity checks for the `validate` option's malformed-HTML compile errors.
 //
-// Babel warns through `console.warn`; Oxc's port warns from Rust directly to
-// process stderr, so both compiles run in child processes and the captured
-// stderr is compared — both whether a warning fires and its exact content.
+// Since #3099 `validate` is a hard compile error in both compilers (the
+// emitted walk is guaranteed broken once the browser re-parses the markup
+// differently). Both compiles run in child processes; the runners catch the
+// thrown error and print its message to stderr so the harness can compare
+// whether each compiler fired and that the DOM diff content matches.
 
 const { spawnSync } = require("child_process");
 const path = require("path");
 
 const compilerDir = path.resolve(__dirname, "..");
 
 const cases = {
-  pInDiv: { code: "const t = <p><div>bad</div></p>;", warns: true },
-  nestedA: { code: "const t = <a><a>x</a></a>;", warns: true },
-  tableNoTbody: { code: "const t = <table><tr><td>1</td></tr></table>;", warns: true },
-  formInForm: { code: "const t = <form><form>x</form></form>;", warns: true },
-  buttonInButton: { code: "const t = <button><button>x</button></button>;", warns: true },
-  dynamicHole: { code: "const t = <p>{x()}<div>bad</div></p>;", warns: true },
+  pInDiv: { code: "const t = <p><div>bad</div></p>;", throws: true },
+  nestedA: { code: "const t = <a><a>x</a></a>;", throws: true },
+  tableNoTbody: { code: "const t = <table><tr><td>1</td></tr></table>;", throws: true },
+  formInForm: { code: "const t = <form><form>x</form></form>;", throws: true },
+  buttonInButton: { code: "const t = <button><button>x</button></button>;", throws: true },
+  dynamicHole: { code: "const t = <p>{x()}<div>bad</div></p>;", throws: true },
   hydratableMarkers: {
     code: "const t = <p>{x()}<div>bad</div></p>;",
     options: { hydratable: true },
-    warns: true
+    throws: true
   },
   // Table partials are wrapped in the right context before validation.
-  tdPartial: { code: "const t = <td>cell</td>;", warns: false },
-  trPartial: { code: "const t = <tr><td>c</td></tr>;", warns: false },
-  colPartial: { code: "const t = <col />;", warns: false },
-  theadPartial: { code: "const t = <thead><tr><th>h</th></tr></thead>;", warns: false },
-  emptyTbody: { code: "const t = <tbody></tbody>;", warns: false },
+  tdPartial: { code: "const t = <td>cell</td>;", throws: false },
+  trPartial: { code: "const t = <tr><td>c</td></tr>;", throws: false },
+  colPartial: { code: "const t = <col />;", throws: false },
+  theadPartial: { code: "const t = <thead><tr><th>h</th></tr></thead>;", throws: false },
+  emptyTbody: { code: "const t = <tbody></tbody>;", throws: false },
   // Escaped text must not be re-interpreted as markup.
-  scriptEscape: { code: 'const t = <div>{"<script>a();</script>"}<b>ok</b></div>;', warns: false },
-  liOrphan: { code: "const t = <li>item</li>;", warns: false },
-  goodDiv: { code: "const t = <div><span>fine</span></div>;", warns: false },
-  disabled: { code: "const t = <p><div>bad</div></p>;", options: { validate: false }, warns: false }
+  scriptEscape: { code: 'const t = <div>{"<script>a();</script>"}<b>ok</b></div>;', throws: false },
+  liOrphan: { code: "const t = <li>item</li>;", throws: false },
+  goodDiv: { code: "const t = <div><span>fine</span></div>;", throws: false },
+  disabled: {
+    code: "const t = <p><div>bad</div></p>;",
+    options: { validate: false },
+    throws: false
+  }
 };
 
 const babelRunner = `
 const babel = require("@babel/core");
 const plugin = require("../babel-plugin");
-babel.transformSync(process.argv[1], {
-  filename: "a.jsx",
-  parserOpts: { plugins: ["jsx"] },
-  plugins: [[plugin, JSON.parse(process.argv[2])]]
-});
+try {
+  babel.transformSync(process.argv[1], {
+    filename: "a.jsx",
+    parserOpts: { plugins: ["jsx"] },
+    plugins: [[plugin, JSON.parse(process.argv[2])]]
+  });
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 42;
+}
 `;
 
 const oxcRunner = `
 const { transform } = require("./index.js");
-transform(process.argv[1], { filename: "a.jsx", ...JSON.parse(process.argv[2]) });
+try {
+  transform(process.argv[1], { filename: "a.jsx", ...JSON.parse(process.argv[2]) });
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 42;
+}
 `;
 
-function stderrOf(runner, code, options) {
+function runCompile(runner, code, options) {
   const result = spawnSync("node", ["-e", runner, code, JSON.stringify(options)], {
     cwd: compilerDir,
     encoding: "utf8"
   });
-  expect(result.status).toBe(0);
-  return result.stderr;
+  expect([0, 42]).toContain(result.status);
+  return { threw: result.status === 42, stderr: result.stderr };
+}
+
+// The compilers format locations differently (Babel appends a code frame;
+// Oxc embeds line:col), so parity is asserted on the DOM diff itself.
+function domDiff(stderr) {
+  const match = stderr.match(/User HTML:\n[^\n]*\n\s*Browser HTML:\n[^\n]*/);
+  expect(match).not.toBeNull();
+  return match[0].replace(/\n\s+/g, "\n ");
 }
 
-describe("validate warning parity", () => {
-  for (const [name, { code, options = {}, warns }] of Object.entries(cases)) {
+describe("validate error parity", () => {
+  for (const [name, { code, options = {}, throws }] of Object.entries(cases)) {
     test(name, () => {
       const fullOptions = { moduleName: "r-dom", ...options };
-      const babelErr = stderrOf(babelRunner, code, fullOptions);
-      const oxcErr = stderrOf(oxcRunner, code, fullOptions);
-      expect(babelErr.includes("malformed")).toBe(warns);
-      expect(oxcErr.includes("malformed")).toBe(warns);
-      if (warns) {
-        expect(oxcErr.trim()).toBe(babelErr.trim());
+      const babel = runCompile(babelRunner, code, fullOptions);
+      const oxc = runCompile(oxcRunner, code, fullOptions);
+      expect(babel.threw).toBe(throws);
+      expect(oxc.threw).toBe(throws);
+      expect(babel.stderr.includes("malformed")).toBe(throws);
+      expect(oxc.stderr.includes("malformed")).toBe(throws);
+      if (throws) {
+        expect(domDiff(oxc.stderr)).toBe(domDiff(babel.stderr));
       }
     });
   }

packages/compiler/src/dom/element.rs

@@ -412,7 +412,7 @@ impl<'a, 'source> AstDomTransform<'a, 'source> {
         let template_id = if skip_template {
             None
         } else {
-            Some(self.template_id_with_options(template, template_flag))
+            Some(self.template_id_with_options(template, template_flag, element.span))
         };
         let has_hydratable_event = self.has_hydratable_event;
         self.has_hydratable_event = saved_hydratable_event;

packages/compiler/src/dom/template.rs

@@ -59,6 +59,9 @@ pub(crate) struct DomTemplate {
     pub(crate) flag: Option<u8>,
     /// Generated `_tmpl$N` local (collision-checked against source names).
     pub(crate) name: String,
+    /// First registration site (templates dedupe on markup), so a `validate`
+    /// failure names the JSX element's source location (#3099).
+    pub(crate) span: Span,
 }
 
 /// A template under construction: the emitted markup (`html`, with omitted
@@ -93,6 +96,15 @@ pub(crate) struct InsertMarker<'a> {
     pub(crate) initial: Option<Expression<'a>>,
 }
 
+/// 1-based line and column for a byte offset, for diagnostics.
+fn line_and_column(source: &str, offset: u32) -> (usize, usize) {
+    let offset = (offset as usize).min(source.len());
+    let prefix = &source[..offset];
+    let line = prefix.bytes().filter(|byte| *byte == b'\n').count() + 1;
+    let column = prefix.rfind('\n').map_or(offset, |at| offset - at - 1) + 1;
+    (line, column)
+}
+
 impl DomTemplateState {
     pub(crate) fn new() -> Self {
         Self {
@@ -240,22 +252,31 @@ impl<'a> AstDomTransform<'a, '_> {
             // against the top-level module, not the renderer config.
             statements.push(self.import_wrapper_helper(built_in, &format!("_${built_in}")));
         }
-        // Babel's postprocess `validate` pass: warn (stderr, like
-        // `console.warn`) when a browser would re-parse a template's markup
-        // differently. Only DOM templates carry the closing-tags variant —
-        // Babel skips SSR templates for the same reason (theirs are AST
-        // nodes, not strings).
+        // Babel's postprocess `validate` pass: a compile ERROR (#3099) when a
+        // browser would re-parse a template's markup differently. Once the
+        // validator has fired, the emitted template is guaranteed not to
+        // match its own positional walk — the browser rebuilds the DOM and
+        // the walk binds against nodes that moved (crash or silent wrong-node
+        // bindings; under SSR the restructuring desyncs hydration too), so
+        // warn-and-emit shipped certain breakage with the explanation buried
+        // in server stderr. The message carries the registration site's
+        // line:col so bundler overlays land on the JSX. `validate: false`
+        // remains the opt-out. Only DOM templates carry the closing-tags
+        // variant — Babel skips SSR templates for the same reason (theirs
+        // are AST nodes, not strings).
         if self.validate {
             for template in &self.template_state.templates {
                 if let Some(result) =
                     crate::shared::validate::is_invalid_markup(&template.closed_html)
                 {
-                    eprintln!(
-                        "\nThe HTML provided is malformed and will yield unexpected output when evaluated by a browser.\n"
-                    );
-                    eprintln!("User HTML:\n {}", result.html);
-                    eprintln!("Browser HTML:\n {}", result.browser);
-                    eprintln!("Original HTML:\n {}", template.closed_html);
+                    let (line, column) = line_and_column(self.source, template.span.start);
+                    return Err(crate::error::CompileError::transform(format!(
+                        "The HTML provided is malformed and will yield unexpected output when evaluated by a browser. ({line}:{column})\n\
+                         User HTML:\n {}\n\
+                         Browser HTML:\n {}\n\
+                         Original HTML:\n {}",
+                        result.html, result.browser, template.closed_html
+                    )));
                 }
             }
         }
@@ -277,6 +298,7 @@ impl<'a> AstDomTransform<'a, '_> {
         &mut self,
         template: TemplateHtml,
         flag: Option<u8>,
+        span: Span,
     ) -> String {
         self.template_state.uses_template = true;
         // Templates dedupe on markup alone (the first registration's flag
@@ -298,6 +320,7 @@ impl<'a> AstDomTransform<'a, '_> {
                 closed_html: template.closed,
                 flag,
                 name: name.clone(),
+                span,
             });
             name
         }

packages/web/test/hydration/diagnostics.spec.tsx

@@ -392,18 +392,25 @@ describe("Phase 2: Walk validation", () => {
     }
   });
 
-  test("getFirstChild warns on browser-corrected structure (tbody insertion)", () => {
+  // The historical poster child for this warn — JSX `<table><tr>` whose
+  // missing tbody the browser inserts during parse — is a compile error
+  // since #3099, so the walk mismatch is staged with valid JSX against
+  // server DOM whose table section differs. The runtime diagnostic still
+  // matters for `validate: false` users and handwritten server markup.
+  test("getFirstChild warns on mismatched table structure", () => {
     const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
     const [text] = createSignal("Cell");
 
-    container.innerHTML = '<table _hk="0"><tbody><tr><td>Cell</td></tr></tbody></table>';
+    container.innerHTML = '<table _hk="0"><thead><tr><td>Cell</td></tr></thead></table>';
 
     dispose = hydrate(
       () => (
         <table>
-          <tr>
-            <td>{text()}</td>
-          </tr>
+          <tbody>
+            <tr>
+              <td>{text()}</td>
+            </tr>
+          </tbody>
         </table>
       ),
       container
@@ -413,7 +420,7 @@ describe("Phase 2: Walk validation", () => {
       c => typeof c[0] === "string" && c[0].includes("Hydration structure mismatch")
     );
     expect(structureWarns.length).toBeGreaterThanOrEqual(1);
-    expect(structureWarns[0][0]).toContain("expected <tr>");
+    expect(structureWarns[0][0]).toContain("expected <tbody>");
     warn.mockRestore();
   });
 
@@ -496,14 +503,16 @@ describe("Phase 2: Walk validation", () => {
     const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
     const [text] = createSignal("Cell");
 
-    container.innerHTML = '<table _hk="0"><tbody><tr><td>Cell</td></tr></tbody></table>';
+    container.innerHTML = '<table _hk="0"><thead><tr><td>Cell</td></tr></thead></table>';
 
     dispose = hydrate(
       () => (
         <table>
-          <tr>
-            <td>{text()}</td>
-          </tr>
+          <tbody>
+            <tr>
+              <td>{text()}</td>
+            </tr>
+          </tbody>
         </table>
       ),
       container