justhtml 3.2.0__tar.gz → 3.4.0__tar.gz

{justhtml-3.2.0 → justhtml-3.4.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.4.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.4.0}/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.4.0] - 2026-07-11
+
+### Security
+- (Severity: Low) Bound named character-reference lookup to the finite HTML entity tables. Previously, a malformed `&` followed by a long alphanumeric run caused repeated shrinking-prefix allocations and lookups, making parsing quadratic and allowing denial of service before sanitization.
+- (Severity: Low) Cap diagnostics retained by `JustHTML(...)` with the new `max_errors` option (default: 1000), including parser, sanitizer, raw-text, and transform findings. Previously, input containing many independently malformed characters or unsafe constructs could allocate an unbounded number of `ParseError` objects.
+- (Severity: Low) Index active-formatting entries by signature within each HTML5 Noah's Ark marker segment, retiring superseded entries lazily and compacting in bounded batches. Previously, repeated fourth occurrences across many formatting signatures rescanned and shifted the active-formatting list, allowing quadratic parsing of crafted HTML.
+- (Severity: Low) Avoid unbounded integer conversion for untrusted `srcset` width descriptors, URL host validation, and `Linkify(...)` URL ports. Previously, inputs with more decimal digits than Python permits in `int()` could raise an uncaught `ValueError` during sanitization or linkification.
+- (Severity: Low) Bound pretty-print indentation and avoid repeatedly copying nested serialized output. Previously, serializing deeply nested untrusted HTML with the default `to_html()` settings could consume quadratic time and memory.
+- (Severity: Low) Compact sibling lists when applying a tag-only `Drop(...)` transform. Previously, dropping many matching untrusted sibling elements shifted the remaining list after every removal, making transform execution quadratic.
+
+## [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.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: justhtml
-Version: 3.2.0
+Version: 3.4.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.4.0}/SECURITY.md

@@ -19,6 +19,20 @@
 | 1.x     | :x:                                      |
 | < 1.0   | :x:                                      |
 
+## Threat Model
+
+JustHTML's primary security boundary is **untrusted HTML input**: markup,
+bytes, and HTML-derived values supplied to parsing, sanitization, and
+serialization APIs. The promises below apply when callers use the documented
+safe defaults or a deliberately safe policy.
+
+Library configuration is trusted application code. This includes custom
+sanitization policies, transform specifications and callbacks, selectors,
+glob patterns, CLI flags, and any policy or transform values assembled from
+configuration. Applications that accept those values from untrusted users must
+validate and constrain them before passing them to JustHTML; transform APIs are
+not a sandbox.
+
 ## Security Domains
 
 This section describes the security areas we use when reviewing `justhtml`.

{justhtml-3.2.0 → justhtml-3.4.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.4.0}/docs/bleach-migration.md

@@ -6,20 +6,19 @@ JustHTML’s sanitization and transform pipeline were heavily inspired by Bleach
 
 Bleach has helped a lot of projects ship safer HTML over the years, and a lot of that is thanks to the hard work of [@willkg](https://github.com/willkg) building and maintaining it.
 
-In 2023, Bleach’s maintainer announced that **Bleach is deprecated** (but will continue to receive security updates, new Python version support, and fixes for egregious bugs). See: https://github.com/mozilla/bleach/issues/698
+In June 2026, Bleach’s maintainer [announced Bleach’s final release](https://bluesock.org/~willkg/blog/dev/bleach_6_4_0_final_release.html). The announcement identifies JustHTML as an easy migration path and explicitly recommends swapping Bleach out for it.
 
-This guide covers common migration patterns.
+This guide starts with Bleach's defaults, then builds up to a copyable compatibility wrapper for a gradual migration.
 
-## Real-world migration pattern: add a local wrapper first
+## Start with the defaults
 
-A large application migration often works best in two steps:
+Bleach and JustHTML are both safe by default, but their default policies are intentionally different. Do not replace `bleach.clean(html)` with `JustHTML(html).to_html()` and expect byte-for-byte identical output.
 
-1. Add a small application-local `clean(...)` wrapper that accepts the Bleach-shaped options your codebase already uses.
-2. Migrate call sites from `bleach.clean(...)` / `bleach.linkify(...)` to that wrapper.
+Bleach's default allowlist keeps a small set of formatting tags such as `b`, `em`, `i`, `a`, `code`, and lists. JustHTML's default policy allows a broader set of ordinary document tags and applies its own URL policy.
 
-That keeps most call-site changes mechanical while leaving the security policy in one place.
+The wrapper below reproduces Bleach 6.x's default tags, attributes, and protocols without making Bleach a runtime dependency. It is a compatibility baseline, not a recommended final policy.
 
-Example wrapper:
+## Copyable `clean(...)` compatibility wrapper
 
 ```python
 import re
@@ -40,10 +39,21 @@ URL_LIKE_ATTRS = {
     "ping",
 }
 
+BLEACH_DEFAULT_TAGS = frozenset(
+    {"a", "abbr", "acronym", "b", "blockquote", "code", "em", "i", "li", "ol", "strong", "ul"}
+)
+BLEACH_DEFAULT_ATTRIBUTES = {
+    "a": {"href", "title"},
+    "abbr": {"title"},
+    "acronym": {"title"},
+}
+BLEACH_DEFAULT_PROTOCOLS = frozenset({"http", "https", "mailto"})
+
 
 def build_url_policy(
     allowed_tags: Collection[str],
     allowed_attributes: Mapping[str, Collection[str]],
+    protocols: Collection[str],
 ) -> UrlPolicy:
     rules = {}
 
@@ -52,7 +62,7 @@ def build_url_policy(
         for attr in global_attrs:
             if attr in URL_LIKE_ATTRS:
                 rules[(tag, attr)] = UrlRule(
-                    allowed_schemes={"http", "https", "mailto", "tel"},
+                    allowed_schemes=protocols,
                     allow_relative=True,
                 )
 
@@ -62,7 +72,7 @@ def build_url_policy(
         for attr in attrs:
             if attr in URL_LIKE_ATTRS:
                 rules[(tag, attr)] = UrlRule(
-                    allowed_schemes={"http", "https", "mailto", "tel"},
+                    allowed_schemes=protocols,
                     allow_relative=True,
                 )
     return UrlPolicy(allow_rules=rules)
@@ -71,13 +81,14 @@ def build_url_policy(
 def clean(
     html: str,
     *,
-    tags: Collection[str] = (),
-    attributes: Mapping[str, Collection[str]] | None = None,
+    tags: Collection[str] = BLEACH_DEFAULT_TAGS,
+    attributes: Mapping[str, Collection[str]] = BLEACH_DEFAULT_ATTRIBUTES,
+    protocols: Collection[str] = BLEACH_DEFAULT_PROTOCOLS,
     css_properties: Collection[str] = (),
-    strip: bool = True,
+    strip: bool = False,
     strip_comments: bool = True,
 ) -> str:
-    attrs = dict(attributes or {})
+    attrs = {tag: set(values) for tag, values in attributes.items()}
     disallowed_tag_handling = "unwrap" if strip else "escape"
 
     # Bleach defaults to strip_comments=True. If you use escape mode
@@ -90,7 +101,7 @@ def clean(
         allowed_tags=tags,
         allowed_attributes=attrs,
         allowed_css_properties=css_properties,
-        url_policy=build_url_policy(tags, attrs),
+        url_policy=build_url_policy(tags, attrs, protocols),
         drop_comments=strip_comments,
         disallowed_tag_handling=disallowed_tag_handling,
     )
@@ -109,57 +120,38 @@ def linkify(text: str, *, nofollow: bool = False) -> str:
     ).to_html(pretty=False)
 ```
 
-Treat this as a compatibility shim, not a universal policy. Tighten `build_url_policy(...)` for your application, especially for attributes that load remote resources such as `img[src]`.
+Use the wrapper with Bleach-compatible defaults:
 
-## Mental model differences
-
-- Bleach takes a string and returns a cleaned string.
-- JustHTML parses into a DOM and sanitizes by default at construction time:
-    - `JustHTML(html)` sanitizes by default (`sanitize=True`).
-    - `JustHTML(html, sanitize=False)` disables sanitization (trusted input only).
-
-JustHTML also supports constructor-time **transforms** (a DOM equivalent of Bleach/html5lib filter pipelines): see [Transforms](transforms.md).
+```python
+# Replace existing bleach.clean(user_html) calls with clean(user_html).
+safe_html = clean(user_html)
+```
 
-## Equivalent of `bleach.clean(...)`
+## Customize the wrapper gradually
 
-A typical Bleach call:
+Keep the call shape familiar while making the policy explicit at the call site:
 
 ```python
-import bleach
-
-clean = bleach.clean(
+safe_html = clean(
     user_html,
-    tags=["p", "b", "a"],
-    attributes={"a": ["href"]},
-    protocols=["http", "https"],
+    tags={"p", "b", "a"},
+    attributes={"a": {"href"}},
+    protocols={"http", "https"},
     strip=True,
 )
 ```
 
-In JustHTML you typically configure a `SanitizationPolicy`:
+`fragment=True` inside the wrapper keeps user-generated snippets free of `<html>`, `<head>`, and `<body>` wrappers. For URL rules with host restrictions, proxies, `srcset`, and remote-resource controls, extend the local `build_url_policy(...)` function; see [URL Cleaning](url-cleaning.md).
 
-```python
-from justhtml import JustHTML, SanitizationPolicy, UrlPolicy, UrlRule
-
-policy = SanitizationPolicy(
-    allowed_tags=["p", "b", "a"],
-    allowed_attributes={"*": [], "a": ["href"]},
-    url_policy=UrlPolicy(
-        default_handling="allow",
-        allow_rules={
-            ("a", "href"): UrlRule(allowed_schemes=["http", "https"]),
-        },
-    ),
-)
+## Intentional compatibility differences
 
-doc = JustHTML(user_html, fragment=True, policy=policy)
-clean = doc.to_html()
-```
+The wrapper matches Bleach's ordinary allowlist behavior, but it deliberately does not preserve every historical output detail:
 
-Notes:
+- JustHTML drops the contents of dangerous containers such as `script` and `style`; Bleach with `strip=True` can leave their text content behind.
+- JustHTML normalizes a protocol-relative URL such as `//example.com/x` to `https://example.com/x`; Bleach preserves the original spelling.
+- JustHTML parses into a DOM and sanitizes at construction time. Add `Sanitize(...)` after later DOM edits if the tree needs to become safe again.
 
-- Prefer `fragment=True` for user-generated snippets. That avoids adding `<html>`, `<head>`, and `<body>` tags.
-- JustHTML sanitizes *at construction time* by default. If you need to sanitize again after later DOM edits, add `Sanitize(...)` at the end of your transform pipeline (see [HTML Cleaning](html-cleaning.md)).
+JustHTML also supports constructor-time transforms, which replace Bleach/html5lib filter pipelines; see [Transforms](transforms.md).
 
 ## Bleach filters → JustHTML transforms
 

{justhtml-3.2.0 → justhtml-3.4.0}/docs/cli.md

@@ -124,7 +124,7 @@ justhtml page.html --selector "main" --format text --separator "" --no-strip
 curl -s https://github.com/EmilStenstrom/justhtml/ | justhtml - --selector '.markdown-body' --format markdown | head -n 15
 ```
 
-Output:
+<!-- justhtml: output -->
 
 ```text
 # JustHTML

{justhtml-3.2.0 → justhtml-3.4.0}/docs/correctness.md

@@ -91,7 +91,7 @@ python run_tests.py --suite encoding
 python run_tests.py --suite unit
 ```
 
-Output:
+<!-- justhtml: output -->
 ```
 PASSED: 3464/3464 passed (100.0%)
 ```
@@ -132,7 +132,7 @@ We generate random malformed HTML to find crashes and hangs:
 python benchmarks/fuzz.py -n 3000000
 ```
 
-Output:
+<!-- justhtml: output -->
 ```
 ============================================================
 FUZZING RESULTS: justhtml

{justhtml-3.2.0 → justhtml-3.4.0}/docs/errors.md

@@ -23,6 +23,11 @@ for error in doc.errors:
 `doc.errors` is ordered by source position (line, column), with unknown
 positions appearing last.
 
+At most 1,000 diagnostics are retained by default, including parser,
+sanitizer, and transform findings produced during construction. Set a different
+positive `max_errors` value when constructing `JustHTML` if your application
+needs a different limit.
+
 ## Error Categories
 
 Each error has a `category` field:

{justhtml-3.2.0 → justhtml-3.4.0}/docs/fragments.md

@@ -16,7 +16,7 @@ doc = JustHTML("<tr><td>cell</td></tr>")
 print(doc.to_html(indent_size=4))
 ```
 
-Output:
+<!-- justhtml: output -->
 
 ```html
 <html>
@@ -37,7 +37,7 @@ doc = JustHTML(html, fragment_context=ctx)
 print(doc.to_html(indent_size=4))
 ```
 
-Output:
+<!-- justhtml: output -->
 
 ```html
 <tr>
@@ -64,7 +64,7 @@ print(doc.to_html())
 paragraphs = doc.query("p")
 ```
 
-Output:
+<!-- justhtml: output -->
 
 ```html
 #document-fragment
@@ -143,7 +143,7 @@ doc = JustHTML("<b>not bold</b>", fragment_context=ctx)
 print(doc.to_html())
 ```
 
-Output:
+<!-- justhtml: output -->
 
 ```html
 &lt;b&gt;not bold&lt;/b&gt;
@@ -227,7 +227,7 @@ dirty = '<p>Hello</p><script>alert("xss")</script><b>world</b>'
 print(sanitize_fragment(dirty))
 ```
 
-Output:
+<!-- justhtml: output -->
 
 ```html
 <p>Hello</p><b>world</b>

{justhtml-3.2.0 → justhtml-3.4.0}/docs/html-cleaning.md

@@ -8,78 +8,49 @@ This page focuses on **HTML cleaning**: tags, attributes, and inline styles. For
 
 On this page:
 
-- [DOM vs construction](#important-dom-vs-construction)
 - [Safe-by-default construction](#safe-by-default-construction)
-- [Sanitizing a DOM directly](#sanitizing-a-dom-directly)
-- [Disable sanitization](#disable-sanitization)
 - [Default policy](#default-sanitization-policy)
-- [Inline styles](#inline-styles-optional)
 - [Custom policy](#use-a-custom-sanitization-policy)
+- [Sanitizing a DOM directly](#sanitizing-a-dom-directly)
+- [Inline styles](#inline-styles-optional)
+- [Advanced policy options](#advanced-policy-options)
+- [Disable sanitization](#disable-sanitization)
 - [Reporting issues](#reporting-issues)
 
-## Important: DOM vs construction
-
-The parsed DOM is **sanitized by default** at construction time (`JustHTML(..., sanitize=True)`), and serialization is a pure output step.
-
-If you want to sanitize **after** other transforms or after direct DOM edits, apply the `Sanitize(...)` transform to sanitize the in-memory tree. If your transform list already includes `Sanitize(...)`, that explicit position becomes the sanitize point; later transforms can reintroduce unsafe content.
-
 ## Safe-by-default construction
 
 By default, construction removes all dangerous html:
 
+### HTML output
+
 ```python
 from justhtml import JustHTML
 
 user_html = '<p>Hello <b>world</b> <script>alert(1)</script> <a href="javascript:alert(1)">bad</a> <a href="https://example.com/?a=1&b=2">ok</a></p>'
 doc = JustHTML(user_html, fragment=True)
-
 print(doc.to_html())
-print()
-print(doc.to_markdown())
 ```
 
-Output:
+<!-- justhtml: output -->
 
 ```html
 <p>Hello <b>world</b>  <a>bad</a> <a href="https://example.com/?a=1&amp;b=2">ok</a></p>
-
-Hello **world** [bad] [ok](https://example.com/?a=1&b=2)
-```
-
-## Sanitizing the in-memory DOM
-
-If you will be working with the DOM and want a clean slate to work from, add `Sanitize(...)` to your transform pipeline.
-
-If you want explicit pass boundaries (advanced use), you can group transforms using [`Stage([...])`](transforms.md#advanced-stages).
-
-```python
-from justhtml import JustHTML, Sanitize
-
-user_html = '<p>Hello <b>world</b> <script>alert(1)</script> <a href="javascript:alert(1)">bad</a> <a href="https://example.com/?a=1&b=2">ok</a></p>'
-doc = JustHTML(user_html, fragment=True, transforms=[Sanitize()])
-
-# The DOM is now sanitized in-memory.
-print(doc.to_html(pretty=False))
-# => <p>Hello <b>world</b>  <a>bad</a> <a href="https://example.com/?a=1&amp;b=2">ok</a></p>
 ```
 
-## Disable sanitization
-
-If you want to (dangerously) disable sanitization, because you know that your trusted HTML can't contain malicious code:
+### Markdown output
 
 ```python
 from justhtml import JustHTML
 
-user_html = '<p>Hello <b>world</b> <script>init_page_view_tracker()</script> <a href="javascript:track_pageview()">ok</a></p>'
-doc = JustHTML(user_html, fragment=True, sanitize=False)
-
-print(doc.to_html())
+user_html = '<p>Hello <b>world</b> <script>alert(1)</script> <a href="javascript:alert(1)">bad</a> <a href="https://example.com/?a=1&b=2">ok</a></p>'
+doc = JustHTML(user_html, fragment=True)
+print(doc.to_markdown())
 ```
 
-Output:
+<!-- justhtml: output -->
 
-```html
-<p>Hello <b>world</b> <script>init_page_view_tracker()</script> <a href="javascript:track_pageview()">ok</a></p>
+```markdown
+Hello **world** [bad] [ok](https://example.com/?a=1&b=2)
 ```
 
 ## Default sanitization policy
@@ -114,23 +85,62 @@ Default allowlists:
   - `img`: `src`, `alt`, `title`, `width`, `height`, `loading`, `decoding`
   - `th`/`td`: `colspan`, `rowspan`
 
+## Use a custom sanitization policy
+
+Start with the smallest policy that matches the HTML you want to accept. This makes the allowed output clear to future maintainers.
+
+```python
+from justhtml import JustHTML, SanitizationPolicy, UrlPolicy, UrlRule
+
+policy = SanitizationPolicy(
+    allowed_tags={"p", "strong", "a"},
+    allowed_attributes={"a": {"href"}},
+    url_policy=UrlPolicy(
+        allow_rules={
+            ("a", "href"): UrlRule(allowed_schemes={"https", "mailto"}),
+        }
+    ),
+)
+
+safe_html = JustHTML(user_html, fragment=True, policy=policy).to_html()
+```
+
+The three settings work together:
+
+- `allowed_tags` controls which elements remain.
+- `allowed_attributes` controls which attribute names remain. An omitted tag has no allowed attributes, so you only need to list tags that accept attributes.
+- URL-valued attributes such as `href` also need a `UrlRule`; allowing the attribute name alone is not enough.
+
+For URL schemes, hosts, proxies, `srcset`, and other URL-specific controls, continue with [URL Cleaning](url-cleaning.md).
+
+## Sanitizing the in-memory DOM
+
+The parsed DOM is sanitized by default at construction time (`JustHTML(..., sanitize=True)`), and serialization is a pure output step.
+
+If you want to sanitize after other transforms or after direct DOM edits, add `Sanitize(...)` at the point where the tree should become safe. Later transforms can reintroduce unsafe content. For explicit pass boundaries (advanced use), see [`Stage([...])`](transforms.md#advanced-stages).
+
+```python
+from justhtml import JustHTML, Sanitize
+
+doc = JustHTML(user_html, fragment=True, transforms=[Sanitize()])
+print(doc.to_html(pretty=False))
+```
+
 ## Inline styles (optional)
 
 Inline styles are disabled by default. To allow them you must:
 
-1) Allow the `style` attribute for the relevant tag via `allowed_attributes`, and
-2) Provide a non-empty allowlist via `allowed_css_properties`.
-
-Even then, JustHTML is conservative: it rejects declarations that look like they can load external resources (such as values containing `url(` or `image-set(`), as well as legacy constructs like `expression(`.
+1. Allow the `style` attribute for the relevant tag via `allowed_attributes`.
+2. Provide a non-empty allowlist via `allowed_css_properties`.
 
-To avoid "footgun" policies, you can start from the built-in preset `CSS_PRESET_TEXT`.
+Even then, JustHTML rejects declarations that look like they can load external resources (such as values containing `url(` or `image-set(`), as well as legacy constructs like `expression(`. Start from the conservative `CSS_PRESET_TEXT` preset.
 
 ```python
 from justhtml import CSS_PRESET_TEXT, JustHTML, SanitizationPolicy, UrlPolicy
 
 policy = SanitizationPolicy(
-    allowed_tags=["p"],
-    allowed_attributes={"*": [], "p": ["style"]},
+    allowed_tags={"p"},
+    allowed_attributes={"p": {"style"}},
     url_policy=UrlPolicy(allow_rules={}),
     allowed_css_properties=CSS_PRESET_TEXT | {"width"},
 )
@@ -139,20 +149,9 @@ html = '<p style="color: red; background-image: url(https://evil.test/x); width:
 print(JustHTML(html, policy=policy).to_html())
 ```
 
-Output:
-
-```html
-<p style="color: red">Hi</p>
-
-```
-
-## Use a custom sanitization policy
+## Advanced policy options
 
-You are encouraged to write your own `SanitizationPolicy`, and not rely on the default one. This makes it easier for future developers to understand what's being cleaned, without having to look it up in justhtml's documentation.
-
-When expanding the default policy, prefer adding small, explicit allowlists.
-
-Advanced sanitization pipelines can also tune selector resource limits:
+Selector limits are for trusted pipelines that need to accept unusually large selectors or match budgets:
 
 ```python
 from justhtml import SanitizationPolicy
@@ -165,43 +164,14 @@ policy = SanitizationPolicy(
 )
 ```
 
-Use this only when you trust the selectors and know which limit your workload needs to raise. The defaults are intentionally conservative for untrusted input.
-
-Treat these as a separate security review if you plan to allow them:
+Treat policies that allow active content as a separate security review: `iframe`, `object`, `embed`, `meta`, `link`, `base`, form elements, and their active attributes are preserved when you explicitly allow them.
 
-- `iframe`, `object`, `embed`
-- `meta`, `link`, `base`
-- form elements and submission-related attributes
-
-If you explicitly allow these tags and their active attributes (for example `iframe[src]` or `object[data]`), JustHTML will preserve them according to your policy. That is an explicit opt-in to active embedded content, not something the sanitizer makes safe for you.
+## Disable sanitization
 
-For URL-related risks and controls, see [URL Cleaning](url-cleaning.md).
+Only disable sanitization for HTML you fully trust:
 
 ```python
-from justhtml import JustHTML, SanitizationPolicy, UrlPolicy, UrlRule
-
-user_html = '<p>Hello <b>world</b> <script>alert(1)</script> <a href="javascript:alert(1)">bad</a> <a href="https://example.com/?a=1&b=2">ok</a></p>'
-
-policy = SanitizationPolicy(
-    allowed_tags=["p", "b", "a"],
-    allowed_attributes={"*": [], "a": ["href"]},
-    url_policy=UrlPolicy(
-        default_handling="allow",
-        allow_rules={
-            ("a", "href"): UrlRule(allowed_schemes=["https"]),
-        }
-    ),
-)
-
-doc = JustHTML(user_html, fragment=True)
-doc = JustHTML(user_html, fragment=True, policy=policy)
-print(doc.to_html())
-```
-
-Output:
-
-```html
-<p>Hello <b>world</b>  <a>bad</a> <a href="https://example.com/?a=1&amp;b=2">ok</a></p>
+doc = JustHTML(trusted_html, fragment=True, sanitize=False)
 ```
 
 ## Reporting issues