From efd89d0168a5367a8fff5e13d6f50623c08f8b17 Mon Sep 17 00:00:00 2001
From: Lucas Werkmeister <lucas.werkmeister@wikimedia.de>
Date: Wed, 4 Jun 2025 18:01:10 +0200
Subject: [PATCH 1/7] Add PHPUnit result cache to .gitignore

---
 .gitignore | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.gitignore b/.gitignore
index c56a231..0500c3c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,3 +3,4 @@
 vendor
 node_modules/
 composer.lock
+.phpunit.result.cache

From ec9da4096f1d08df838f18df651a565077b123bf Mon Sep 17 00:00:00 2001
From: Lucas Werkmeister <lucas.werkmeister@wikimedia.de>
Date: Mon, 2 Jun 2025 18:11:34 +0200
Subject: [PATCH 2/7] Declare ext-dom, ext-libxml dependencies in composer.json

Otherwise, IntelliJ complains that this is missing.
---
 composer.json | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/composer.json b/composer.json
index cf2a9b7..f7aaadb 100644
--- a/composer.json
+++ b/composer.json
@@ -9,6 +9,8 @@
 	],
 	"license": "LGPL-2.1-only",
 	"require": {
+		"ext-dom": "*",
+		"ext-libxml": "*",
 		"php": ">=7.2"
 	},
 	"autoload": {

From 814df81e32dbc497c2f35f8cbdcb6ba1b154c44c Mon Sep 17 00:00:00 2001
From: Lucas Werkmeister <lucas.werkmeister@wikimedia.de>
Date: Wed, 4 Jun 2025 12:54:43 +0200
Subject: [PATCH 3/7] Extract HtmlParser class
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Component’s responsibilities now start at the DOMElement; HtmlParser
contains the code to parse the HTML and extract the root node from the
DOMDocument. (I want to extend the latter logic in a follow-up commit,
and for this it’s nicer if it’s a separate class, IMHO.)

In principle, Component::render() should probably operate on a deep
clone of the root node; then a Component could be reused without having
to parse it several times, which could come in handy later. However, at
the moment, the Component is always freshly created, so the extra clone
seems wasteful; so for now just document that render() shouldn’t be
called repeatedly. The only “public” entry point to this library so far
is Templating, which obeys this rule.

Also add covers tags to TemplatingTest, since it’s kind of an
integration test for much of the library (including JsParsing, but I
can’t be bothered to add all those classes to the covers as well).

Bug: T395802
---
 src/Component.php            | 79 +++++-------------------------------
 src/HtmlParser.php           | 65 +++++++++++++++++++++++++++++
 src/Templating.php           |  5 ++-
 tests/php/HtmlParserTest.php | 36 ++++++++++++++++
 tests/php/TemplatingTest.php |  7 +---
 5 files changed, 118 insertions(+), 74 deletions(-)
 create mode 100644 src/HtmlParser.php
 create mode 100644 tests/php/HtmlParserTest.php

diff --git a/src/Component.php b/src/Component.php
index 2389357..0e881fe 100644
--- a/src/Component.php
+++ b/src/Component.php
@@ -4,14 +4,10 @@
 
 use DOMAttr;
 use DOMCharacterData;
-use DOMDocument;
 use DOMElement;
 use DOMNode;
 use DOMNodeList;
 use DOMText;
-use Exception;
-use LibXMLError;
-
 use WMDE\VueJsTemplating\JsParsing\BasicJsExpressionParser;
 use WMDE\VueJsTemplating\JsParsing\CachingExpressionParser;
 use WMDE\VueJsTemplating\JsParsing\JsExpressionParser;
@@ -19,9 +15,9 @@
 class Component {
 
 	/**
-	 * @var string HTML
+	 * @var DOMElement
 	 */
-	private $template;
+	private $rootNode;
 
 	/**
 	 * @var JsExpressionParser
@@ -29,79 +25,26 @@ class Component {
 	private $expressionParser;
 
 	/**
-	 * @param string $template HTML
+	 * @param DOMElement $rootNode
 	 * @param callable[] $methods
 	 */
-	public function __construct( $template, array $methods ) {
-		$this->template = $template;
+	public function __construct( DOMElement $rootNode, array $methods ) {
+		$this->rootNode = $rootNode;
 		$this->expressionParser = new CachingExpressionParser( new BasicJsExpressionParser( $methods ) );
 	}
 
 	/**
+	 * Note: this method is not currently safe to call repeatedly
+	 * (the internal root node is modified in-place).
+	 *
 	 * @param array $data
 	 *
 	 * @return string HTML
 	 */
 	public function render( array $data ) {
-		$document = $this->parseHtml( $this->template );
-
-		$rootNode = $this->getRootNode( $document );
-		$this->handleNode( $rootNode, $data );
-
-		return $document->saveHTML( $rootNode );
-	}
-
-	/**
-	 * @param string $html HTML
-	 *
-	 * @return DOMDocument
-	 */
-	private function parseHtml( $html ) {
-		if ( LIBXML_VERSION < 20900 ) {
-			$entityLoaderDisabled = libxml_disable_entity_loader( true );
-		}
-		$internalErrors = libxml_use_internal_errors( true );
-		$document = new DOMDocument( '1.0', 'UTF-8' );
-
-		// Ensure $html is treated as UTF-8, see https://stackoverflow.com/a/8218649
-		// LIBXML_NOBLANKS Constant excludes "ghost nodes" to avoid violating
-		// vue's single root node constraint
-		if ( !$document->loadHTML( '<?xml encoding="utf-8" ?>' . $html, LIBXML_NOBLANKS ) ) {
-			//TODO Test failure
-		}
-
-		/** @var LibXMLError[] $errors */
-		$errors = libxml_get_errors();
-		libxml_clear_errors();
-
-		// Restore previous state
-		libxml_use_internal_errors( $internalErrors );
-		if ( LIBXML_VERSION < 20900 ) {
-			libxml_disable_entity_loader( $entityLoaderDisabled );
-		}
-
-		foreach ( $errors as $error ) {
-			//TODO html5 tags can fail parsing
-			//TODO Throw an exception
-		}
-
-		return $document;
-	}
-
-	/**
-	 * @param DOMDocument $document
-	 *
-	 * @return DOMElement
-	 * @throws Exception
-	 */
-	private function getRootNode( DOMDocument $document ) {
-		$rootNodes = $document->documentElement->childNodes->item( 0 )->childNodes;
-
-		if ( $rootNodes->length > 1 ) {
-			throw new Exception( 'Template should have only one root node' );
-		}
+		$this->handleNode( $this->rootNode, $data );
 
-		return $rootNodes->item( 0 );
+		return $this->rootNode->ownerDocument->saveHTML( $this->rootNode );
 	}
 
 	/**
@@ -245,7 +188,7 @@ private function handleFor( DOMNode $node, array $data ) {
 	}
 
 	private function appendHTML( DOMNode $parent, $source ) {
-		$tmpDoc = $this->parseHtml( $source );
+		$tmpDoc = ( new HtmlParser() )->parseHtml( $source );
 		foreach ( $tmpDoc->getElementsByTagName( 'body' )->item( 0 )->childNodes as $node ) {
 			$node = $parent->ownerDocument->importNode( $node, true );
 			$parent->appendChild( $node );
diff --git a/src/HtmlParser.php b/src/HtmlParser.php
new file mode 100644
index 0000000..4674337
--- /dev/null
+++ b/src/HtmlParser.php
@@ -0,0 +1,65 @@
+<?php
+
+declare( strict_types = 1 );
+
+namespace WMDE\VueJsTemplating;
+
+use DOMDocument;
+use DOMElement;
+use Exception;
+use LibXMLError;
+
+/**
+ * Methods for parsing HTML strings and extracting elements from them.
+ */
+class HtmlParser {
+
+	/**
+	 * Parse the given HTML string into a DOM document.
+	 */
+	public function parseHtml( string $html ): DOMDocument {
+		if ( LIBXML_VERSION < 20900 ) {
+			$entityLoaderDisabled = libxml_disable_entity_loader( true );
+		}
+		$internalErrors = libxml_use_internal_errors( true );
+		$document = new DOMDocument( '1.0', 'UTF-8' );
+
+		// Ensure $html is treated as UTF-8, see https://stackoverflow.com/a/8218649
+		// LIBXML_NOBLANKS Constant excludes "ghost nodes" to avoid violating
+		// vue's single root node constraint
+		if ( !$document->loadHTML( '<?xml encoding="utf-8" ?>' . $html, LIBXML_NOBLANKS ) ) {
+			//TODO Test failure
+		}
+
+		/** @var LibXMLError[] $errors */
+		$errors = libxml_get_errors();
+		libxml_clear_errors();
+
+		// Restore previous state
+		libxml_use_internal_errors( $internalErrors );
+		if ( LIBXML_VERSION < 20900 ) {
+			libxml_disable_entity_loader( $entityLoaderDisabled );
+		}
+
+		foreach ( $errors as $error ) {
+			//TODO html5 tags can fail parsing
+			//TODO Throw an exception
+		}
+
+		return $document;
+	}
+
+	/**
+	 * Get the root node of the template represented by the given document.
+	 */
+	public function getRootNode( DOMDocument $document ): DOMElement {
+		$rootNodes = $document->documentElement->childNodes->item( 0 )->childNodes;
+
+		if ( $rootNodes->length > 1 ) {
+			throw new Exception( 'Template should have only one root node' );
+		}
+
+		return $rootNodes->item( 0 );
+	}
+
+}
diff --git a/src/Templating.php b/src/Templating.php
index 77258e0..a7d3deb 100644
--- a/src/Templating.php
+++ b/src/Templating.php
@@ -12,7 +12,10 @@ class Templating {
 	 * @return string
 	 */
 	public function render( $template, array $data, array $methods = [] ) {
-		$component = new Component( $template, $methods );
+		$htmlParser = new HtmlParser();
+		$document = $htmlParser->parseHtml( $template );
+		$rootNode = $htmlParser->getRootNode( $document );
+		$component = new Component( $rootNode, $methods );
 		return $component->render( $data );
 	}
 
diff --git a/tests/php/HtmlParserTest.php b/tests/php/HtmlParserTest.php
new file mode 100644
index 0000000..81a89b6
--- /dev/null
+++ b/tests/php/HtmlParserTest.php
@@ -0,0 +1,36 @@
+<?php
+
+namespace WMDE\VueJsTemplating\Test;
+
+use DOMElement;
+use Exception;
+use PHPUnit\Framework\TestCase;
+use WMDE\VueJsTemplating\HtmlParser;
+
+/**
+ * @covers \WMDE\VueJsTemplating\HtmlParser
+ */
+class HtmlParserTest extends TestCase {
+
+	private function parseAndGetRootNode( string $html ): DOMElement {
+		$htmlParser = new HtmlParser();
+		$document = $htmlParser->parseHtml( $html );
+		return $htmlParser->getRootNode( $document );
+	}
+
+	private function assertIsDivTest( DOMElement $element ): void {
+		$this->assertSame( 'div', $element->tagName );
+		$this->assertSame( 'test', $element->getAttribute( 'class' ) );
+	}
+
+	public function testSingleRootNode(): void {
+		$rootNode = $this->parseAndGetRootNode( '<div class="test"></div>' );
+		$this->assertIsDivTest( $rootNode );
+	}
+
+	public function testTwoRootNodes() {
+		$this->expectException( Exception::class );
+		$this->parseAndGetRootNode( '<p></p><p></p>' );
+	}
+
+}
diff --git a/tests/php/TemplatingTest.php b/tests/php/TemplatingTest.php
index a6dc50a..6b74e0d 100644
--- a/tests/php/TemplatingTest.php
+++ b/tests/php/TemplatingTest.php
@@ -7,6 +7,8 @@
 use WMDE\VueJsTemplating\Templating;
 
 /**
+ * @covers \WMDE\VueJsTemplating\Component
+ * @covers \WMDE\VueJsTemplating\HtmlParser
  * @covers \WMDE\VueJsTemplating\Templating
  */
 class TemplatingTest extends TestCase {
@@ -17,11 +19,6 @@ public function testJustASingleEmptyHtmlElement() {
 		$this->assertSame( '<div></div>', $result );
 	}
 
-	public function testTemplateHasTwoRootNodes_ThrowsAnException() {
-		$this->expectException( Exception::class );
-		$this->createAndRender( '<p></p><p></p>', [] );
-	}
-
 	public function testTemplateHasOnClickHandler_RemoveHandlerFormOutput() {
 		$result = $this->createAndRender( '<div v-on:click="doStuff"></div>', [] );
 

From da2e5a27e256d5d497d7333b4cccaf06516e131b Mon Sep 17 00:00:00 2001
From: Lucas Werkmeister <lucas.werkmeister@wikimedia.de>
Date: Mon, 2 Jun 2025 18:02:06 +0200
Subject: [PATCH 4/7] Handle empty documents slightly better
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Previously, we’d crash because the documentElement is null in this case.
---
 src/HtmlParser.php           | 4 ++++
 tests/php/HtmlParserTest.php | 6 ++++++
 2 files changed, 10 insertions(+)

diff --git a/src/HtmlParser.php b/src/HtmlParser.php
index 4674337..6b54d14 100644
--- a/src/HtmlParser.php
+++ b/src/HtmlParser.php
@@ -53,6 +53,10 @@ public function parseHtml( string $html ): DOMDocument {
 	 * Get the root node of the template represented by the given document.
 	 */
 	public function getRootNode( DOMDocument $document ): DOMElement {
+		if ( $document->documentElement === null ) {
+			throw new Exception( 'Empty document' );
+		}
+
 		$rootNodes = $document->documentElement->childNodes->item( 0 )->childNodes;
 
 		if ( $rootNodes->length > 1 ) {
diff --git a/tests/php/HtmlParserTest.php b/tests/php/HtmlParserTest.php
index 81a89b6..a572d6f 100644
--- a/tests/php/HtmlParserTest.php
+++ b/tests/php/HtmlParserTest.php
@@ -28,6 +28,12 @@ public function testSingleRootNode(): void {
 		$this->assertIsDivTest( $rootNode );
 	}
 
+	public function testEmptyDocument(): void {
+		$this->expectException( Exception::class );
+		$this->expectExceptionMessage( 'Empty document' );
+		$this->parseAndGetRootNode( '' );
+	}
+
 	public function testTwoRootNodes() {
 		$this->expectException( Exception::class );
 		$this->parseAndGetRootNode( '<p></p><p></p>' );

From e9a784aaa5dc69236ede4a5c14b1fa9a71f3665b Mon Sep 17 00:00:00 2001
From: Lucas Werkmeister <lucas.werkmeister@wikimedia.de>
Date: Wed, 4 Jun 2025 16:46:39 +0200
Subject: [PATCH 5/7] Extract HtmlParser::getBodyElement()
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

So we can also use it in Component::appendHTML() (v-html="" handling).
Part of this will also be useful when getRootNode() gains support for
SFC inputs later (which is why appendHTML() doesn’t use getRootNode()
directly).

In theory, we could skip over a <head> element in the <html>, but as I
don’t think it makes sense to have a <head> in any Vue component /
template, let’s just throw an error in that case and include a test for
that. (I don’t think we can test the “expected <html>” condition, that
part is basically dead code – the parser should always synthesize <html>
and <body> elements surrounding “normal” markup if it’s not already
present in the source.)
---
 src/Component.php            |  5 +++--
 src/HtmlParser.php           | 32 +++++++++++++++++++++++++++-----
 tests/php/HtmlParserTest.php |  7 +++++++
 3 files changed, 37 insertions(+), 7 deletions(-)

diff --git a/src/Component.php b/src/Component.php
index 0e881fe..50e3856 100644
--- a/src/Component.php
+++ b/src/Component.php
@@ -188,8 +188,9 @@ private function handleFor( DOMNode $node, array $data ) {
 	}
 
 	private function appendHTML( DOMNode $parent, $source ) {
-		$tmpDoc = ( new HtmlParser() )->parseHtml( $source );
-		foreach ( $tmpDoc->getElementsByTagName( 'body' )->item( 0 )->childNodes as $node ) {
+		$htmlParser = new HtmlParser();
+		$tmpDoc = $htmlParser->parseHtml( $source );
+		foreach ( $htmlParser->getBodyElement( $tmpDoc )->childNodes as $node ) {
 			$node = $parent->ownerDocument->importNode( $node, true );
 			$parent->appendChild( $node );
 		}
diff --git a/src/HtmlParser.php b/src/HtmlParser.php
index 6b54d14..e3335a5 100644
--- a/src/HtmlParser.php
+++ b/src/HtmlParser.php
@@ -53,11 +53,7 @@ public function parseHtml( string $html ): DOMDocument {
 	 * Get the root node of the template represented by the given document.
 	 */
 	public function getRootNode( DOMDocument $document ): DOMElement {
-		if ( $document->documentElement === null ) {
-			throw new Exception( 'Empty document' );
-		}
-
-		$rootNodes = $document->documentElement->childNodes->item( 0 )->childNodes;
+		$rootNodes = $this->getBodyElement( $document )->childNodes;
 
 		if ( $rootNodes->length > 1 ) {
 			throw new Exception( 'Template should have only one root node' );
@@ -66,4 +62,30 @@ public function getRootNode( DOMDocument $document ): DOMElement {
 		return $rootNodes->item( 0 );
 	}
 
+	/**
+	 * Get the `<html>` element of the given document.
+	 */
+	public function getHtmlElement( DOMDocument $document ): DOMElement {
+		$documentElement = $document->documentElement;
+		if ( $documentElement === null ) {
+			throw new Exception( 'Empty document' );
+		}
+		if ( $documentElement->tagName !== 'html' ) {
+			throw new Exception( "Expected <html>, got <{$documentElement->tagName}>" );
+		}
+		return $documentElement;
+	}
+
+	/**
+	 * Get the `<body>` element of the given document.
+	 */
+	public function getBodyElement( DOMDocument $document ): DOMElement {
+		$htmlElement = $this->getHtmlElement( $document );
+		$bodyElement = $htmlElement->childNodes->item( 0 );
+		if ( $bodyElement->tagName !== 'body' ) {
+			throw new Exception( "Expected <body>, got <{$bodyElement->tagName}>" );
+		}
+		return $bodyElement;
+	}
+
 }
diff --git a/tests/php/HtmlParserTest.php b/tests/php/HtmlParserTest.php
index a572d6f..c3ac18a 100644
--- a/tests/php/HtmlParserTest.php
+++ b/tests/php/HtmlParserTest.php
@@ -34,6 +34,13 @@ public function testEmptyDocument(): void {
 		$this->parseAndGetRootNode( '' );
 	}
 
+	public function testHeadElement(): void {
+		$html = '<html><head><title>Title</title></head><body>ABC</body></html>';
+		$this->expectException( Exception::class );
+		$this->expectExceptionMessage( 'Expected <body>, got <head>' );
+		$this->parseAndGetRootNode( $html );
+	}
+
 	public function testTwoRootNodes() {
 		$this->expectException( Exception::class );
 		$this->parseAndGetRootNode( '<p></p><p></p>' );

From 5bbd75bc7e7ed17bcb57c3b983128541773e844f Mon Sep 17 00:00:00 2001
From: Lucas Werkmeister <lucas.werkmeister@wikimedia.de>
Date: Tue, 3 Jun 2025 16:46:20 +0200
Subject: [PATCH 6/7] Use DOMNodeList with array syntax

This is not only more readable, but also a bit faster [1] (though I
doubt this code is a bottleneck anywhere either way).

[1]: https://3v4l.org/NGEKe
---
 src/HtmlParser.php | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/HtmlParser.php b/src/HtmlParser.php
index e3335a5..109ca76 100644
--- a/src/HtmlParser.php
+++ b/src/HtmlParser.php
@@ -59,7 +59,7 @@ public function getRootNode( DOMDocument $document ): DOMElement {
 			throw new Exception( 'Template should have only one root node' );
 		}
 
-		return $rootNodes->item( 0 );
+		return $rootNodes[0];
 	}
 
 	/**
@@ -81,7 +81,7 @@ public function getHtmlElement( DOMDocument $document ): DOMElement {
 	 */
 	public function getBodyElement( DOMDocument $document ): DOMElement {
 		$htmlElement = $this->getHtmlElement( $document );
-		$bodyElement = $htmlElement->childNodes->item( 0 );
+		$bodyElement = $htmlElement->childNodes[0];
 		if ( $bodyElement->tagName !== 'body' ) {
 			throw new Exception( "Expected <body>, got <{$bodyElement->tagName}>" );
 		}

From a27aaada4e54ead7861bd5e1f136823361c5e4fe Mon Sep 17 00:00:00 2001
From: Lucas Werkmeister <lucas.werkmeister@wikimedia.de>
Date: Mon, 2 Jun 2025 18:13:53 +0200
Subject: [PATCH 7/7] Support single-file component inputs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

If the input contains a single root <template> and the other root
elements are all <script> or <style>, then pick the <template> contents
as the actual root element and only render its contents. This allows us
to use SFC *.vue files as the input.

It’s worth noting that we can’t use getBodyElement() directly, as I had
originally hoped – if the SFC starts with a <script> and then has a
<template> afterwards, rather than starting with the <template>, then
the PHP HTML parser will actually place the whole contents inside a
synthetic <head> rather than a synthetic <body>. (Such an SFC structure
is disallowed by eslint-config-wikimedia via vue/component-tags-order,
but I don’t think this library should rely on that.)

Bug: T395802
---
 src/HtmlParser.php           | 98 +++++++++++++++++++++++++++++++++---
 tests/php/HtmlParserTest.php | 19 ++++++-
 tests/php/TemplatingTest.php | 20 ++++++++
 3 files changed, 129 insertions(+), 8 deletions(-)

diff --git a/src/HtmlParser.php b/src/HtmlParser.php
index 109ca76..acd9e89 100644
--- a/src/HtmlParser.php
+++ b/src/HtmlParser.php
@@ -53,13 +53,11 @@ public function parseHtml( string $html ): DOMDocument {
 	 * Get the root node of the template represented by the given document.
 	 */
 	public function getRootNode( DOMDocument $document ): DOMElement {
-		$rootNodes = $this->getBodyElement( $document )->childNodes;
-
-		if ( $rootNodes->length > 1 ) {
-			throw new Exception( 'Template should have only one root node' );
-		}
-
-		return $rootNodes[0];
+		$htmlElement = $this->getHtmlElement( $document );
+		$headOrBody = $this->getSoleHeadOrBody( $htmlElement );
+		$rootNodeParent = $this->getTemplateElement( $headOrBody ) ?? $headOrBody;
+		$rootNode = $this->getOnlySubstantialChild( $rootNodeParent );
+		return $rootNode;
 	}
 
 	/**
@@ -88,4 +86,90 @@ public function getBodyElement( DOMDocument $document ): DOMElement {
 		return $bodyElement;
 	}
 
+	/**
+	 * Get the `<head>` or `<body>` element of the given document,
+	 * asserting that it is the only child (cannot have both nor any other children).
+	 */
+	private function getSoleHeadOrBody( DOMElement $htmlElement ): DOMElement {
+		$length = $htmlElement->childNodes->length;
+		if ( $length !== 1 ) {
+			throw new Exception( "Expected exactly 1 <html> child, got $length" );
+		}
+
+		$child = $htmlElement->childNodes[0];
+		$tagName = $child->tagName;
+		if ( $tagName !== 'head' && $tagName !== 'body' ) {
+			throw new Exception( "Expected <head> or <body>, got <$tagName>" );
+		}
+
+		return $child;
+	}
+
+	/**
+	 * Get the `<template>` element of the given `<head>` or `<body>` element,
+	 * discarding any adjacent `<script>` or `<style>` elements
+	 * if the input is in Single-File Component (SFC) syntax.
+	 */
+	private function getTemplateElement( DOMElement $rootElement ): ?DOMElement {
+		$onlyTemplateElement = null;
+		foreach ( $rootElement->childNodes as $node ) {
+			if ( $node->nodeType === XML_COMMENT_NODE ) {
+				// comment node, ignore
+				continue;
+			} elseif ( $node->nodeType === XML_TEXT_NODE ) {
+				if ( trim( $node->textContent ) === '' ) {
+					// whitespace-only text node, ignore
+					continue;
+				} else {
+					// not SFC
+					$onlyTemplateElement = null;
+					break;
+				}
+			}
+			if ( $node->tagName === 'template' ) {
+				if ( $onlyTemplateElement === null ) {
+					$onlyTemplateElement = $node;
+				} else {
+					// more than one <template>, handle as non-SFC and throw error below
+					$onlyTemplateElement = null;
+					break;
+				}
+			} elseif ( $node->tagName !== 'script' && $node->tagName !== 'style' ) {
+				// top-level tag other than <template>, <script> or <style> => not SFC
+				$onlyTemplateElement = null;
+				break;
+			}
+		}
+		return $onlyTemplateElement;
+	}
+
+	/**
+	 * Get the only “substantial” child of the given element.
+	 * Ignore any adjacent comments or whitespace-only text nodes
+	 * (such as line breaks or indentation).
+	 */
+	private function getOnlySubstantialChild( DOMElement $element ): DOMElement {
+		$onlySubstantialChild = null;
+		foreach ( $element->childNodes as $node ) {
+			if ( $node->nodeType === XML_COMMENT_NODE ) {
+				// comment node, ignore
+				continue;
+			} elseif ( $node->nodeType === XML_TEXT_NODE && trim( $node->textContent ) === '' ) {
+				// whitespace-only text node, ignore
+				continue;
+			}
+			if ( $onlySubstantialChild === null ) {
+				$onlySubstantialChild = $node;
+			} else {
+				throw new Exception( 'Template should only have one root node' );
+			}
+		}
+
+		if ( $onlySubstantialChild !== null ) {
+			return $onlySubstantialChild;
+		} else {
+			throw new Exception( 'Template contained no root node' );
+		}
+	}
+
 }
diff --git a/tests/php/HtmlParserTest.php b/tests/php/HtmlParserTest.php
index c3ac18a..af824b4 100644
--- a/tests/php/HtmlParserTest.php
+++ b/tests/php/HtmlParserTest.php
@@ -28,6 +28,23 @@ public function testSingleRootNode(): void {
 		$this->assertIsDivTest( $rootNode );
 	}
 
+	public function testSingleFileComponent_OnlyTemplate(): void {
+		$rootNode = $this->parseAndGetRootNode( '<template><div class="test"></div></template>' );
+		$this->assertIsDivTest( $rootNode );
+	}
+
+	public function testSingleFileComponent_TemplateAndScriptAndStyle(): void {
+		$template = '<template><div class="test"></div></template><script></script><style></style>';
+		$rootNode = $this->parseAndGetRootNode( $template );
+		$this->assertIsDivTest( $rootNode );
+	}
+
+	public function testSingleFileComponent_ScriptAndTemplateAndStyle(): void {
+		$template = '<script></script><template><div class="test"></div></template><style></style>';
+		$rootNode = $this->parseAndGetRootNode( $template );
+		$this->assertIsDivTest( $rootNode );
+	}
+
 	public function testEmptyDocument(): void {
 		$this->expectException( Exception::class );
 		$this->expectExceptionMessage( 'Empty document' );
@@ -37,7 +54,7 @@ public function testEmptyDocument(): void {
 	public function testHeadElement(): void {
 		$html = '<html><head><title>Title</title></head><body>ABC</body></html>';
 		$this->expectException( Exception::class );
-		$this->expectExceptionMessage( 'Expected <body>, got <head>' );
+		$this->expectExceptionMessage( 'Expected exactly 1 <html> child, got 2' );
 		$this->parseAndGetRootNode( $html );
 	}
 
diff --git a/tests/php/TemplatingTest.php b/tests/php/TemplatingTest.php
index 6b74e0d..0092bb6 100644
--- a/tests/php/TemplatingTest.php
+++ b/tests/php/TemplatingTest.php
@@ -19,6 +19,26 @@ public function testJustASingleEmptyHtmlElement() {
 		$this->assertSame( '<div></div>', $result );
 	}
 
+	public function testSingleFileComponent(): void {
+		$template = <<< 'EOF'
+<template>
+	<!-- eslint-disable-next-line something -->
+	<div></div>
+</template>
+<script setup>
+const something = 'something';
+</script>
+<style scoped>
+.some-class {
+	font-weight: bold;
+}
+</style>
+EOF;
+		$result = $this->createAndRender( $template, [] );
+
+		$this->assertSame( '<div></div>', $result );
+	}
+
 	public function testTemplateHasOnClickHandler_RemoveHandlerFormOutput() {
 		$result = $this->createAndRender( '<div v-on:click="doStuff"></div>', [] );