justhtml 3.2.0__tar.gz → 3.3.0__tar.gz

{justhtml-3.2.0 → justhtml-3.3.0}/.github/workflows/ci.yml

@@ -41,15 +41,25 @@ jobs:
           git -C html5lib-tests checkout 9fb614afaa42ce8787840f057b32084308e76549
           git -C html5lib-tests rev-parse HEAD
 
+      - name: Checkout WPT tree-construction tests
+        run: |
+          cd ..
+          git clone --filter=blob:none --sparse https://github.com/web-platform-tests/wpt.git
+          git -C wpt fetch origin 75b089d70448e1da425ab8cf38971b6af41f3cea
+          git -C wpt checkout 75b089d70448e1da425ab8cf38971b6af41f3cea
+          git -C wpt sparse-checkout set html/syntax/parsing/resources
+          git -C wpt rev-parse HEAD
+
       - name: Setup test fixtures
         run: |
           cp -a ../html5lib-tests/tokenizer tests/html5lib-tests-tokenizer
-          cp -a ../html5lib-tests/tree-construction tests/html5lib-tests-tree
+          cp -a ../wpt/html/syntax/parsing/resources tests/html5lib-tests-tree
           cp -a ../html5lib-tests/serializer tests/html5lib-tests-serializer
           cp -a ../html5lib-tests/encoding tests/html5lib-tests-encoding
 
       - name: Run pre-commit
         id: precommit
+        if: matrix.python-version == '3.14'
         run: pre-commit run --show-diff-on-failure --color=always --all-files
         env:
           SKIP: mypy
@@ -61,14 +71,14 @@ jobs:
       - name: Diagnose test failures (verbose)
         if: always()
         run: |
-          if [ "${{ steps.precommit.outcome }}" = "success" ] && [ "${{ steps.run_tests.outcome }}" = "success" ]; then
+          if [ "${{ steps.precommit.outcome }}" != "failure" ] && [ "${{ steps.run_tests.outcome }}" = "success" ]; then
             echo "No failures detected; skipping verbose rerun."
             exit 0
           fi
           python run_tests.py -v --no-write-summary
 
       - name: Run mypy
-        if: matrix.python-version == '3.12'
+        if: matrix.python-version == '3.14'
         run: mypy
 
   test-pyodide:

{justhtml-3.2.0 → justhtml-3.3.0}/.pre-commit-config.yaml

@@ -33,7 +33,7 @@ repos:
     hooks:
       - id: tests-coverage
         name: Tests & Coverage
-        entry: bash -c 'coverage run run_tests.py --no-write-summary && coverage report'
+        entry: bash -c 'coverage run run_tests.py && coverage report'
         language: system
         pass_filenames: false
         always_run: true

{justhtml-3.2.0 → justhtml-3.3.0}/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.3.0] - 2026-07-04
+
+### Changed
+- Document that `Linkify(...)` must run before an explicit `Sanitize(...)` in a transform list, not after, and correct the `clean_url_value()` example to escape the returned value with `escape_attr_value()` before embedding it in HTML. Previously, the docs suggested orderings that silently skip URL-policy validation on Linkify-generated links, and separately claimed `clean_url_value()` output needed no further escaping for HTML attribute embedding.
+
+### Fixed
+- Copy `override_attrs` when cloning a node instead of storing the caller's dict by reference. Previously, calling `clone_node(override_attrs=...)` more than once with the same dict (or holding onto that dict after cloning) produced clones that aliased the same attribute dictionary, so mutating one clone's attributes silently mutated another clone or the caller's own dict.
+
+### Performance
+- Avoid rescanning the entire open-elements stack for every unmatched end tag inside foreign (SVG/MathML) content in the streaming parser (`stream()`), by tracking open-element name counts the same way the main parser engine does. Previously, a run of unmatched end tags deep inside foreign content was quadratic in the depth of nesting.
+- Bound `Linkify(...)`'s email-candidate pattern to RFC 5321's 64-octet local-part limit instead of an unbounded match. Previously, the greedy local-part match followed by a required (and often absent) `@` forced a full-length backtrack at every candidate start position, making long "@"-free runs of otherwise email-local-part-legal text (such as repeated dotted-numeric tokens) quadratic to scan.
+- Share cached sibling/ancestor lookups across nodes when matching structural selectors (`:nth-child`, sibling combinators) in custom `EditAttrs(...)`/`SetAttrs(...)`-style transform pipelines, the same way `query()` already does. Previously, each node rebuilt this data from scratch, making structural-selector transforms quadratic over documents with many siblings. Sharing is only enabled when every transform in the pipeline is provably attribute-only; a pipeline that also uses `Edit(...)`, `Decide(...)`, `Drop(...)`, `Linkify(...)`, or similar structure-changing transforms is unaffected and keeps its previous (already correct) behavior.
+- Access the parser's open-elements stack through a plain attribute again instead of a property, removing a Python-level function call from one of the hottest paths in tree construction.
+
+### Security
+- (Severity: Low) HTML-escape a literal `&` left over after percent-encoding a URL for the `HTMLContext.URL` serialization context (used for `href`/`src`-style attributes). Previously, a URL containing a legacy (no-semicolon) named HTML entity immediately after a decoded `&` could be interpreted differently once embedded in an HTML attribute and re-parsed by a browser than what was validated.
+
 ## [3.2.0] - 2026-07-04
 
 ### Changed

{justhtml-3.2.0 → justhtml-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: justhtml
-Version: 3.2.0
+Version: 3.3.0
 Summary: A pure Python HTML5 parser that just works.
 Project-URL: Homepage, https://github.com/emilstenstrom/justhtml
 Project-URL: Issues, https://github.com/emilstenstrom/justhtml/issues

{justhtml-3.2.0 → justhtml-3.3.0}/docs/api.md

@@ -602,7 +602,7 @@ To override the encoding for byte input, pass `encoding=...`.
 | `"end"` | `tag_name` | Closing tag |
 | `"text"` | `text_content` | Text content |
 | `"comment"` | `comment_text` | HTML comment |
-| `"doctype"` | `doctype_name` | DOCTYPE declaration |
+| `"doctype"` | `(name, public_id, system_id)` | DOCTYPE declaration fields |
 
 ---
 

{justhtml-3.2.0 → justhtml-3.3.0}/docs/linkify.md

@@ -125,6 +125,33 @@ This matters for Linkify because sanitization policies can remove or rewrite att
 - Schemes not allowed for `a[href]` are stripped (the `<a>` remains, but `href` is removed).
 - Protocol-relative `//example.com` is resolved according to policy (default: `https://example.com`).
 
+**Put `Linkify()` before `Sanitize()`, not after.** It is tempting to reach for `transforms=[Sanitize(policy), Linkify()]`, reasoning "sanitize first, then add links to the clean text." That order does the opposite of what it looks like: your explicit `Sanitize()` position becomes the sanitize point (see above), so the `<a href="...">` elements Linkify creates afterward are never checked against your `UrlPolicy`/`UrlRule` restrictions.
+
+```python
+from justhtml import JustHTML, Linkify, Sanitize, SanitizationPolicy, UrlPolicy, UrlRule
+
+# A policy that only allows https:// links on <a href>.
+policy = SanitizationPolicy(
+    allowed_tags=["a"],
+    allowed_attributes={"a": ["href"]},
+    url_policy=UrlPolicy(allow_rules={("a", "href"): UrlRule(allowed_schemes={"https"})}),
+)
+text = "See http://example.com"
+
+# Wrong: Linkify's generated <a href> is created after the sanitize point,
+# so the https-only restriction never sees it.
+doc = JustHTML(text, transforms=[Sanitize(policy), Linkify()])
+print(doc.to_html(pretty=False))
+# => See <a href="http://example.com">http://example.com</a>
+
+# Right: Linkify runs first, so its output is covered by the same sanitize pass.
+doc = JustHTML(text, transforms=[Linkify(), Sanitize(policy)])
+print(doc.to_html(pretty=False))
+# => See http://example.com
+```
+
+If you don't need other transforms between them, the simplest safe option is to omit `Sanitize()` entirely and let `sanitize=True` (the default) append it automatically after `Linkify()`.
+
 If you want Linkify output without any sanitization changes (trusted input only), use `sanitize=False` and avoid adding `Sanitize(...)` in transforms.
 
 ## Provenance

{justhtml-3.2.0 → justhtml-3.3.0}/docs/sanitization.md

@@ -124,10 +124,12 @@ rule = UrlRule(allowed_schemes={"https", "mailto"})
 cleaned_url = JustHTML.clean_url_value(value=user_url, url_rule=rule)
 
 if cleaned_url:
-    # URL is safe to use.
-    # Note: clean_url_value performs URL encoding, so no extra escape needed if using double quotes in HTML.
-    # <a href="${cleaned_url}">
-    pass
+    # cleaned_url is a validated, percent-encoded URL, not an HTML-attribute-safe
+    # string: it deliberately keeps "&" literal so multi-parameter query strings
+    # stay usable as plain text (e.g. in a JS string). Escape it like any other
+    # attribute value before embedding it in HTML.
+    safe_url = JustHTML.escape_attr_value(cleaned_url)
+    # <a href="${safe_url}">
 ```
 
 ## Configuration

{justhtml-3.2.0 → justhtml-3.3.0}/docs/streaming.md

@@ -15,7 +15,6 @@ The streaming parser is:
 
 ```python
 from justhtml import stream
-from pathlib import Path
 
 html = "<html><body><p>Hello, world!</p></body></html>"
 
@@ -23,12 +22,24 @@ for event, data in stream(html):
     print(event, data)
 ```
 
+Output:
+```text
+start ('html', {})
+start ('body', {})
+start ('p', {})
+text Hello, world!
+end p
+end body
+end html
+```
+
 ## Byte Input and Encodings
 
 `stream()` also accepts bytes (`bytes`, `bytearray`, `memoryview`). In that case, the input is decoded using HTML encoding sniffing (including a `windows-1252` fallback for legacy documents).
 
 ```python
 from justhtml import stream
+from pathlib import Path
 
 data = Path("page.html").read_bytes()
 for event, data in stream(data):
@@ -48,19 +59,6 @@ for event, data in stream(data, encoding="utf-8"):
 
 See [Encoding & Byte Input](encoding.md) for details.
 
-Output:
-```
-start ('html', {})
-start ('head', {})
-end head
-start ('body', {})
-start ('p', {})
-text Hello, world!
-end p
-end body
-end html
-```
-
 ## Events
 
 | Event | Data Type | Description |
@@ -69,7 +67,7 @@ end html
 | `"end"` | `tag_name` | Closing tag encountered |
 | `"text"` | `str` | Text content |
 | `"comment"` | `str` | HTML comment content |
-| `"doctype"` | `str` | DOCTYPE name (usually `"html"`) |
+| `"doctype"` | `(name, public_id, system_id)` | DOCTYPE declaration fields |
 
 ## Examples
 

{justhtml-3.2.0 → justhtml-3.3.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "justhtml"
 authors = [{ name = "Emil Stenström", email = "emil@emilstenstrom.se" }]
-version = "3.2.0"
+version = "3.3.0"
 description = "A pure Python HTML5 parser that just works."
 readme = "README.md"
 license = { file = "LICENSE" }

{justhtml-3.2.0 → justhtml-3.3.0}/src/justhtml/dom/__init__.py

@@ -422,7 +422,7 @@ class Node:
         Returns:
             A new node that is a copy of this node.
         """
-        attrs = override_attrs if override_attrs is not None else (self.attrs.copy() if self.attrs else None)
+        attrs = override_attrs.copy() if override_attrs is not None else (self.attrs.copy() if self.attrs else None)
         clone = Node(
             self.name,
             attrs,
@@ -551,7 +551,7 @@ class Element(Node):
         self._self_closing = False
 
     def clone_node(self, deep: bool = False, override_attrs: dict[str, str | None] | None = None) -> Element:
-        attrs = override_attrs if override_attrs is not None else (self.attrs.copy() if self.attrs else {})
+        attrs = override_attrs.copy() if override_attrs is not None else (self.attrs.copy() if self.attrs else {})
         clone = Element(self.name, attrs, self.namespace)
         clone._source_html = self._source_html
         clone._origin_pos = self._origin_pos
@@ -586,7 +586,7 @@ class Template(Element):
             self.template_content = None
 
     def clone_node(self, deep: bool = False, override_attrs: dict[str, str | None] | None = None) -> Template:
-        attrs = override_attrs if override_attrs is not None else (self.attrs.copy() if self.attrs else {})
+        attrs = override_attrs.copy() if override_attrs is not None else (self.attrs.copy() if self.attrs else {})
         clone = Template(
             self.name,
             attrs,

{justhtml-3.2.0 → justhtml-3.3.0}/src/justhtml/parser/engine.py

@@ -722,7 +722,7 @@ class ParseEngine:
         "_rcdata_tags",
         "_skip_escaped_comment_space",
         "_special_elements",
-        "_stack_impl",
+        "_stack",
         "_strip_invisible_unicode",
         "_table_allowed_children",
         "_table_cell_tags",
@@ -847,20 +847,12 @@ class ParseEngine:
         self._nodes_to_drop: list[Element] = []
         self._nodes_to_unwrap: list[Element] = []
         self._template_modes: list[str] = []
-        self._stack_impl: _CountingStack = _CountingStack()
+        self._stack: _CountingStack = _CountingStack()
 
     @property
     def errors(self) -> list[ParseError]:
         return self._errors
 
-    @property
-    def _stack(self) -> _CountingStack:
-        return self._stack_impl
-
-    @_stack.setter
-    def _stack(self, value: list[Node]) -> None:
-        self._stack_impl = value if isinstance(value, _CountingStack) else _CountingStack(value)
-
     def _line_col_at_pos(self, pos: int) -> tuple[int, int]:
         if pos < 0:  # pragma: no cover - parser offsets are non-negative
             pos = 0
@@ -1104,7 +1096,7 @@ class ParseEngine:
             html_context = self._fragment_context_namespace in {None, "html"}
             if html_context and context_name in self._rcdata_tags:
                 self._body = root
-                self._stack = [root]
+                self._stack = _CountingStack([root])
                 text = self._clean_text(self._html_input, replace_null=True)
                 if context_name == "textarea" and text.startswith("\n"):
                     text = text[1:]
@@ -1114,7 +1106,7 @@ class ParseEngine:
 
             if html_context and context_name in self._plaintext_tags:
                 self._body = root
-                self._stack = [root]
+                self._stack = _CountingStack([root])
                 self._append_raw_literal_text(self._html_input, 0)
                 return root
 
@@ -1124,7 +1116,7 @@ class ParseEngine:
                 or context_name in self._rawtext_element_tags
             ):
                 self._body = root
-                self._stack = [root]
+                self._stack = _CountingStack([root])
                 self._append_raw_literal_text(self._html_input, 0)
                 return root
 
@@ -1139,7 +1131,7 @@ class ParseEngine:
                 self._html = context
                 self._head = head
                 self._body = body
-                self._stack = [root, context, body]
+                self._stack = _CountingStack([root, context, body])
                 if not self._raw_mode:
                     if (
                         "head" not in self._allowed_tags
@@ -1154,10 +1146,10 @@ class ParseEngine:
                 self._append(root, context)
                 self._fragment_context_node = context
                 self._body = context
-                self._stack = [root, context]
+                self._stack = _CountingStack([root, context])
             else:
                 self._body = root
-                self._stack = [root]
+                self._stack = _CountingStack([root])
         else:
             doc = Document()
             if self._track_tag_spans:
@@ -1172,7 +1164,7 @@ class ParseEngine:
             self._html = html_el
             self._head = head
             self._body = body
-            self._stack = [doc, html_el, body]
+            self._stack = _CountingStack([doc, html_el, body])
 
         self._parse_range(0, self._length)
         self._finish_document_shell()
@@ -1408,7 +1400,7 @@ class ParseEngine:
             and not self._body_has_content()
             and not self._has_open_parser_only_template()
         ):
-            self._stack = [self._doc, self._html, self._head]  # type: ignore[list-item]
+            self._stack = _CountingStack([self._doc, self._html, self._head])  # type: ignore[list-item]
             self._after_head = False
             self._explicit_head = True
         else:
@@ -1818,7 +1810,7 @@ class ParseEngine:
                     if source_pos is not None:  # pragma: no branch - opposite edge requires invalid parser state
                         source_pos += leading_len
                     raw = stripped
-                self._stack = [self._doc, self._html, self._body]  # type: ignore[list-item]
+                self._stack = _CountingStack([self._doc, self._html, self._body])  # type: ignore[list-item]
                 self._after_head = False
                 self._body_mode_seen = True
                 parent = self._body
@@ -1826,7 +1818,7 @@ class ParseEngine:
             if raw_is_space is None:  # pragma: no branch - opposite edge requires invalid parser state
                 raw_is_space = raw.strip(_SPACE) == ""
             if not raw_is_space:
-                self._stack = [self._doc, self._html, self._body]  # type: ignore[list-item]
+                self._stack = _CountingStack([self._doc, self._html, self._body])  # type: ignore[list-item]
                 self._after_head = False
                 self._body_mode_seen = True
                 parent = self._body
@@ -1835,7 +1827,7 @@ class ParseEngine:
                 raw_is_space = raw.strip(_SPACE) == ""
             if not raw_is_space:
                 if self._find_open_html_index("body") is None:
-                    self._stack = [self._doc, self._html, self._body]  # type: ignore[list-item]
+                    self._stack = _CountingStack([self._doc, self._html, self._body])  # type: ignore[list-item]
                 self._after_body = False
                 self._after_document = False
                 self._after_html = False
@@ -2068,9 +2060,9 @@ class ParseEngine:
             if (
                 self._frameset_seen and not self._body_explicit
             ):  # pragma: no cover - later state normalization restores body mode
-                self._stack = [self._doc, self._html]  # type: ignore[list-item]
+                self._stack = _CountingStack([self._doc, self._html])  # type: ignore[list-item]
             else:
-                self._stack = [self._doc, self._html, self._body]  # type: ignore[list-item]
+                self._stack = _CountingStack([self._doc, self._html, self._body])  # type: ignore[list-item]
             self._after_head = False
             self._body_mode_seen = True
             return pos
@@ -2078,7 +2070,7 @@ class ParseEngine:
             self._in_colgroup = False
             if self._body_mode_seen and self._stack[-1] is not self._head:
                 return pos
-            self._stack = [self._doc, self._html]  # type: ignore[list-item]
+            self._stack = _CountingStack([self._doc, self._html])  # type: ignore[list-item]
             self._after_head = True
             return pos
         if name == "colgroup" and not self._parser_only_template_depth:
@@ -2119,7 +2111,7 @@ class ParseEngine:
             and self._stack[-1] is self._head
             and self._html is not None
         ):
-            self._stack = [self._doc, self._html, self._body]  # type: ignore[list-item]
+            self._stack = _CountingStack([self._doc, self._html, self._body])  # type: ignore[list-item]
             self._after_head = False
             self._body_mode_seen = True
         if self._in_head_noscript:
@@ -2279,7 +2271,7 @@ class ParseEngine:
             if (
                 self._find_open_html_index("body") is None
             ):  # pragma: no cover - body-less after-document tags return earlier
-                self._stack = [self._doc, self._html, self._body]  # type: ignore[list-item]
+                self._stack = _CountingStack([self._doc, self._html, self._body])  # type: ignore[list-item]
             self._after_body = False
             self._after_document = False
             self._after_html = False
@@ -2291,9 +2283,9 @@ class ParseEngine:
                 return pos
             self._in_colgroup = False
             if self._head is not None and self._stack[-1] is self._head:
-                self._stack = [self._doc, self._html, self._body]  # type: ignore[list-item]
+                self._stack = _CountingStack([self._doc, self._html, self._body])  # type: ignore[list-item]
             if self._frameset_seen and not self._body_explicit:
-                self._stack = [self._doc, self._html]  # type: ignore[list-item]  # pragma: no cover - frameset state keeps later body reconstruction unreachable here
+                self._stack = _CountingStack([self._doc, self._html])  # type: ignore[list-item]  # pragma: no cover - frameset state keeps later body reconstruction unreachable here
             self._after_head = False
             self._body_mode_seen = (
                 True  # pragma: no cover - frameset end-tag paths return before re-entering body mode
@@ -2311,7 +2303,7 @@ class ParseEngine:
                     self._set_end_span(self._html, name, tag_start, tag_end)
             return pos
         if self._fragment and self._fragment_context_name == "html" and name == "html":
-            self._stack = [self._doc]
+            self._stack = _CountingStack([self._doc])
             return pos
         if not self._fragment and name == "head":
             self._in_colgroup = False
@@ -2320,7 +2312,7 @@ class ParseEngine:
             if self._head is not None:  # pragma: no branch - opposite edge requires invalid parser state
                 if self._track_tag_spans:
                     self._set_end_span(self._head, name, tag_start, tag_end)
-            self._stack = [self._doc, self._html]  # type: ignore[list-item]
+            self._stack = _CountingStack([self._doc, self._html])  # type: ignore[list-item]
             self._after_head = True
             return pos
         if name == "colgroup" and not self._parser_only_template_depth:
@@ -2383,7 +2375,7 @@ class ParseEngine:
             and self._stack[-1] is self._head
             and self._html is not None
         ):
-            self._stack = [self._doc, self._html, self._body]  # type: ignore[list-item]
+            self._stack = _CountingStack([self._doc, self._html, self._body])  # type: ignore[list-item]
             self._after_head = False
             self._body_mode_seen = True
         if self._in_head_noscript:
@@ -2551,7 +2543,7 @@ class ParseEngine:
                 if self._body_mode_seen:
                     return pos
                 if self._head is not None:  # pragma: no branch - opposite edge requires invalid parser state
-                    self._stack = [self._doc, self._html, self._head]  # type: ignore[list-item]
+                    self._stack = _CountingStack([self._doc, self._html, self._head])  # type: ignore[list-item]
                     self._after_head = False
                 return pos
             if name == "body":
@@ -2567,7 +2559,7 @@ class ParseEngine:
                 if self._body_mode_seen:
                     return pos
                 self._body_mode_seen = True
-                self._stack = [self._doc, self._html, self._body]  # type: ignore[list-item]
+                self._stack = _CountingStack([self._doc, self._html, self._body])  # type: ignore[list-item]
                 self._after_head = False
                 return pos
             if not self._body_mode_seen and not (action.head_content if action is not None else False):
@@ -2581,7 +2573,7 @@ class ParseEngine:
             and current_top is self._head
             and not (action.head_content if action is not None else False)
         ):
-            self._stack = [self._doc, self._html, self._body]  # type: ignore[list-item]
+            self._stack = _CountingStack([self._doc, self._html, self._body])  # type: ignore[list-item]
             self._after_head = False
             self._body_mode_seen = True
             current_top = self._body
@@ -2601,11 +2593,11 @@ class ParseEngine:
                 and not self._body_mode_seen
                 and not self._body_has_content()
             ):
-                self._stack = [self._doc, self._html, self._head]  # type: ignore[list-item]
+                self._stack = _CountingStack([self._doc, self._html, self._head])  # type: ignore[list-item]
                 self._after_head = False
                 current_top = self._head
             else:
-                self._stack = [self._doc, self._html, self._body]  # type: ignore[list-item]
+                self._stack = _CountingStack([self._doc, self._html, self._body])  # type: ignore[list-item]
                 self._after_head = False
                 self._body_mode_seen = True
                 current_top = self._body
@@ -2644,7 +2636,7 @@ class ParseEngine:
 
         if action is not None and action.drop_content:
             if self._raw_head_text_parent(name) and self._head is not None:
-                self._stack = [self._doc, self._html, self._head]  # type: ignore[list-item]
+                self._stack = _CountingStack([self._doc, self._html, self._head])  # type: ignore[list-item]
             return self._skip_rawtext(name, pos, end)
         if action is not None and action.drop_subtree:
             if action.allowed:  # pragma: no branch - opposite edge requires invalid parser state
@@ -2823,7 +2815,7 @@ class ParseEngine:
         in_template_content = bool(self._template_modes)
         if not self._fragment and self._after_document and name != "html" and not self._frameset_seen:
             if self._find_open_html_index("body") is None:
-                self._stack = [self._doc, self._html, self._body]  # type: ignore[list-item]
+                self._stack = _CountingStack([self._doc, self._html, self._body])  # type: ignore[list-item]
             self._after_body = False
             self._after_document = False
             self._after_html = False
@@ -2873,7 +2865,7 @@ class ParseEngine:
                         self._head.attrs.setdefault(attr_name, attr_value)
                     self._set_origin(self._head, tag_start)
                     self._set_source_span(self._head, tag_start, tag_end)
-                    self._stack = [self._doc, self._html, self._head]  # type: ignore[list-item]
+                    self._stack = _CountingStack([self._doc, self._html, self._head])  # type: ignore[list-item]
                     self._after_head = False
                 return pos
             if name == "body":
@@ -2891,7 +2883,7 @@ class ParseEngine:
                 if self._body_mode_seen:
                     return pos
                 self._body_mode_seen = True
-                self._stack = [self._doc, self._html, self._body]  # type: ignore[list-item]
+                self._stack = _CountingStack([self._doc, self._html, self._body])  # type: ignore[list-item]
                 self._after_head = False
                 return pos
             if not self._body_mode_seen and not (action.head_content if action is not None else False):
@@ -2905,7 +2897,7 @@ class ParseEngine:
             and current_top is self._head
             and not (action.head_content if action is not None else False)
         ):
-            self._stack = [self._doc, self._html, self._body]  # type: ignore[list-item]
+            self._stack = _CountingStack([self._doc, self._html, self._body])  # type: ignore[list-item]
             self._after_head = False
             self._body_mode_seen = True
             current_top = self._body
@@ -2926,11 +2918,11 @@ class ParseEngine:
                 and not self._body_mode_seen
                 and not self._body_has_content()
             ):
-                self._stack = [self._doc, self._html, self._head]  # type: ignore[list-item]
+                self._stack = _CountingStack([self._doc, self._html, self._head])  # type: ignore[list-item]
                 self._head_reentry = True
                 current_top = self._head
             else:
-                self._stack = [self._doc, self._html, self._body]  # type: ignore[list-item]
+                self._stack = _CountingStack([self._doc, self._html, self._body])  # type: ignore[list-item]
                 self._after_head = False
                 self._body_mode_seen = True
                 current_top = self._body
@@ -3071,7 +3063,7 @@ class ParseEngine:
             return self._parse_rawtext_element(name, attrs, self_closing, pos, end, tag_start, tag_end)
         if action is not None and not raw_mode and action.drop_content:
             if self._raw_head_text_parent(name) and self._head is not None:
-                self._stack = [self._doc, self._html, self._head]  # type: ignore[list-item]
+                self._stack = _CountingStack([self._doc, self._html, self._head])  # type: ignore[list-item]
             return self._skip_rawtext(name, pos, end)
         if action is not None and action.rawtext_as_text:
             return self._parse_rawtext_as_text(name, pos, end)
@@ -3086,7 +3078,7 @@ class ParseEngine:
                 or (not self._body_explicit and not self._body_mode_seen and not self._body_has_content())
             )
         ):
-            self._stack = [self._doc, self._html, self._head]  # type: ignore[list-item]
+            self._stack = _CountingStack([self._doc, self._html, self._head])  # type: ignore[list-item]
             if raw_mode:
                 self._insert_sanitized_element(
                     name, attrs, self_closing, self._head, tag_start=tag_start, tag_end=tag_end
@@ -3149,7 +3141,7 @@ class ParseEngine:
             if (
                 not self._fragment and self._html is not None
             ):  # pragma: no branch - opposite edge requires invalid parser state
-                self._stack = [self._doc, self._html]
+                self._stack = _CountingStack([self._doc, self._html])
             else:
                 for idx, stack_node in enumerate(
                     self._stack[1:], start=1
@@ -3677,7 +3669,7 @@ class ParseEngine:
         self._in_head_noscript = False
         if self._fragment or self._html is None:  # pragma: no branch - opposite edge requires invalid parser state
             return  # pragma: no cover - unreachable after parser-state guards
-        self._stack = [self._doc, self._html, self._body]  # type: ignore[list-item]
+        self._stack = _CountingStack([self._doc, self._html, self._body])  # type: ignore[list-item]
         self._after_head = False
         self._body_mode_seen = True
 
@@ -3687,7 +3679,7 @@ class ParseEngine:
         if self._open_template_index() is not None:  # pragma: no branch - reentry finishes after templates close
             return  # pragma: no cover - guarded by template close ordering
         self._head_reentry = False
-        self._stack = [self._doc, self._html]
+        self._stack = _CountingStack([self._doc, self._html])
         self._after_head = True
 
     def _close_to_fragment_context(self) -> bool:
@@ -4468,7 +4460,7 @@ class ParseEngine:
                     self._set_end_span(node, name, close_start, pos)
             self._stack.pop()
         if parsed_in_initial_head and self._html is not None and self._head is not None:
-            self._stack = [self._doc, self._html, self._head]  # type: ignore[list-item]
+            self._stack = _CountingStack([self._doc, self._html, self._head])  # type: ignore[list-item]
         self._finish_head_reentry()
         return pos
 
@@ -4520,7 +4512,7 @@ class ParseEngine:
         if self._stack and self._stack[-1] is node:  # pragma: no branch - opposite edge requires invalid parser state
             self._stack.pop()
         if parsed_in_initial_head and self._html is not None and self._head is not None:
-            self._stack = [self._doc, self._html, self._head]  # type: ignore[list-item]
+            self._stack = _CountingStack([self._doc, self._html, self._head])  # type: ignore[list-item]
         self._finish_head_reentry()
         return pos
 
@@ -5624,7 +5616,7 @@ class ParseEngine:
             children.clear()
         self._frameset_seen = True
         self._mark_active_formatting_dirty()
-        self._stack = [self._doc, self._html]  # type: ignore[list-item]
+        self._stack = _CountingStack([self._doc, self._html])  # type: ignore[list-item]
         self._after_head = False
         return True
 
@@ -5642,7 +5634,7 @@ class ParseEngine:
             self._body, Element
         ):  # pragma: no branch - opposite edge requires invalid parser state
             self._remove_child(self._html, self._body)
-            self._stack = [self._doc, self._html]
+            self._stack = _CountingStack([self._doc, self._html])
         self._frameset_seen = True
         self._mark_active_formatting_dirty()
         return True