# onehtml docs, all pages (onehtml 1.0.0)

Every page of https://recursiveai.org/onehtml/docs/ and https://recursiveai.org/onehtml/cookbook/ as markdown, getting started first. Index: https://recursiveai.org/onehtml/llms.txt


<!-- https://recursiveai.org/onehtml/docs/getting-started/ -->

# Getting started with onehtml

Install onehtml for .NET 10, parse an HTML page the way a browser does, query it with CSS selectors, make an edit that leaves every other byte alone, compute the accessibility tree, and check the page against WCAG 2.2 AA with SARIF output.

## Install

onehtml targets `net10.0`, so you need the .NET 10 SDK. The three packages share one version; this guide uses 1.0.0.

```shell
dotnet new console -o OneHtmlStart
cd OneHtmlStart
dotnet add package RecursiveAI.OneHtml --version 1.0.0
dotnet add package RecursiveAI.OneHtml.Accessibility --version 1.0.0
dotnet add package RecursiveAI.OneHtml.Accessibility.Validation --version 1.0.0
```

Install only what you use: `RecursiveAI.OneHtml.Accessibility` brings in `RecursiveAI.OneHtml`, and `RecursiveAI.OneHtml.Accessibility.Validation` brings in both. The libraries use nothing outside the .NET base class library, contain no `unsafe` code, and work with NativeAOT and trimming.

The libraries never read files or the network. You load the bytes and hand them over, as the examples below do. Scripts are kept as inert text, and nothing is laid out or painted.

## The sample page

Every step below runs against `events.html`, a 2,051-byte events page for a made-up library. It has a header with a logo and navigation, two event cards, a newsletter form and a footer. It also has two problems an accessibility check should catch: an image with no `alt` and an icon-only submit button.

```html
<article class="card" data-event-id="114">
  <h2>Story time for ages 3&ndash;5</h2>
  <p>Saturdays at 10:30 in the children&rsquo;s room. <a href="/events/story-time/">Details</a></p>
  <img src="/img/story-time.jpg" width=640 height=360>
</article>
```

The snippets are one program, in order. Put these `using` directives at the top of `Program.cs`:

```csharp
using RecursiveAI.OneHtml;
using RecursiveAI.OneHtml.Editing;
using RecursiveAI.OneHtml.Css;
using RecursiveAI.OneHtml.Accessibility;
using RecursiveAI.OneHtml.Accessibility.Validation;
using RecursiveAI.OneHtml.Accessibility.Validation.Catalogue;
```

## Parse a document

`Document.Parse` takes bytes, a string or a `SourceText`. Give it bytes when you have them: it then picks the encoding the way a browser does (byte order mark, then the `Content-Type` you pass in `ParseOptions`, then the `<meta>` prescan) and records how sure it is.

```csharp
byte[] bytes = File.ReadAllBytes("events.html");
Document doc = Document.Parse(bytes);

Console.WriteLine($"Encoding: {doc.Source.Encoding.Name} ({doc.Source.Confidence})");
Console.WriteLine($"Mode: {doc.Mode}, nodes: {doc.NodeCount}");
```

```text
Encoding: UTF-8 (Certain)
Mode: NoQuirks, nodes: 101
```

Parsing follows the WHATWG HTML standard: the tokenizer, every insertion mode, foster parenting, templates and foreign content. Malformed markup doesn’t throw. It becomes the same tree a browser would build. A `Document` is an immutable snapshot that any number of threads can read at once, and `Node` is a small struct handle into it.

## Query with CSS selectors

`QuerySelector` returns the first match, or a null node (check `IsNull`). `QuerySelectorAll` returns every match in document order. Both take Selectors Level 4, including `:has()`, `:is()`, `:where()` and `:not()` with selector lists.

```csharp
Node title = doc.Root.QuerySelector("title");
Console.WriteLine(title.TextContent);

foreach (Node heading in doc.Root.QuerySelectorAll("article.card > h2"))
{
    Node article = heading.Closest("article");
    Console.WriteLine($"{article.GetAttribute("data-event-id")}: {heading.TextContent}");
}

Node missing = doc.Root.QuerySelector("main img:not([alt])");
Console.WriteLine($"No alt: {missing.GetAttribute("src")}, has width: {missing.HasAttribute("width")}");
```

```text
Events | Harbor Street Library
114: Story time for ages 3–5
115: Repair café
No alt: /img/story-time.jpg, has width: True
```

Character references are already decoded: `&ndash;` reads as `–` and `caf&eacute;` as `café`. `GetAttribute` returns `null` when the attribute is absent and `""` when it is present but empty.

## Make a lossless edit and write it back

`doc.Apply(edits)` takes a list of edits aimed at nodes of the snapshot. Either all of them apply or none do. The output is spliced from the original bytes: only the bytes an edit touches change. The engine re-parses the result and checks that it matches the expected tree before returning it. The old snapshot and its handles stay valid.

```csharp
EditResult result = doc.Apply(new[]
{
    Edit.SetAttribute(missing, "alt", "Children listening to a story"),
});

if (!result.Succeeded)
{
    throw new InvalidOperationException(result.Failure);
}

byte[] output = result.Document!.ToLosslessBytes();
File.WriteAllBytes("events.edited.html", output);

EditedRange range = result.Changes!.Ranges.Single();
Console.WriteLine($"Inserted at byte {range.OldByteRange.Start}: [{range.NewText}]");

int at = range.OldByteRange.Start;
int grew = output.Length - bytes.Length;
bool headSame = bytes.AsSpan(0, at).SequenceEqual(output.AsSpan(0, at));
bool tailSame = bytes.AsSpan(range.OldByteRange.End).SequenceEqual(output.AsSpan(range.OldByteRange.End + grew));
Console.WriteLine($"{bytes.Length} -> {output.Length} bytes; before the edit identical: {headSame}, after: {tailSame}");
```

```text
Inserted at byte 1086: [ alt="Children listening to a story"]
2051 -> 2087 bytes; before the edit identical: True, after: True
```

The unquoted `width=640 height=360`, the `&ndash;` reference, the comments and the indentation all stay as they were. `diff` shows one changed line:

```text
33c33
<       <img src="/img/story-time.jpg" width=640 height=360>
---
>       <img src="/img/story-time.jpg" width=640 height=360 alt="Children listening to a story">
```

The other operations are `RemoveAttribute`, `ReplaceText`, `InsertBefore`, `InsertAfter`, `Prepend`, `Append`, `Wrap`, `Unwrap`, `Replace`, `Remove`, `SetStyle` and `RemoveStyle`. [Edit HTML without reformatting it](https://recursiveai.org/onehtml/cookbook/edit-html-csharp-lossless/) shows several at once.

## Compute the accessibility tree

The accessibility tree is what a browser gives to screen readers: a role, an accessible name and states for each node that matters. `AccessibilityTree.Build` computes it from the document and its cascade (WAI-ARIA 1.2, HTML-AAM and AccName 1.2), using Chromium’s choices where the specifications leave room. No browser is involved.

```csharp
DocumentStyles styles = DocumentStyles.Create(doc);
AccessibilityTree tree = AccessibilityTree.Build(doc, styles);

string[] interesting = { "heading", "link", "button", "image", "textbox" };
foreach (AxNode node in tree.Nodes.Where(n => !n.IsIgnored && interesting.Contains(n.Role)))
{
    Console.WriteLine($"{node.Role,-8} \"{node.Name.Value}\" from {node.Name.Source}");
}
```

```text
link     "Harbor Street Library" from Contents
image    "Harbor Street Library" from NativeAttribute
link     "Books" from Contents
link     "Events" from Contents
link     "Visit" from Contents
heading  "Upcoming events" from Contents
heading  "Story time for ages 3–5" from Contents
link     "Details" from Contents
image    "" from None
heading  "Repair café" from Contents
link     "Partner site" from Contents
image    "Volunteers at a workbench fixing a lamp" from NativeAttribute
textbox  "Your email" from Placeholder
button   "" from None
link     "hello@example.org" from Contents
button   "Back to top" from Contents
```

This tree was built from the original `doc`, so the story-time image still has no name. The submit button has none either: its only content is an `aria-hidden` icon. The logo link takes its name from the `alt` of the image inside it. The email field is named only by its placeholder.

## Check the page against WCAG 2.2 AA

`Checker` runs one rule catalogue that covers axe-core’s WCAG and best-practice rules and every W3C-approved ACT rule. Each rule is labeled with the WCAG criteria it checks. A profile picks the rules for a standard: `Wcag20AA`, `Wcag21AA`, `Wcag22AA`, or `All`, which adds best practices.

```csharp
var options = new CheckOptions { Profile = ValidationProfile.Wcag22AA };
CheckReport report = new Checker().Check(doc, options);

foreach (RuleResult failure in report.WithOutcome(Outcome.Failed))
{
    Console.WriteLine($"{failure.RuleId} at {failure.Locator}: {failure.Message}");
}
Console.WriteLine($"Failed {report.Count(Outcome.Failed)}, needs review {report.Count(Outcome.NeedsReview)}, " +
                  $"needs render {report.Count(Outcome.NeedsRender)}, passed {report.Count(Outcome.Passed)}");

string sarif = report.ToSarifJson(new ExportOptions { Url = "events.html", Indented = true });
File.WriteAllText("events.sarif", sarif);
```

```text
button-name at form > button: The button has no accessible name.
image-alt at #content > article:nth-of-type(1) > img: The image has no accessible name.
Failed 2, needs review 18, needs render 10, passed 62
```

Every result has one of five outcomes:

- `Failed`, `Passed` and `Inapplicable` are decided.
- `NeedsReview` means markup and CSS can’t settle it, for example whether a heading describes its section. A person has to look.
- `NeedsRender` means the rule needs layout captured from a browser. Here all 10 are `target-size`, which needs the border boxes of each target and its neighbors. You can supply those as `RenderedFacts` (see [Rendered facts](https://recursiveai.org/onehtml/docs/rendered-facts/)), and `FactsMissing` on each result lists what is needed.

The checker doesn’t replace human review. It reports what it can’t decide instead of guessing.

`events.sarif` is SARIF 2.1.0. Each failure has its rule, its line and column, its byte offset and a source snippet. The rule’s entry in the file lists the WCAG criteria it checks.


```json
{
  "ruleId": "button-name",
  "ruleIndex": 28,
  "kind": "fail",
  "level": "error",
  "rank": 90,
  "message": {
    "text": "The button has no accessible name."
  },
  "locations": [
    {
      "physicalLocation": {
        "artifactLocation": {
          "uri": "events.html",
          "index": 0
        },
        "region": {
          "startLine": 45,
          "startColumn": 7,
          "endLine": 45,
          "endColumn": 29,
          "byteOffset": 1584,
          "byteLength": 22,
          "snippet": {
            "text": "<button type=\"submit\">"
          }
        }
      }
    }
  ]
}
```

That is an excerpt of one result. The full result also has a logical location, a fingerprint and properties such as `outcome` and `locator`. Review results have `kind: "review"` and `level: "none"`, so filter on `kind` as well as `level`. [SARIF export](https://recursiveai.org/onehtml/docs/sarif/) gives the full mapping.

## The packages

| Package | What it gives you |
|---|---|
| `RecursiveAI.OneHtml` | The WHATWG HTML parser with encoding sniffing, the DOM as immutable snapshots with a byte-level source map, Selectors Level 4, unique locators, a CSS parser, the cascade under a `StyleContext` (viewport, media features, focus, hover), and lossless editing of HTML and CSS with a JSON edit format you can save and replay. |
| `RecursiveAI.OneHtml.Accessibility` | The accessibility tree (WAI-ARIA 1.2, HTML-AAM, AccName 1.2, Core-AAM, SVG-AAM) with each role, name and hidden state traced to its source, incremental updates after edits, a reading view, navigation lists, tree diffs, export in Chrome’s AX-tree shape, and `RenderedFacts` from a Chrome `DOMSnapshot` you supply. |
| `RecursiveAI.OneHtml.Accessibility.Validation` | The rule catalogue labeled by WCAG version, level and criterion; WCAG 2.0, 2.1 and 2.2 AA profiles; incremental re-checks after an edit; suggested edits where exactly one fix is correct; and native JSON, axe-compatible JSON and SARIF 2.1.0 output. |

All three are licensed MIT OR Apache-2.0, at your option.

## Where next

Articles: [Parse HTML in C#](https://recursiveai.org/onehtml/articles/parse-html-csharp/), [Migrate from HtmlAgilityPack](https://recursiveai.org/onehtml/articles/migrate-from-htmlagilitypack/), [HtmlAgilityPack vs AngleSharp](https://recursiveai.org/onehtml/articles/htmlagilitypack-vs-anglesharp/).

- Recipes: [parse HTML from a string, file or stream](https://recursiveai.org/onehtml/cookbook/parse-html/), [CSS selectors](https://recursiveai.org/onehtml/cookbook/css-selectors/), [extract visible text](https://recursiveai.org/onehtml/cookbook/extract-visible-text/), [compute styles](https://recursiveai.org/onehtml/cookbook/computed-style-csharp/), [WCAG checks in CI with SARIF](https://recursiveai.org/onehtml/cookbook/wcag-checks-ci-sarif/) and [apply suggested fixes](https://recursiveai.org/onehtml/cookbook/apply-suggested-fixes/).
- How editing works, including fallback when a splice would change how the page parses: [Editing](https://recursiveai.org/onehtml/docs/editing/).
- The selector support and its known gaps: [Selectors](https://recursiveai.org/onehtml/docs/selectors/).
- The cascade and computed values: [Cascade](https://recursiveai.org/onehtml/docs/cascade/).
- How the tree is built and where Chromium’s choices are used: [Accessibility tree](https://recursiveai.org/onehtml/docs/accessibility-tree/) and [Chromium profile](https://recursiveai.org/onehtml/docs/accessibility-chromium-profile/).
- Rule selection, private rules and re-checking: [The checker](https://recursiveai.org/onehtml/docs/checker/). Coverage per WCAG criterion: [Coverage](https://recursiveai.org/onehtml/docs/coverage/).

Guides: [Web scraping in C#](https://recursiveai.org/onehtml/articles/web-scraping-csharp/) and [CSS selectors in C#](https://recursiveai.org/onehtml/articles/css-selectors-csharp/).


<!-- https://recursiveai.org/onehtml/docs/editing/ -->

# Editing HTML

Normative behaviour of `Document.Apply` and `DocumentEditor` in `RecursiveAI.OneHtml`. A port must reproduce it from this text. The saved-edit JSON and replay are in `edit-format.md`; stylesheet edits are at the end of this file.

## Contract

- `doc.Apply(edits)` returns an `EditResult`: either a new `Document` and a `ChangeSet`, or a failure with a reason per edit. **All edits apply or none do.** The old snapshot and every handle into it are untouched.
- Edit targets are `Node` handles into the snapshot being edited. Edits in one transaction all refer to that snapshot, and are applied in order; an edit may target a node created by an earlier edit of the same transaction.
- An empty transaction returns bytes identical to the input.
- Each `EditOutcome` is `Applied`, `Invalid` (the operation does not fit the target or its input is unusable: `unwrap` on a text node, an edit to a synthesized `selectedcontent` clone, NUL in text), `Failed` (the result cannot be expressed in HTML: no enclosing region re-parses to the expected tree), or `NotAttempted` (an earlier edit stopped the transaction). A no-op such as removing an absent attribute is `Applied`.
- Limits, checked before the work they guard: `MaxEdits` (100,000), `MaxInsertedLength` (16 MiB of inserted markup and text), `MaxVerifications` (64 re-parses in one-at-a-time fallback; each re-parse covers the whole document, so a hopeless transaction on a large page must not climb the ladder for long). Exceeding one fails the transaction cleanly: nothing is applied, and the edit being widened is `Failed` with the reason "the output was re-parsed N times without matching".

## Operations

| Operation | Notes |
|---|---|
| `SetAttribute(element, name, value)` | Replaces the value, or appends the attribute. Name matching is ASCII case-insensitive for HTML elements, exact for foreign-element adjusted names. |
| `RemoveAttribute(element, name)` | No-op (applied, no range) when absent. |
| `ReplaceText(target, text)` | On a text node: its data. On an element: all its children become one text node (none for empty text). Escaped for the context: raw text and RCDATA elements get their content verbatim or character-reference escaped as the element's parsing mode requires; foreign content escapes as normal data. |
| `InsertBefore`, `InsertAfter`, `Prepend`, `Append` | `html` is parsed with the fragment algorithm in the target's context (the parent's, for before/after). |
| `Wrap(node, html, count)` | `html` must parse to one element. The `count` contiguous siblings from `node` move inside it, **after the wrapper's own children**. |
| `Unwrap(element)` | Children take its place. A text, comment or doctype target is `Invalid`, as is an element whose parent is the document, and a `template` element. |
| `Replace(node, html)`, `Remove(node)` | |
| `SetStyle(element, property, value, important)`, `RemoveStyle(element, property)` | Edit the `style=""` attribute using CSS Syntax declaration ranges. `!important` is kept when the declaration has it and `important` is not given. |

A `template` target means its content fragment: children are inserted into, and read from, the template contents.

## How the output is built

1. The edits run against a working copy of the arena columns, in order. Each edit marks a **region** dirty: an element's attribute list, an element's child list, or a single text node.
2. Each dirty region becomes a **splice** of the original text. Bytes outside splices are copied as they are, so they are identical to the input by construction. A region that would be rewritten gets the smallest range that covers the edit: one attribute value, one attribute, the attribute list, the child range.
3. The spliced text is encoded in the **document's encoding**. Editing a `<meta charset>` does not change the encoding used. A character the encoding cannot represent is written as a hexadecimal character reference (`&#xHHHH;`) in attribute values and data; in raw text, where references are not decoded, such a character makes the edit `Invalid`. `replacement` and other encodings with no encoder are rejected. ISO-2022-JP is edited only where the splice sits in ASCII state; otherwise the edit falls back or fails.
4. The output is parsed again. The result must equal the working tree (`TreeComparer`: kinds, names, namespaces, attributes, text, in order). `selectedcontent` children are not compared, since they are clones of the selected option. **The returned snapshot is that re-parse**, so its source map is exact for the output bytes. A mismatch is never returned as output; it triggers fallback.

## Writing rules

- **Escaping:** `&` and `<`, `>` (and NBSP as `&nbsp;`, always a reference) in data; `&` and the quote character, and NBSP, in attribute values. NUL and lone surrogates are rejected (`Invalid`). CR is written as `&#13;` so it survives newline normalisation. Raw text and script content is written unescaped (HTML 13.3); content that would not re-parse to the same text, such as one containing its own end tag, fails the re-parse check (`Failed`). A leading line feed in `pre`, `listing` and `textarea` content is protected with an extra line feed.
- **Local style** (`LocalStyle`), inferred from a bounded sample (the first 5,000 elements) and copied into new markup: attribute quote character (single only when more frequent than double), tag-name case and attribute-name case (each upper or lower), void-element form (`<br>`, `<br/>`, `<br />`), the newline sequence, newline (CRLF or LF) and indentation. Inserted markup is parsed first, then serialized by `MarkupWriter` in this style; attributes keep the author's order and name case.
- **Indentation (line mode):** when the target sits on its own line (only whitespace between the previous line break and its start tag, and a line break after it), inserted siblings are placed on their own lines with the target's indentation, and prepend/append use the child indentation inferred from the existing children. This adds whitespace text nodes to the tree; they are listed in `ChangeSet.Added`. For `prepend`, the new element goes after the element's leading whitespace text. Otherwise (inline context) nothing is added.
- Void elements and elements with no end tag in the source are not given end tags unless the markup requires them.
- `style=""` edits splice only the declaration when the attribute is quoted and its value is verbatim (no references); otherwise the whole value is replaced.

## Fallback

A splice cannot be used when the edited node, or something it affects, is not where the source says: parser-inserted (`implied` tbody/head/body), displaced (foster parenting, adoption agency), cloned, or when the new bytes would change how surrounding markup parses (a `<p>` closed by an inserted block, an inserted `<tr>` in a table).

The engine first tries the whole transaction with fine splices. If the re-parse differs, the edits are re-applied one at a time and each failing region is **widened to its 1st, 2nd, … enclosing element that has bytes of its own**: the region's range becomes that element's children range, re-serialized from the working tree. The first level whose output re-parses to the expected tree wins. If none does before the document root, the edit is `Failed` (the document root is never rewritten). Every widened range is reported: `EditResult.Fallbacks` has the edit index, range, level and reason, and `EditedRange.FallbackLevel` is greater than zero. Fallback output is canonical serialization of the subtree, so bytes inside a fallback range are not preserved; bytes outside it are.

Synthesized `selectedcontent` clones are never editable. Edit the selected `option` instead.

## Change set

- `Added`: nodes in the new snapshot that did not exist (including whitespace nodes added by line mode). `Removed`: nodes of the old snapshot that are gone. `Changed`: `NodeChange(Node, Old, Changes)` where `Changes` flags `Attributes`, `Data` (text characters), `Children` (child list changed) and `Parent` (moved to another parent); `Node` refers to the new snapshot and `Old` to the old one.
- `ChangeSet.MapToNew(oldNode)` maps an old handle to its counterpart in the new snapshot (the null node if removed; `ArgumentException` for a node of another snapshot).
- `Ranges`: one `EditedRange` per rewritten region, with the old and new ranges in text units and bytes, the new bytes, the indexes of the edits that produced it, and its fallback level. Ranges are sorted and do not overlap. This is the audit diff: replace `OldByteRange` of the input with `NewBytes`, and the output follows.
- Because the snapshot is a re-parse, node identity across snapshots is established by the `MapToNew` correspondence computed from the working tree, not by index.

## Cost

One edit costs about one parse of the document plus about 1 ms (the verification re-parse dominates; the column copy does not). On a 35,011-node page: parse 4.6 ms, one attribute edit 5.8 ms (12.4 MB allocated), 100 attribute edits in one transaction 7.2 ms. Reads on an old snapshot, on a fresh parse and on an edited snapshot cost the same.

## Cost of a stylesheet edit

One edit on a 1,000-rule, 73 KB sheet (parse 0.52 ms, 1.6 MB): `setDeclaration` 2.85 ms / 7.5 MB before the narrow check (5.4 parses of time, 4.7 of allocation), 0.88 ms / 2.7 MB after (1.7 and 1.7). What remains is the parse that produces the new sheet snapshot and the change set's pass over the sheet's rules. An edit set spread over the whole sheet (50 declarations across 1,000 rules) has a window as wide as the sheet and costs what it did.

## Restyle after an edit

To get the styles of the edited document, call `styles.Restyle(result)` with the `EditResult` or `BatchResult`; see `cascade.md`.

## Statuses

`EditStatus` also has `Stale` (a saved target is gone or no longer looks like it did) and `Ambiguous` (a saved target matches several places). Only replay produces them; see `edit-format.md`.

## Stylesheet edits

`SheetEdit` operations: `SetDeclaration`, `RemoveDeclaration`, `InsertRule` (before or after a rule, or at the end of a stylesheet or of a rule's block), `RemoveRule`, `ReplaceRule`. Targets are rules of a specific `Stylesheet` snapshot. `Stylesheet.Apply(edits)` edits a stylesheet as text; `EditBatch` applies document edits and stylesheet edits together, all or nothing, to `<style>` elements (`InlineStylesheets.Of(doc)`, named `inline:<n>`), to supplied `LinkedStylesheet`s (named by URL, written back in the sheet's own encoding) and to loose snapshots.

- **Splice only what changed.** Every edit becomes a local replacement of source text. For a `<style>` element only the stretches that change are spliced into the document, so the document's change set shows those text stretches. For a linked sheet the new bytes are the old bytes with the same stretches replaced. All edits of a transaction refer to the original snapshot and are placed by original position; list order decides only the order among edits landing at the same offset: appended declarations, then insertions after a rule, insertions before a rule, then insertions at the end of a block.
- **Conflicts.** Two edits that change the same bytes, or an insertion strictly inside a replaced stretch, make the transaction `Invalid`. Pure deletions that touch or overlap merge. A later edit that contradicts an earlier one on the same property is resolved by the expected rule model and written through the fallback below.
- **Local format.** New text copies the sheet: the newline sequence (documents and sheets are decoded with newlines normalized to line feed, and the original convention is restored on writing), the indentation unit and the indentation of the line the neighbour starts on, the text before and after a declaration's colon and before `!important`, whether the last declaration of a block ends in a semicolon, and the white space between adjacent rules (taken from the pair around the reference rule, then any pair in the container, then any pair at the top level). With no evidence the defaults are: one line feed between rules, two spaces of indentation, `: ` after a property, a semicolon after the last declaration. Removing an item removes the white space that separated it from its neighbour (after it, or before it for the last item of a block); comments between rules stay.
- **Inserted CSS** must parse as exactly one rule (CSS Syntax 3 §5.3 "consume a rule"); leading and trailing white space is dropped, a block-less at-rule gets its semicolon, and later lines are re-indented. An insertion at the end of a stylesheet whose last item is an incomplete prelude cannot be written and is `Failed`.
- **Verification.** The edited text is parsed again and its rule events (rule kind, name, normalized prelude, declarations with normalized values and importance, in order) must equal the events derived from the original tree and the edits. The expected events never come from the new text.
  - **Narrow check first.** The check covers a stretch of whole top-level rules: the rules the edits touch, plus one on each side, to the end of the sheet when that is nearer. Only that stretch of the new text is parsed, and only its expected events are built. This is sound because a rule list is parsed rule by rule from any rule boundary: the text before the stretch is unchanged and its rules ended at their own delimiters in the original parse; the stretch ends at the end of the sheet or after an untouched rule that ended at its delimiter. When the stretch alone gives the expected rules, the whole sheet does.
  - **Whole-sheet check as the fallback.** A narrow mismatch proves nothing, so the whole new text is parsed and compared to the whole expected list; that result decides. The same happens when the new text is longer than the token or input limit, or when the pieces do not lie inside the stretch. `EditOptions.VerifyWholeStylesheet` skips the narrow check; the two give the same output.
- **Fallback.** If they differ, the rule containing the edit is rewritten from the expected events; if that still differs, the next enclosing rule is rewritten, up to the stylesheet's top level. Each rewrite is reported in the `StylesheetChangeSet.Ranges` with its level (0 is a local splice).
- **Limits.** The `EditOptions` limits apply to the whole batch: the count of edits, the inserted length, and the number of verification parses.
- **Change set.** `StylesheetChangeSet` lists rules `Added`, `Removed` and `Changed` (new-snapshot nodes for added and changed, old-snapshot nodes for removed) and the rewritten ranges, each with old and new range, the edits that produced it and its fallback level. A cascade consumer restyles the elements matched by the rules in the change set. An edit of an embedded sheet is also in the document's change set as a text change.
- **Linked sheets.** Unencodable characters in the target encoding make the edit `Failed`; the byte order mark is kept.


<!-- https://recursiveai.org/onehtml/docs/edit-format/ -->

# Edit format, version 1

The saved form of edits: a JSON envelope that names what to change durably enough to replay on another copy of the page or stylesheet, plus the replay rules. It is language-neutral; a port must read and write the same JSON and give the same replay outcomes from this text. The in-memory operations and how HTML and CSS bytes are written are in `editing.md`. Locators and fingerprints are in `locators.md`.

## Model

- An **edit** is one operation on one target. A **transaction** is an ordered list of edits applied together: all apply or none does, and the caller gets a reason per edit.
- In memory, targets are handles into a specific snapshot. A saved edit instead carries a **durable target** (below) that replay resolves against whatever document it is given.
- Markup an edit inserts is an HTML fragment parsed in the target's context, and inserted CSS is parsed as one rule; neither is built by string concatenation.
- Each edit carries an opaque `meta` value. The library stores and returns it and never reads it.
- Replay never guesses. An edit whose target cannot be identified with certainty is reported, and then nothing is applied.

## Envelope

```json
{
  "format": "onehtml-edits",
  "version": 1,
  "document": { "url": "https://example.test/", "sha256": "…" },
  "edits": [
    {
      "op": "setAttribute",
      "target": { "locator": "…", "fingerprint": { }, "anchor": { } },
      "name": "title",
      "value": "Campus map",
      "meta": { "criterion": "4.1.2" }
    }
  ]
}
```

- `format` must be `"onehtml-edits"` and `version` the number `1`; anything else is rejected. A new version is introduced only for changes that alter meaning.
- `document` is informative (what the edits were made against); `sha256` is the hex SHA-256 of the document's bytes when it had any. Replay does not use it.
- **Reading:** unknown members are ignored at every level, duplicate members keep the last value, a UTF-8 byte order mark is skipped, and text after the top-level value is an error. Members of `edits` that are not objects are errors. An edit with no `op` is accepted by the reader and reported `invalid` at replay.
- **Writing:** members come in the fixed order shown in this document, compact by default, strings escaped only as RFC 8259 requires plus the C0 controls (non-ASCII text, `<`, `>`, `&` and `'` are written as they are, as UTF-8); numbers are integers except inside `meta`. The same envelope always writes the same bytes.
- **`meta`** is any JSON value. It is stored as compact JSON text (re-written token by token, so whitespace is not preserved) and written back at the same place. `null` means absent.

## Operations

| `op` | Target | Other members |
|---|---|---|
| `setAttribute` | element | `name`, `value` |
| `removeAttribute` | element | `name` |
| `replaceText` | text node, or element (all its children become one text node) | `text` |
| `insertBefore`, `insertAfter` | node | `html` |
| `prepend`, `append` | element | `html` |
| `wrap` | node, or `count` contiguous siblings starting at it (default 1) | `html` (one element), `count` |
| `unwrap` | element | |
| `replace` | node | `html` |
| `remove` | node | |
| `setStyle`, `removeStyle` | element (`style=""`) | `property`, `value`, `important` |
| `setDeclaration` | rule | `property`, `value`, `important` |
| `removeDeclaration` | rule | `property` |
| `insertRule` | see below | `css` |
| `removeRule` | rule | |
| `replaceRule` | rule | `css` |

`setDeclaration` replaces the value of the rule's last declaration of that property, or appends one; `removeDeclaration` removes every declaration of the property and is applied (changing nothing) when there is none. The placement of `replaceText` on an element, of `wrap`, and of insertions inside `template` elements is as in `editing.md`.

**`insertRule`** places a rule with exactly one of these members, whose value is a rule target:
- `"before": <rule target>` and `"after": <rule target>`: next to that rule.
- `"end": <rule target>`: as the last item of that rule's block.
- `"end": true`: at the end of the stylesheet named by the member `sheet`.

Stylesheet edits name their sheet in the target's `sheet` member (and in `sheet` for `"end": true`): `inline:<n>` for the n-th `<style>` element, counting HTML-namespace `style` elements from 0 in tree order and leaving out `template` contents, or the URL the caller supplied for a linked sheet.

## Targets

An element target:

```json
{
  "locator": "nav#main-nav > ul > li:nth-child(3) > a",
  "fingerprint": {
    "tag": "a",
    "attrs": { "class": "nav-link", "href": "/calendar" },
    "text": "sha256:9f2c…",
    "path": "sha256:41ab…"
  },
  "anchor": { "start": 18234, "end": 18301, "bytes": "sha256:c07e…" }
}
```

- **`locator`:** a selector unique in the document it was generated from. It prefers `id`, `data-*`, `name`, landmark and ARIA attributes and falls back to the shortest unique structural path. A locator is *standalone* when it is a single compound selector (no combinator): it names the element by itself rather than by position.
- **`fingerprint`:** `tag`; `attrs`, the key attributes present (`class` without hash-like names, `href`, `id` unless hash-like, `name`, `role`, `src`, `type`), sorted by name; `text`, `sha256:` and the hex SHA-256 of the whitespace-normalized text content; `path`, `sha256:` and the hex SHA-256 of the position path (`tag[k]/…` from the root, k the 1-based position among element siblings).
- **`anchor`:** the source range of the element's start tag through its end (`start`, `end`, in bytes of the original input, or in text offsets when the document was parsed from a string) and `bytes`, `sha256:` and the hash of those bytes.

**Text and comment targets** have `"kind": "text"` or `"kind": "comment"`, a `parent` (an element target), an `index` (the position among the parent's child nodes) and `fingerprint.text` (the hash of the node's data after whitespace normalization).

**Rule targets** have `"kind": "rule"` and:
- `sheet`: the sheet name (above).
- `selector`: the rule's prelude with runs of white space collapsed to one space. For an at-rule it is `@name prelude` with the name lower-cased.
- `atRules`: the `selector` values of the enclosing rules, outermost first. Nested style rules count as enclosing rules.
- `index`: the 0-based position of the rule among all rules of the sheet with the same `selector` and the same `atRules`, in document order.
- `fingerprint.declarations`: `sha256:` and the hash of the rule's own declarations (names lower-cased except custom properties, values whitespace-normalized, importance), in order.

## Replay

Every edit's target is resolved against the document as it is now. Resolution:

1. **Anchor.** If the target has an anchor and exactly one node of the right kind sits at exactly that range with the same tag and bytes hashing to `bytes`, that node is the candidate. If the locator also matches exactly one *different* node, the edit is `stale` (the page changed in a way the anchor cannot see). If the locator matches nothing or several, the anchor wins.
2. **Locator.** Otherwise the locator must match exactly one node: none gives `stale`, several give `ambiguous`.
3. **Fingerprint.** `tag` and `attrs` must be equal and `text` equal after normalization, or the edit is `stale`. `path` is advisory when the locator is standalone; for any other locator a path mismatch makes the edit `stale`, because a positional locator selects whatever now sits at that position. A fingerprint is required unless the anchor resolved the target; a target with neither is `invalid`.
4. **Text and comment targets** resolve their `parent` as above, then take the child at `index`, which must be of the right kind and have the fingerprinted text.
5. **Rule targets** find the sheet by name (a missing sheet is `stale`), then the rules with equal `selector` and `atRules`. With an `index`, the rule at that position must exist and its declarations hash must match, else `stale`; without one, one candidate resolves and several are `ambiguous`.

Outcomes per edit: `applied`; `stale` (target gone or no longer the same); `ambiguous` (several candidates); `invalid` (the operation does not fit the target, the operation is unknown, the member it needs is missing); `failed` (the result cannot be written losslessly); `notAttempted` (this edit resolved, but another edit did not, so nothing was applied). A transaction with any outcome other than `applied` applies nothing.

Two byte-identical copies of an element cannot be told apart by anything this format records. If the anchor's bytes hold at the saved position, replay applies there even when an identical copy was inserted nearby; that is the same element as far as the format can know. A target whose anchor no longer holds and whose locator matches the copies is `ambiguous`.

## Limits

The reader checks these before building anything and rejects with an error that names the limit; the caller may pass others. Defaults: input 32 MiB; nesting depth 32 (the reader keeps an explicit counter and never recurses on depth); 100,000 edits; any string 16 MiB; `meta` 64 KiB per edit and 256 times that in total; 64 attributes per fingerprint; 64 `atRules` per target.

## Versioning and determinism

Version 1 is described here. A reader of version 1 ignores members it does not know; a change that alters the meaning of an existing member is a new version. Writing is deterministic: the same edits give the same bytes on every platform.


<!-- https://recursiveai.org/onehtml/docs/selectors/ -->

# Selectors

Normative behaviour of `RecursiveAI.OneHtml.Selectors` and the `Node` query members. The grammar and matching rules are
those of Selectors Level 4 (with the HTML Standard section 4.16 for the HTML pseudo-classes and DOM for the query
methods); this file records what those texts leave open or what this library adds.

## Parsing

- Input is a string or a CSS Syntax component-value list (so `@supports selector()` can reuse it). Parsing never
  throws from `TryParse`/`IsValid`; `Parse` throws `SelectorSyntaxException`.
- `:is()` and `:where()` take **forgiving** lists: an invalid item is dropped and never matches. The dropped text is kept
  (serialized) so the list serializes stably. `IsValidComplexSelector` (the `selector()` test) is false when anything was
  dropped. `:not()`, `:has()` and top-level lists are not forgiving.
- A `[` or `(` still open at the end of input is closed there, as CSS Syntax says.
- Serialization follows CSSOM. Identifiers also escape non-ASCII code points that are not name code points.
- Namespaces: `SelectorParseOptions.Namespaces` maps prefixes to namespace URIs; an undeclared prefix is a syntax error;
  without a map a named prefix is an error; `*|x` and `|x` are accepted. A map entry for the empty prefix is the default namespace for unprefixed type selectors.
- Pseudo-elements are parsed and reported but never match an element. After `::part()` only state and user-action
  pseudo-classes are accepted; nothing after `::slotted()`; a second pseudo-element only after `::part()`/`::slotted()`.
  `:heading(<integer>#)` is parsed.
- The column combinator `||` parses and never matches.
- Limits, checked while parsing and before allocating: 65,536 characters; nesting of `:is/:where/:not/:has/:nth-… of`
  16; 128 compounds per complex selector; 4,096 complex selectors per list; 16,384 simple selectors. Exceeding one
  throws `SelectorLimitExceededException` (`TryParse` returns false). Parsing uses an explicit stack, not recursion.

## Specificity

Per Selectors 4 §17: `:is/:not/:has` take the most specific argument, `:nth-child(… of S)` adds the most specific `S`
to a pseudo-class, `:where` is zero, pseudo-elements count in C.

## Matching

- Right to left against a compiled list. Each list reports its rightmost-compound keys (id, class, tag) and its
  dependencies (`SelectorDependencies`: ancestor, sibling, `:has`, state) for the cascade to bucket and invalidate.
- No work is quadratic in the document: a failure memo starts after 64 backtracking steps, `:has()` marks are computed
  in bulk, `of S` positions are cached per snapshot, and `:is()`/`:where()`/`:not()` answers are kept per (selector,
  element) once evaluations nest, in the cascade at once and in `Matches`, `QuerySelector(All)` and `Closest` after a
  few nested evaluations (up to 2M entries), so nested forms cost their size, not depth to the nesting. Deep trees (thousands of levels) use no recursion.
- Names: HTML elements in HTML documents match type selectors and attribute names ASCII-case-insensitively; the HTML
  list of case-insensitive attribute values (`type`, `lang`, …) is honoured. Class and id compare
  case-insensitively in quirks mode.
- `:scope` is the `SelectorMatchOptions.Scope` node, else the document element for queries on the document and the
  element itself for queries on an element.
- `:defined` matches every element that is not a custom element (no script runs, so custom elements are never defined).
- `:link`/`:any-link`: `a` and `area` with an `href`. `:visited`, `:local-link`, `:autofill`, `:popover-open`, `:modal`
  never match.
- `:lang()` uses the nearest `lang` (or `xml:lang` in foreign content) and extended filtering; `:lang("")` matches an
  element whose language is the empty string. `:dir()` follows `dir`, with `auto` read from the first strong character
  and otherwise inheriting; it is an approximation of the full bidi algorithm.
- Dynamic pseudo-classes (`:hover`, `:focus`, `:focus-visible`, `:focus-within`, `:active`, `:target`,
  `:target-within`) read `SelectorMatchOptions.State` (`InteractionState`); with none, they match nothing. `:target`
  works only for the connected document.

### Form and state pseudo-classes from attributes

`:checked`, `:disabled`/`:enabled` (including the fieldset and `legend` rule), `:required`/`:optional`,
`:read-only`/`:read-write` (HTML-namespace elements only), `:placeholder-shown`, `:default`, `:indeterminate`, `:open`,
`:in-range`/`:out-of-range` follow the HTML Standard from attributes alone.

`:valid`/`:invalid` are decided where static: `required`, `email`, `url` (absolute URL parse), `pattern` (the BCL
ECMAScript-mode regex with a 50 ms timeout; a pattern that does not compile, is over 4,096 characters or times out is ignored, as an invalid pattern is), number/range/date-time `min`/`max`, and
number `step`. There is no dirty flag and no custom validity, so script-set state is invisible.

## Query members

`QuerySelector`, `QuerySelectorAll`, `Matches`, `Closest`, `GetElementsByTagName`, `GetElementsByClassName` are on `Node`.
Navigation and matching against a compiled list allocate nothing; `QuerySelectorAll` into a caller list allocates only
that list. `Children` returns element children (W3C); `ChildNodes` returns all children. Indexes (ids, sibling
positions, form owners) are built on first use per snapshot and are safe to share between threads.

## Conformance (web-platform-tests, pinned commit in the notices file)

| Directory | Pass | Known failure | N/A |
|---|---|---|---|
| `dom/nodes` `selectors.js` (document, element, detached element, fragment contexts; query, queryAll, matches, invalid) | 2140 | 0 | 20 |
| `dom/nodes/Element-closest.html` | 29 | 0 | 0 |
| `css/selectors/parsing` (24 files) | 346 | 43 | 1 |
| `html/semantics/selectors/pseudo-classes` (39 files) | 22 | 0 | 75 |

N/A reasons: 20 expectations are built by script (`createElementNS`, `setAttributeNS`); 75 pseudo-class entries need
a script mutation of element state, user interaction, or reference rendering; 1 parsing case needs a browser feature.
Known failures: 43 assertions in three `*.tentative.html` files for proposals that are not in Selectors 4
(class-prefix `.foo-*` selectors and `:has-slotted`). The specificity files in `css/selectors` (`is/not/has`) compare
cascade winners; they run with the cascade (see `cascade.md`).


<!-- https://recursiveai.org/onehtml/docs/locators/ -->

# Locators and fingerprints

Normative behaviour of `RecursiveAI.OneHtml.Locators`, written so another language can reproduce it byte for byte.

## Hash-like names

Build tools mint class names and ids (`Button_primary__3xK9z`, `css-1x2y3z`, `sc-bdfBwQ`) that change with every build.
Locators never use them and fingerprints drop them. There is one definition, `GeneratedNames.IsHashLike(name)`:

1. Cut the name into segments at every character that is not an ASCII letter or digit.
2. The name is hash-like when some segment of **five or more** characters is one of:
   - **all digits** (`12345`);
   - **letters and digits** with at least two changes between a digit and a non-digit (`3xK9z`, `550e8400`;
     `year2024` has one change and is not hash-like);
   - **letters only, with both an upper-case and a lower-case letter**, that is not a run of camel-case words. A
     camel-case run is: an optional capital, one or more lower-case letters, then any number of words that are one
     capital followed by one or more lower-case letters.

Vectors: hash-like — `12345`, `3xK9z`, `550e8400`, `bdfBwQ`, `css-1x2y3z`, `Button_primary__3xK9z`.
Not hash-like — `year2024`, `navLink`, `Button`, `iPhone`, `main`, `nav-link`, `x1`, `a1b2` (shorter than five), `HEADER`
(one case only).

Letters are ASCII only; every other character is a separator.

## Locator generation

A locator is a selector (Selectors 4 syntax, serialized per CSSOM) that is unique in the document it was generated from.
Only elements in the document tree get one (not the contents of a `<template>`, not nodes of another document).

Per element, the **candidates**, best first:

1. `#id` when the id is non-empty and not hash-like (ids are compared case-folded in quirks mode).
2. A test hook: `[data-testid="v"]`, then `data-test`, `data-test-id`, `data-cy`, `data-qa`, `data-automation-id`,
   `data-id`, each with a non-empty value, in that order of attribute name.
3. `tag[name="v"]` when `name` is non-empty.
4. `[role="r"][aria-label="l"]` when both are non-empty, then `[aria-label="l"]`, then `[role="r"]`.
5. The bare tag name.

A candidate is **unique** when exactly one element of the document offers the same candidate (counted across every
element's full candidate list, not only its best one). Classes are never used.

Algorithm: walk from the element up through its element ancestors; at each element (starting with the element itself)
take the first unique candidate as the **anchor** and stop. Each element passed over contributes a step. A step is
`tag:nth-of-type(k)` (k is the 1-based position among siblings with the same type), or just `tag` when the element is the
only one of its type among its siblings. When the element or its parent is not in the HTML namespace the step is
`tag:nth-child(k)` instead. The locator is the anchor followed by the steps from the outermost down, each joined by
` > `. The tag in a step is the local name serialized as a CSS identifier.

Limits: at most 120 steps; an element further than that below any anchor has no locator (`TryGenerate` returns false).
If no ancestor offers an anchor, there is no locator (the document element is normally anchored by its tag).

Verification: before returning, the text is parsed and the element must match it. Anchors are unique and each step
selects one child, so the match is unique by construction; `Verify` additionally queries the whole document and demands
exactly the target (linear time, meant for tests).

Values are serialized as CSS strings and identifiers per CSSOM, so ids with special characters round-trip.

## Fingerprint

`ElementFingerprint.Create(element)` gives four fields.

- **tag**: the element's local name.
- **attrs**: for each of `class`, `href`, `id`, `name`, `role`, `src`, `type` (in that, i.e. sorted, order) that is present
  without a namespace:
  - `class`: split on ASCII whitespace; drop hash-like tokens; join the rest with a single space; omit the key if none
    remain;
  - `id`: omitted when hash-like;
  - others: the value as written.
- **text**: `"sha256:"` + lower-case hex SHA-256 of the UTF-8 bytes of the normalized text content. Text content is the
  concatenation of the element's descendant text nodes in tree order (comments, processing instructions excluded).
  Normalization: every run of ASCII whitespace (U+0020, U+0009, U+000A, U+000C, U+000D) becomes one space; leading and
  trailing whitespace is removed; nothing else changes (no-break spaces stay).
- **path**: `"sha256:"` + lower-case hex SHA-256 of the UTF-8 bytes of the path text: for each element from the document
  element down to this one, `localName[k]` with k the 1-based position among its **element** siblings, joined by `/`
  (for example `html[1]/body[2]/div[3]`).

SHA-256 is implemented in the library (no operating-system dependency).

Comparison: tag and attrs must be equal exactly; text hashes equal; the path hash is advisory and reported separately.


<!-- https://recursiveai.org/onehtml/docs/reading-view/ -->

# Reading view and navigation lists

`ReadingView.Create(tree)` and `NavigationLists.Create(tree)` (also `tree.CreateReadingView()` and
`tree.CreateNavigationLists()`) in `RecursiveAI.OneHtml.Accessibility` derive two things from an accessibility tree: the page
as one linear sequence of spoken-style steps, and the lists a reader offers for jumping around it.

**This is an approximation.** The wording is generic English, chosen to be clear and stable. It does not reproduce what
any particular screen reader says, and the tree it reads is Chromium's choice of tree (`accessibility-chromium-profile.md`).
Nothing in it is a statement about NVDA, JAWS, VoiceOver, Orca or ChromeVox. The golden files in
`testdata/reading-view/` show the output for the pages in the tests.

## The reading view

The tree is walked depth first in tree order: document order, with `aria-owns` children where the tree puts them. Each step
(`ReadingItem`) has:

- `Kind`: `Text`, `Element`, `Start` or `End`;
- `Text`: the wording, never empty;
- `Node` (the tree node), `DomNode`, and `Nodes` (every tree node a text run covers);
- `Lang`: the value of the nearest `lang` attribute on the node or an ancestor, trimmed; null when none is declared or the
  nearest is empty (the language is unknown);
- `Depth`: the number of containers open around it.

`ToText()` prints one step per line, two spaces of indent per depth.

### What produces a step

A node that the tree ignores produces nothing, but its children are still visited (they carry their own ignored and hidden
status). A hidden or `aria-hidden` subtree is ignored all the way down, so it is not read.

**Text runs.** The text of adjacent text nodes is merged into one `Text` step, as a reader reads a line. A run continues
across inline elements that are not announced (`b`, `span`, `em`, `time`, ...) and across the white space between inline
neighbours, and it ends at: an announced element or container (before and after it), the start or end of any element whose
`display` is not inline (a paragraph, `div`, list item, table part), and a change of `Lang`. Runs are whitespace-collapsed
and trimmed (ASCII whitespace only). Text that is the content of a native label which names a control or group (`label`
for a form control, `legend`, `caption`, `figcaption`) is not read as a run, because it is the name the control's or
container's step already says.

**Announced elements** produce an `Element` step:

```
<role phrase>[, <state>...][: <name>][, value <value>]
```

- The phrase is the table below. `aria-roledescription` replaces it.
- Names come from the tree. For a role that takes its name from contents, the name is included only when the element is a
  leaf: its contents are only text (nothing in it is itself announced) or its role's children are presentational (WAI-ARIA 1.2
  "Children Presentational"; those children are then not read again). When something inside is announced (a heading holding
  a link) the step says the role and the contents follow as their own steps, so no text is said twice. A name from
  `aria-label`, `aria-labelledby` or a native label is always included.
- `combobox` (including a `select`) is a leaf: its options are not read unless it is a visible `listbox`.
- Value (`, value X`) is added for text fields, search fields, combo boxes, sliders, spin buttons, progress bars and meters:
  `aria-valuetext`, else the value, else `aria-valuenow`.

**Containers** produce a `Start` step and, after their contents, an `End` step (`end of <phrase>`), at the same depth:

| Role | Start | End |
|---|---|---|
| `list` | `list with N items` (`list` when no `listitem` is counted); N counts the `listitem` descendants whose nearest list is this one | `end of list` |
| `table`, `grid`, `treegrid` | `table with R rows and C columns` (or `grid`, `tree grid`); rows are the `row` descendants, columns the widest row after column spans | `end of table` |
| `banner`, `complementary`, `contentinfo`, `main`, `navigation`, `search` | `<name> landmark` (`banner`, `complementary`, `content info`, `main`, `navigation`, `search`) | `end of <name> landmark` |
| `region`, `form` | `region`, `form` | `end of region`, `end of form` |
| `dialog`, `alertdialog` | `dialog` or `alert dialog`, then `, modal` when `aria-modal` is true | `end of dialog`, `end of alert dialog` |
| `group`, `radiogroup`, `toolbar`, `menu`, `menubar`, `listbox`, `tablist`, `tree`, `figure`, `article` | the phrase | `end of <phrase>` |

Landmark phrases do not say "landmark" for `region` and `form`, which exist as roles only when named. Container steps then
add their states (below) and `: <name>` when the container has a name. `region` and `form` have a name by construction;
`section` and `form` elements without one are `generic` in the tree and produce no container.

**Role phrases** (announced roles without a table row above): `link`, `button`, `heading level N` (`heading` without a level),
`checkbox`, `radio button`, `switch`, `text field`, `text area` (multiline), `search field`, `combo box`, `option`, `slider`,
`spin button`, `progress bar`, `meter`, `scroll bar`, `image` (role `img` and `image`), `menu item`, `checkbox menu item`,
`radio menu item`, `tab`, `tab panel`, `tree item`, `separator`, `math`, `tooltip`, `alert`, `status`, `log`, `marquee`,
`timer`, `note`, `block quote`, `term`, `definition`, `code`, `application`, `document`, `inserted text`, `deleted text`.
Other roles (`generic`, `paragraph`, `StaticText`, `strong`, `emphasis`, `row`, `rowgroup`, `caption`, ...) are silent.

**List items** are announced as `item P of N` (position in set and set size), then their contents follow.

**Table cells.**

- `columnheader` and `rowheader`: `column header` / `row header`, with `: <name>` when the cell holds only text; otherwise
  the contents follow.
- `cell` and `gridcell`: `cell`, then `: column header A / B, row header C` when headers apply, and the contents follow as
  steps of their own.
- The grid is laid out with `colspan` and `rowspan` (or `aria-colspan` / `aria-rowspan`), spans clamped to 1000 columns and
  65,534 rows. A column header applies to cells below it in the columns it spans, a row header to cells to its right in the
  rows it spans. Headers are the cells whose tree role is `columnheader` or `rowheader`, so `scope`, `th` position and
  explicit roles act through the role layer. At most 16 headers are listed per cell, and a table with more than 100,000 cells
  is read without cell headers beyond that point.

**States**, in this order, each added as `, <state>` when it applies to the role: `checked`, `not checked`,
`partially checked` (checkbox, radio, switch, menu item checkbox and radio); `pressed`, `not pressed`, `partially pressed`;
`expanded`, `collapsed`; `selected`; `current page`, `current step`, `current location`, `current date`, `current time`,
`current` (other tokens); `required`; `invalid entry` (any `aria-invalid` other than false); `unavailable` (disabled);
`read only`; `has popup`; and `P of N` for options, tabs, radio buttons, menu items and tree items.

## Navigation lists

`NavigationLists` has five lists, each in tree order, each entry holding its `AxNode` (and so its DOM node, locator and
source range). Ignored nodes are not listed.

| List | Contains | Entry |
|---|---|---|
| `Headings` | role `heading` | level (the heading level, 2 when a `role=heading` has none), name, `Lang` |
| `Landmarks` | roles `banner`, `complementary`, `contentinfo`, `form`, `main`, `navigation`, `region`, `search` | role, name, number of landmarks containing it |
| `Links` | role `link` | name, `href` as written (null when there is none), whether it starts with `#` |
| `FormFields` | roles `textbox`, `searchbox`, `combobox`, `listbox`, `checkbox`, `radio`, `switch`, `slider`, `spinbutton` | role, label (the accessible name), required, invalid, disabled, value text (null when empty) |
| `Tables` | roles `table`, `grid`, `treegrid` | caption (the accessible name), rows, columns, column header names, row header names |

Buttons are not form fields in these lists. A table whose role is `none` (a presentational table) is not listed; whether a
layout table gets that role is decided by the role layer.

## Differences

`ReadingView.Diff(other, changeSet?)` returns a `ReadingViewDiff`. Tree nodes are matched as for `TreeDiff`. A step is
identified by its tree node and `Kind` (a text run by its first text node); matched steps are `Changed` when `Text` or `Lang`
differs, steps with no match are `Added` or `Removed`, and a step that only moved is not a change. Removing the second of
three list items removes `item 2 of 3` and its text and changes `list with 3 items`, `item 1 of 3` and `item 3 of 3`.

## Not done

Announcements are English only; `Lang` is kept so a consumer can choose. Live regions, `aria-description` and tooltips,
form `title` hints, link visited state, images' long descriptions and the position of the virtual cursor are not part of
the view.


<!-- https://recursiveai.org/onehtml/docs/css-syntax/ -->

# CSS parsing and stylesheet snapshots

Normative behaviour of `RecursiveAI.OneHtml.Css`, written so another language can reproduce it. The algorithms are
those of CSS Syntax Module Level 3 (Editor's Draft of 20 October 2026, drafts.csswg.org/css-syntax-3/); this file
records only what that text leaves open or what this library adds.

## Input and offsets

- Input is decoded text (UTF-16 code units). Every range is a half-open `[start, end)` pair of offsets into that text.
- Preprocessing (§3.3) is applied while reading, not by rewriting the text, so offsets stay offsets into the original:
  CR, FF and CRLF are each one newline; U+0000 and lone surrogates act as U+FFFD (an ident code point, so they
  continue identifiers and are copied into values as U+FFFD).
- Byte input goes through the §3.2 determination (`CssEncoding.DetermineFallbackEncoding`) with a caller-supplied
  label lookup and decoder; the library has no encoding tables of its own in this layer.

## Tokens

- Tokens are exactly those of §4. Comments are not tokens: they are recorded as ranges in a separate list.
- Every character of the input belongs to exactly one token or one comment, so concatenating tokens and comments in
  offset order gives back the input. `CssSourceWriter.Write` does this and fails loudly if it ever does not.
- Token values are decoded from the source on request (escapes, U+FFFD replacement). A backslash at the very end of the
  input stands for U+FFFD, except inside a string, where it is dropped (§4.3.5, §4.3.7).
- Unicode-range tokens exist only in the value of a `unicode-range` declaration, which is tokenized a second time
  from its source text (§5.5.6, §5.5.11). Those extra tokens sit after the ordinary ones and are not part of the
  text-covering sequence.
- `CssToken.NumberValue` is a double parsed from the number's text; magnitudes beyond the double range are infinite.

## Brackets

Function and `(`, `[`, `{` openers are paired with their closers in one pass with an explicit stack: a closer closes
the innermost open block only if it is that block's ending token, otherwise it is an ordinary token (§5.5.9, §5.5.10).
An opener left open at end of input has no closer and runs to the end. The same pass applies the nesting limit (see Limits).
All parsing then skips a nested block by jumping to its matching closer, so nothing recurses on input depth.

## Nodes

A parse yields a tree of nodes in source order. Kinds:

- **Qualified rule**: prelude (token range) and a `{}` block. Style rules are qualified rules.
- **At-rule**: name, prelude, and either a terminating `;` or a `{}` block.
- **Declaration**: name, colon, value (leading and trailing whitespace and `!important` removed), important flag,
  optional terminating `;`. A name starting `--` (after unescaping) is a custom property: its value is kept verbatim
  as source text and its name is case-sensitive.
- **Invalid**: source the specification says to drop ("return nothing"). Kept so every construct has a range.

Block contents are parsed with §5.5.5 into children in source order. Declarations and rules stay interleaved; a
consumer that needs CSS Nesting's grouping of declarations into nested-declaration rules derives it from the order
(declarations after a nested rule start a new group).

- In a list of declarations (`style` attribute text) at-rules are kept as at-rule nodes; the specification discards
  them, so a consumer that wants exactly the specification's result reads only the declarations.
- `@charset` is an ordinary at-rule node; it is not a rule (§8.3) and the CSSOM must skip it.
- A rule whose prelude begins `--name:` is dropped as invalid (§5.5.3) rather than parsed as a rule; nested, it
  swallows the rest of the would-be declaration.
- Declarations are tried first for every construct in a block. The attempt fails fast (before scanning to a
  semicolon) when a `{}` block appears in a non-custom value anywhere but as the whole value, which keeps parsing
  linear on long runs of nested rules.
- Validity beyond syntax (is this a known property, a valid selector, does a custom property value contain an
  unmatched `]`) is not decided here.

### Ranges

- A node's range runs from its first token to its closing `}` or terminating `;`; for a declaration with no `;`
  to its last value or `!important` token. A block that is never closed ends at the end of the text.
- Prelude range: from the first to the last non-whitespace prelude token (comments inside kept). Value range likewise.
- Content range of a block: the text strictly between the braces (to the end of the text if unclosed).
- Declaration parts have their own ranges: name, colon, value, `!important` (from `!` to the end of `important`),
  semicolon. Whitespace and comments between parts belong to no part.

## Limits

`CssParseOptions` defaults: input 16,777,216 code units, 8,388,608 tokens, nesting depth 256 (blocks and functions
together). Input length is checked before tokenizing and token count as tokens are added (the arrays grow only up to the
limit). Exceeding either throws `CssLimitExceededException` with the limit that was hit. Malformed CSS never throws.
Cancellation is checked every 4096 tokens and every 4096 parser steps.

**Nesting depth degrades; it does not throw.** CSS Syntax 3 closes every block still open at the end of the input
(§5.5.9 "consume a simple block" and §5.5.10 "consume a function": end of input is a parse error and the block is returned),
so input made of thousands of unclosed brackets is ordinary, if odd, CSS, and so is binary data that was served as a
stylesheet. Throwing for it would fail the whole sheet, and every other sheet's rules with it, over one bad region. So when
a block or function would nest deeper than `MaxNestingDepth`, bracket pairing stops at that opener: it and everything after
it stay unpaired, which the parser already reads as blocks that run to the end of their range, and `CssTree.NestingLimitReached`
is set. The block that crosses the limit keeps its tokens but is not parsed into rules or declarations (its contents were
never bracket-matched, so they may hold closers that match nothing). The tree stays lossless (`ToSourceText` equals the
input) and its depth stays at most `MaxNestingDepth` plus one; nothing recurses on input depth. `CssLimit.NestingDepth`
is kept in the enum for compatibility and is no longer thrown. Tests: `CssLimitsAndFuzzTests` (hand-written deep and
random bracket input, lossless round trip). On the corpus the one stylesheet that hit the limit was a gzip body stored
undecoded, 56 kB of binary data.

## Serialization

- `CssSourceWriter` / `Stylesheet.ToSourceText()`: the source text, rebuilt from tokens and comments.
- `CssSerializer`: canonical text from the structure alone, following CSSOM (identifier and string escaping, `name:
  value;` declarations, `{ }` for empty blocks, grouping rules on indented lines) and §9 (a `/**/` between token pairs
  that would otherwise merge; a unit that would read as an exponent is escaped; a `\` delim is followed by a newline).
  Comments are dropped, whitespace runs become one space, names of non-custom properties are lowercased, unclosed
  constructs are closed. It re-parses to the same structure.

## Known deviations of the css-parsing-tests suite

The suite follows the 2021 candidate draft. 22 of its cases are expected to differ from the current text and are
listed with the deciding sentence in `tests/OneHtml.Tests/Css/CssParsingTests.cs`: 1 case with U+0080..U+00B6 as
ident characters (§4.2 lists the non-ASCII ident ranges), 9 with unicode-range tokens outside a `unicode-range`
descriptor (§4.3.1), 2 with `~=`-style match tokens (not in §4), 8 for declaration value trimming and the
semicolon stop token (§5.5.6), 2 with CDO/CDC kept in a rule list (§5.5.1). The suite lists parse errors for
unterminated strings and urls inside values; the test harness derives them from `CssToken.IsTerminated`.


<!-- https://recursiveai.org/onehtml/docs/css-values/ -->

# CSS values, the property table, media queries and `@supports`

Normative behaviour of the value layer of `RecursiveAI.OneHtml.Css`, written so another language can reproduce it. It
sits on the tokens and component values of `css-syntax.md`. The algorithms are those of CSS Values and Units 4,
CSS Color 4 (with the Color 5 relative-color and `color-mix()` parts), CSS Variables 1, Media Queries 5 and CSS
Conditional 3 as of 20 October 2026; this file records what those texts leave open and what is not implemented.

## Property table

- **Source.** `ed/css.json` of the `@webref/css@latest` branch of <https://github.com/w3c/webref>, commit
  `bb927df3d6cc86f1c0beca204844a170a0843a18` (committed 2026-10-22), SHA-256
  `30cb8daa786d6c27a1f74c5d413311c785ee0eec1dd34c65e8a4e6681c86baca`. This is webref's merged extract of every CSS
  specification's property definitions, not the per-spec curated files.
- **Generator.** `tools/generate-css-properties.py <css.json>` writes `src/OneHtml/Css/Generated/PropertyTableData.g.cs`.
  It checks the input against the pinned SHA-256, is deterministic, and records commit and date in the generated file.
  The fetch commands are in the script's header. `tools/generate-css-colors.py` does the same for the named-color
  table of CSS Color 4 (`Generated/NamedColors.g.cs`).
- **Content.** 822 properties, of which 170 are shorthands, 64 are logical-property members (20 logical groups), and 64
  are legacy aliases. Each entry has its name, inheritance (yes, no, "see longhands", unspecified), initial value as
  text, applies-to, percentages, computed-value text, value syntax, alias target, longhands, reset-only longhands
  and logical group. The initial value is parsed to component values on first use.
- **Prose values.** An initial value is "text" only when the source gives a value that is CSS. Otherwise the entry says
  which kind of prose it is and the initial value is not guessed:
  - *see longhands* (98): `all`, `animation`, `background`, `border` and its sides, `color-adjust`, `columns`,
    `container`, `font`, `gap`, `list-style`, `margin-block`, `margin-inline`, `mask`, `offset`, `outline`,
    `padding-block`, `padding-inline`, `text-decoration`, `transition`, the `rule*` and `column-rule*` families, the
    `corner-*-shape` family, the `timeline-trigger*` and `*-timeline` shorthands, `place-items`, `cue`, `pause`, `rest`,
    and the others the generator reports with `PropertyInitialKind.SeeLonghands`;
  - *depends on the user agent* (1): `font-family`;
  - *not defined for shorthand properties* (1): `marker`;
  - *missing in the source* (73): the `-webkit-` aliases of the flexbox, animation, transition, transform, mask, box
    and appearance properties, and `column-width`, `font-stretch`, `grid-column-gap`, `grid-gap`, `grid-row-gap`,
    `stop-color`, `stop-opacity`, `word-wrap`.
  `PropertyTable.All.Where(p => p.InitialKind != PropertyInitialKind.Value)` lists them.
- **Typed properties.** 33 properties have a typed parser (`TypedProperties.IsTyped`): the accessibility set
  (`display`, `visibility`, `content`, `color` and the other color properties, `background-image`, `opacity`, `font-size`,
  `font-weight`, `font-style`, `font-family`, `outline-*`, `clip`, `clip-path`, `position` and the offsets,
  `overflow-*`, `speak`, `speak-as`, `pointer-events`). Every other property keeps its value as component values.
- **Licences.** See `THIRD-PARTY-NOTICES.md`.

## CSS-wide keywords and shorthands

- `initial`, `inherit`, `unset`, `revert` and `revert-layer` are recognised only when they are the whole value
  (`CssWideKeywords.Detect`).
- `Shorthands.Expand(name, value)` returns the **leaf** longhands in table order; nested shorthands are flattened and
  reset-only longhands are `initial`. Status is `Expanded`, `Invalid` (the value does not match the grammar),
  `PendingSubstitution` (the value contains `var()` and cannot be split yet), `NotExpanded` (a shorthand without a
  grammar here: keep the value as written) or `NotShorthand`.
- Grammars exist for: shorthands whose value syntax ends in `{1,4}` or `{1,2}` with that many longhands (`margin`,
  `padding`, `inset`, `scroll-margin`, `border-color`, `border-style`, `border-width` and the logical pairs) and
  the two-longhand pair shorthands; shorthands with exactly a `-width`, `-style` and `-color` longhand (`border` and its
  sides, `outline`, `column-rule`); and `text-decoration`, `list-style`, `font`, `background`, `background-position`,
  `transition` and `animation`. `Shorthands.HasGrammar(name)` says which. Every other shorthand is `NotExpanded`.
- Where the table's syntax ends in `{1,4}` or `{1,2}` the expansion uses the CSS rule for omitted sides.

## Numbers, units and math

- A `CssQuantity` is a number, percentage or dimension as written, or the result of a math function. A literal too
  large for a double is held at the largest finite value; only a math function yields infinity.
- Units: absolute lengths, font-relative (`em ex cap ch ic lh rem rex rcap rch ric rlh`), viewport (`vw vh vi vb vmin
  vmax` and the `s`, `l`, `d` variants), container (`cqw cqh cqi cqb cqmin cqmax`), angle, time, frequency, resolution
  and flex units. `LengthContext` supplies the inputs for relative units; the library never measures fonts. When font
  metrics are unknown, `ex`=0.5em, `ch`=0.5em, `cap`=0.7em and `ic`=1em (Values 4 §6.1.1 fallbacks; cap is this
  library's choice). Absolute units use the CSS reference pixel.
- Math functions: `calc min max clamp round mod rem sin cos tan asin acos atan atan2 pow sqrt hypot log exp abs sign`.
  Parsing uses an explicit stack, so nesting never recurses; the expression is capped at 65,536 nodes.
  - Type checking follows Values 4 §10.1: sums need the same type; a percentage in a calculation is invalid where the
    property takes no percentage, even when it cancels (`sign(50%)`).
  - Simplification: constants fold; `min`/`max`/`clamp` of constants with the same unit fold, percentages included; a
    sum is sorted number, percentage, then dimensions by unit name (§10.13). A `clamp()` bound written `none` stands
    alone and takes no part in arithmetic.
  - Serialization: a math function that folds to a constant serializes as `calc(<value><unit>)`; NaN and infinity as
    `calc(NaN)`, `calc(infinity)`.
  - **Not implemented:** products of two dimensions (`1px * 1px`) are kept as written rather than simplified,
    `progress()`, `random()`, `random-item()`, `calc-mix()`, `inherit()` and `attr()` in math (Values 5).

## Colors

- Forms: named colors, hex (3, 4, 6, 8 digits), `rgb() rgba() hsl() hsla() hwb() lab() lch() oklab() oklch()`,
  `color()` with the predefined spaces except `display-p3-linear`, `color-mix()`, relative color syntax,
  `light-dark()`, `currentcolor`, `transparent` and the system colors.
- **Legacy serialization** (hex, named, `rgb()`, `hsl()`, `hwb()`, with no `none`): `rgb(r, g, b)` or
  `rgba(r, g, b, a)` with channels rounded half up to integers 0..255 and the alpha stored as 8 bits and written with
  the two-decimal rule of Color 4 §16.1.1 (`#00000088` is `rgba(0, 0, 0, 0.53)`).
  - css-parsing-tests expects unrounded channels and a six-decimal alpha for these (it predates the 8-bit rule).
    The suite runner accepts a difference within the rounding; the current text wins.
- **Missing components.** `rgb()` with `none` serializes as `color(srgb ...)` with `none` kept; `hsl()` and `hwb()` stay
  in their own function with `none` kept (§16.2.2).
- **Modern forms** print their own function with numbers rounded to six decimals, shortest form. Color 4 requires at
  least round-trip precision, so six decimals is allowed; tests that expect six significant digits (`73.3386`) differ.
  Numbers of magnitude 1e15 or more use an exponent.
- Parse-time clamps: `lab`/`lch` lightness to 0..100 and `oklab`/`oklch` to 0..1, chroma at least 0, hue taken modulo
  360, `hsl` saturation and lightness to 0..100, `hwb` whiteness and blackness at least 0 (a sum of 100% or more is
  a gray), NaN from math becomes 0, an infinite hue becomes 0. `rgb()` channels clamp to 0..255.
- `color-mix()` in `hsl` or `hwb` returns sRGB. Hues interpolate with the four methods. Missing components take the
  other operand's value.
- Relative colors: channel keywords are numbers (`rgb` 0..255, `hsl` and `hwb` percentages as numbers 0..100). The
  result of `rgb()`, `hsl()` or `hwb()` relative syntax is `color(srgb ...)` unless a component is missing, when `hsl`
  and `hwb` keep their function. A keyword used alone keeps its component missing.
- **Powerless hues.** Converting into `hsl`, `hwb`, `lch` or `oklch` marks the hue missing when the source chroma is
  at most 0.0015 (lab, lch) or 0.000004 (oklab, oklch), the converted saturation is under 0.001%, or whiteness plus
  blackness is within 0.002% of 100%. An authored color already in the mix space keeps its hue.
- System colors take fixed light-scheme sRGB values (dark with `ColorParseOptions.DarkScheme`) and keep their keyword
  in `SystemName`; `ToCss()` prints the keyword.
- Gamut mapping to sRGB (`ToSrgb`) is the CSS Gamut Mapping algorithm in OKLCH with the JND of 0.02.
- **Not implemented:** `alpha()`, `contrast-color()`, `color-layers()`, `display-p3-linear`, single-operand
  `color-mix()`, `color-mix()` with 0% weights, and the specified-value serialization of `color-mix()`, relative colors
  and math functions inside colors (`ToCss()` returns the resolved color; `lab(calc(0.5) ...)` prints the number). A
  font-relative or container length inside a color calculation does not parse, because the color parser has no length
  context.

## `var()`

- `VarSubstitution.ResolveCustomProperties` computes custom properties (cycles and references to invalid properties
  become guaranteed-invalid and are left out). `Substitute` replaces `var()` in a value. Both are iterative.
- A cycle is a strongly connected component (Tarjan, iterative) of the graph whose edges are the `var()` references
  in a value, fallbacks included, whether or not the fallback would be used.
- A fallback has its leading whitespace dropped. A substituted value gets `/**/` between two pieces only where two
  name-like characters would fuse into one token.
- **Limits**, checked before the work they guard (`VarLimits`): 1,048,576 characters in one substituted value,
  2,097,152 token visits (every token of every expanded fallback counts, so an empty expansion is bounded too), and
  16,777,216 characters over one `ResolveCustomProperties` call. Exceeding one gives `SubstitutionStatus.LimitExceeded`,
  and the declaration is invalid at computed-value time. A billion-laughs input fails in milliseconds.
- `IsValidSyntax` checks `var()` at parse time (Variables 2): the first argument is one or more tokens, or a single
  non-empty `{}` block; a `{}` block cannot be mixed with other tokens there; whatever follows the first top-level
  comma is the fallback and may be empty. Whether the first argument names a custom property is checked at
  substitution, which accepts only a `--name` identifier (Variables 1).

## Media queries

- `MediaQueryList.Parse` follows Media Queries 5: media types, `not`/`only`/`and`/`or`, range syntax (`width >= 400px`,
  `400px < width <= 800px`), `<general-enclosed>` (unknown). `ToCss()` is the canonical text; an invalid query
  serializes and evaluates as `not all`.
- Evaluation is three-valued. A query whose condition is unknown does not match, and `not` of unknown is unknown, so
  `not all and (unknown-feature)` does not match.
- Unclosed blocks, functions and strings are closed at the end of the input, and the canonical text writes those closers
  out so that it parses back to itself.
- Features: `width height device-width device-height aspect-ratio device-aspect-ratio resolution color color-index
  monochrome grid (0 or 1) orientation hover any-hover pointer any-pointer update overflow-block overflow-inline scan
  color-gamut prefers-color-scheme prefers-reduced-motion prefers-reduced-transparency prefers-reduced-data
  prefers-contrast forced-colors scripting display-mode dynamic-range video-dynamic-range inverted-colors nav-controls`
  and `-webkit-device-pixel-ratio`. Other names, and values outside a feature's grammar, are unknown.
- `@container` queries are parsed as at-rules and are not evaluated (they need layout).

## `StyleContext`

`StyleContext` is an immutable record. Today it holds `MediaFeatures`: media type, width, height, device pixel ratio,
`prefers-color-scheme`, `prefers-reduced-motion`, `-transparency`, `-data`, `prefers-contrast`, `forced-colors`,
`hover`/`any-hover`, `pointer`/`any-pointer`, color bits, and `scripting`, which is always `none` because the library
never runs script. The defaults are a 1280x720 light-scheme screen. New members get defaults, so existing callers keep
working when the interaction state (focus, hover, `:target`, `:active`) is added.

## `@supports`

`SupportsCondition` parses `not`, `and`, `or`, parentheses, `(property: value)`, `selector(...)`, and
`<general-enclosed>` (false). `DeclarationSupport.IsSupported(property, value)` is true when:

1. the property is a custom property with a name; or
2. it is in the property table (aliases included) and the value is non-empty and syntactically acceptable (no bad
   strings or URLs, no stray closers, no top-level braces or semicolons), and
   - the value is a CSS-wide keyword or contains `var()`; or
   - the property is typed: its typed parser accepts the value; or
   - the property is a shorthand with a grammar: it expands; or
   - the property's value syntax is only keywords and simple types (`<length>`, `<color>`, ...): the value matches it; or
   - otherwise: nothing more is checked (the value is accepted).

`selector(...)` is decided by `SupportsOptions.SelectorSupported`, which gets the selector text; without a callback the
text only has to look like one complex selector (selector-shaped tokens, no top-level commas). The selectors
component is meant to supply the real check.

## Linked stylesheets

`WhatwgCssEncodingProvider.Instance` implements the CSS Syntax §3.2 byte-to-text steps with the WHATWG decoders: the
protocol label, the `@charset` rule, then the referrer's encoding and UTF-8. The decoder replaces CR and CRLF with LF.

## Deviations the test suites show

The replay of the web-platform-tests files (`testdata/css/wpt-expectations.txt`) and of css-parsing-tests lists every known
failure with its reason. In short: the specified value of `color-mix()`, relative colors and math in colors is not
kept; Values 5 and Color 6 functions are missing; typed arithmetic on dimensions is not simplified; the analogous-
component carry-forward of Color 4 §12.4 between different spaces is incomplete.


<!-- https://recursiveai.org/onehtml/docs/cascade/ -->

# The cascade, computed styles, interaction overlays and restyle

Normative behaviour of `RecursiveAI.OneHtml.Css.DocumentStyles` (namespace `RecursiveAI.OneHtml.Css`), written so another
language can reproduce it. The algorithms are those of CSS Cascade 5 (with the Cascade 6 `revert-rule` keyword), CSS
Nesting 1, CSS Variables 1, CSS Conditional 3/4, Selectors 4 and the HTML Standard's Rendering section (§15). This file
records what those texts leave open and what is not implemented. Values stay token lists unless a typed parser exists
(`css-values.md`); there is no layout and no painting.

## Entry points

| Member | What it does |
|---|---|
| `DocumentStyles.Create(document, context?, options?)` | Gathers the style sources and prepares the cascade. No element is computed yet. |
| `GetStyle(element)` | The `ComputedStyle` of an element, computed with its ancestors on first use and cached. Thread-safe. |
| `ComputeAll()` | Computes every element in document order. |
| `WithContext(context)` | A view for another `StyleContext` that recomputes only what the context can reach (overlay). |
| `Restyle(newDocument, change)` | A view for an edited document that recomputes only what the change can reach. |
| `Sheets`, `Diagnostics`, `RuleCount`, `DistinctStyleCount` | What was gathered, what could not be, and sharing figures. |

`ComputedStyle` exposes, for every property in the property table: `GetValue(name)` (a `StyleValue`: tokens, text, the
declaration it came from, whether it is initial or inherited), `GetPropertyValue(name)` (text), `GetSource(name)`
(`DeclarationSource`: sheet, rule, source range, importance, origin, layer path), `TryGetCustomProperty`, and
`GetComputedValue(name)` (the `getComputedStyle` serialization for the typed set). Typed accessors build on first read and
are cached: `Display`, `Visibility`, `Opacity`, `Position`, the offsets, `OverflowX/Y`, `PointerEvents`, `Speak`, `SpeakAs`,
`Content`, `Clip`, `ClipPath`, `BackgroundImage`, `FontStyle`, `FontFamily`, `FontSizePx`, `FontWeight`, `Color`,
`BackgroundColor`, `OutlineColor`, `OutlineStyle`, `OutlineWidthPx`, `OutlineOffsetPx`. Resolution chains (`color` →
`currentcolor`, `font-size` → parent, root, viewport) are iterative.

## Style sources

Gathered in this order, each with an origin and a position in the cascade order:

1. **User agent sheet.** The CSS blocks of HTML §15 (33 standard blocks, 4 quirks-mode blocks), generated by
   `tools/generate-ua-stylesheet.py` into `Css/Generated/UserAgentStylesheet.g.cs` with the retrieval date and the SHA-256
   of the page. The quirks blocks apply when the document is in quirks mode. Blocks that are not CSS or are encoding
   specific are skipped (the generator lists them). Turn it off with `StyleSourceOptions.IncludeUserAgentSheet`.
2. **User sheets** from `StyleSourceOptions.UserSheets` (empty by default).
3. **Presentational hints** (their own tier between user and author, HTML §15.3.x): `bgcolor`, `text`, `font`
   `color/face/size`, `align` on `div`, `p` and `h1`–`h6`, `width`/`height` on `img`, `video`, `canvas`, `iframe`, `embed`,
   `object`, `table`, `td`, `th`, `nowrap`, and the `body` element's `link` attribute, which colours every `a[href]` and `area[href]` of the
   document (HTML Rendering, "Page"), with the legacy colour parser. **Left out:** `vlink`/`alink` (`:visited` never matches; `:active` is a
   context state),
   `border`, `cellpadding`, `cellspacing`, `valign`, list `type`, `hr` attributes, `frame`/`rules`.
4. **Author sheets** in document order: `<style>` elements and `<link rel=stylesheet>` (bytes from
   `StyleSourceOptions.Resolver`, keyed by absolute URL: the document URL from `BaseUrl`, changed by the first `<base href>`).
   A `media` attribute that does not match the context's media, `disabled`, a non-CSS `type` and `rel=alternate` sheets
   are skipped. A sheet the resolver does not return is reported as a `MissingStylesheet` diagnostic and contributes
   nothing; the library never fetches.
5. **`@import`** (same resolver) is followed in place, with `layer()`, `supports()` and media conditions, only before other
   rules (an `@import` after a rule is ignored). A cycle, or a chain deeper than `MaxImportDepth` (16), is reported
   (`ImportCycle`, `ImportDepthExceeded`) and skipped. A layered import establishes its layer even when the sheet is missing.
6. **`style=""`** attributes, as an element-attached declaration source above all author rules of the same importance.

Conditional group rules: `@media` (evaluated against the context's `MediaFeatures`), `@supports` (including
`selector()`, which accepts `&`; a selector that starts with a combinator is not valid there), `@layer` (named, anonymous,
nested, statement form; a statement inside a style rule is ignored), `@namespace`, and style rules with CSS Nesting
(`&` is replaced by `:is(parent)`, or `:scope` at the top level; an item without `&` is relative to the parent; a nested
declaration run after nested rules becomes a separate ordered rule; an invalid nested selector drops that rule and its
content; the resolved selector text is capped at 64 KB). Rules with a pseudo-element selector are kept out of the element match index; those that end in `::before`, `::after` or
`::marker` (or the single-colon forms of the first two) go into a separate index per pseudo-element (see
"Pseudo-element styles").

## Cascade

For every element and property the winner is the declaration with the greatest key, compared in this order (Cascade 5 §6):

1. **Tier:** normal declarations rank user agent < user < presentational hint < author < inline `style`; `!important`
   reverses origins: author important < inline important < user important < user agent important. Transitions and
   animations are not evaluated.
2. **Layer:** layers are ranked in a post-order of the layer tree per origin (unlayered last); for important declarations
   the rank is reversed.
3. **Specificity** (Selectors 4; `:is()` and `:not()` take their most specific argument).
4. **Order of appearance** (rule order across sheets, then the declaration's position).

Shorthands are expanded before they are compared (`Shorthands.Expand`); a shorthand with no grammar in the library
(`NotExpanded`, for example `box-shadow`) is kept as its own token list and does not override earlier longhands.
`all` accepts only a CSS-wide keyword and sets every property except `direction`, `unicode-bidi` and custom properties.
Logical properties are merged with their physical counterparts using the element's `writing-mode` and `direction` (the
later in the cascade wins). Inheritance follows the property table. CSS-wide keywords: `initial`, `inherit`, `unset`;
`revert` removes the declarations of the same origin class (user agent / user / hint-and-author); `revert-layer` removes
the winner's layer **and every later layer** of that origin at both importances (Cascade 5 §7.3.5 "or between its
normal and important levels"; element-attached styles roll back only themselves); `revert-rule` removes the winner's
rule. After a rollback the cascade is evaluated again until a non-rollback winner remains; nothing left means unset.

**Custom properties** cascade like any property, then resolve per element: `var()` inside custom properties is
substituted, cycles and references to invalid properties make the property guaranteed-invalid (it is absent, and does not
fall back to the inherited value), and the results inherit. For other properties `var()` is substituted when the style is
built; a value that is invalid then behaves as `unset` (Variables 1 §3.2). A declaration with `var()` is checked at
parse time for well-formed `var()` syntax; the fallback of a `var()` may not contain a top-level `!` or `;`.

**Provenance.** Each winning value keeps the declaration that supplied it (`DeclarationSource`). For rules from an inline
`style` attribute or a presentational hint, `Owner` is the null node, because rules are shared by text between elements.

## The style table

Styles are immutable and shared. The key of a style is the parent style object plus the identities of the winning
declaration values (and custom-property winners); an element with the same key gets the same `ComputedStyle`. A style
holds its own non-inherited values, a shared table of inherited values and the custom properties. The effect: siblings with
the same winners share a style; equal styles under different parent objects do not, because lazily resolved values
(`currentcolor`, `em`) read the parent. On the 35,000-node benchmark page below, 45 % as many styles as elements are built.
Reads are lookups; typed values are built once on first read and published with a volatile write.

## Interaction state and overlays

`StyleContext` adds `Focus` (+ `FocusSource`: `Keyboard` or `PointingDevice`), `Hover`, `Active` and `Target`, next to the
media features. They feed the selector matcher's `InteractionState`:

- `:focus` and `:focus-within` (the focused element and its flat-tree ancestors); `:focus-visible` is true for a keyboard
  focus, and for pointer focus only on text-entry controls and editing hosts (as Chrome documents it).
- `:hover` on the hovered element and its ancestors, and on the control a hovered `<label>` labels (HTML §4.10.4); `:active`
  likewise.
- `:target` and `:target-within`.
- `:visited` never matches.
- Script-driven state is invisible, so these results are CSS only.

`WithContext` returns a view that keeps the base view's styles and stores new ones for the elements the new state can
change. It matches the index of rules that read dynamic pseudo-classes (`Hover`, `Active`, `Focus`, `FocusWithin`,
`Target`, including inside `:is()`, `:not()` and `:has()`) under the old and the new state, and recomputes the elements
whose matches differ, parents before children, then the descendants whose inherited values changed. A media change rebuilds
the base.

When only the focused element differs, the matching is bounded instead of run over the page. Each compound of a rule that reads
focus is an anchor; a selector's match can change only where an anchor compound matches differently, and from there only
along the rest of the selector. The anchor compounds that can change are those of the old and new focused element and, for
`:focus-within` and for focus read inside `:has()`, of their ancestors; a `:has()` argument with a sibling combinator also
reaches the earlier siblings of those ancestors. Anchors are bucketed by the id, class or type their compound requires, so an
element is tried against only the anchors it could satisfy. What follows the anchor in the selector reaches below it and
beside it: all descendants after a descendant combinator, but only as many levels as there are child combinators when
no descendant combinator follows (`li:focus-within > a` reaches the li's children, not its subtree). Hover, active and
target changes, and focus changes together with them, test every element against the index of dynamic rules. Overlays share the engine's style table. `ChangedElements` lists the indices an overlay or restyle replaced.

## Restyle after a change

`Restyle(newDocument, StyleChange)` returns `RestyleResult(Styles, RestyledElements, FullRecompute)`.

- `StyleChange.Elements`: `ElementChange(NodeIndex, AttributeNames?)` for elements whose attributes changed (names in
  lower case; null means any), or whose children or text changed. `NodeIndex` is an index in the **new** document.
- `StyleChange.OldToNew`: for a new document whose node indices differ from the old one (an edit parses again), the new
  index of each old node, or -1 if it was removed. Added, removed and moved nodes are then found by comparing the trees,
  so the caller does not list them. Without it the new document must have the same node indices, parents and kinds.
- `StyleChange.SheetsChanged`: a `<style>` text, a linked sheet or a `<link>` changed. The sheets are gathered again;
  the elements matched by the rules between the common prefix and suffix of the old and new rule lists are restyled.

An element is recomputed when it is listed, new, moved, or next to an added or removed node (siblings and parents, when a
sibling, position or `:empty` selector exists, and the descendants of those siblings when such a selector reads a position
or sibling and then reaches below, as `li:last-child a` does), when a selector that reads a changed attribute, class or id matches it
differently in the old and the new document (found by matching only those rules, which covers descendant, sibling,
`:has()` and `:nth-*` reach), when a changed rule matches it, or when its parent's style object changed and the values
differ. Everything else keeps its style object. A change of quirks mode or of the layer structure, and a tree of another
shape without `OldToNew`, recompute fully (`FullRecompute`).

### `:has()` after a change of shape

A `:has()` result for an element X reads only what X's relative selectors reach (Selectors 4 section 4.5), so after nodes
were added or removed the engine compares old and new matches (as for attribute changes, matching only the rules with
`:has()`) for the elements the change can reach, instead of recomputing the page. The reach depends on where the
`:has()` sits in a rule:

- **Bounded:** every `:has()` of the rule is in a subject compound, alone or inside `:is()`, `:where()` or `:not()` items
  that are subjects themselves (`.a:has(.b)`, `li:not(:has(> a))`, `:is(.a:has(.b), .c)`). X is then an ancestor of
  what changed, and, when a relative selector starts with `+` or `~`, also an earlier element sibling of the change or of
  one of its ancestors. Only those elements are compared. This holds because `:has()` cannot nest, so no other `:has()`
  result feeds X's.
- **Unbounded:** a `:has()` before a combinator (`.a:has(.b) + .c`, `.a:has(.b) .c`), or inside `:nth-child(… of S)`.
  Elements beside or below X depend on X's result, so these rules are compared for every element of the page. This
  costs one match of those rules per element and no style recomputation beyond the elements whose matches differ.

Seeds are the elements the shape change touched (new nodes, the parents of removed ones, neighbours and, for rules that
reach below, the descendants of neighbours). A change of attributes is found by the attribute reach above.

### From an edit result

`styles.Restyle(EditResult)` and `styles.Restyle(BatchResult)` (extension methods in `RecursiveAI.OneHtml.Css`) take the
styles of the edited snapshot and the result of `Apply` and return the `RestyleResult` for the new document. The result
equals `DocumentStyles.Create` on the new document with the same context and options. They build the `StyleChange`:

- `OldToNew[o]` is the change set's `MapToNew` of old node `o`, or -1 when it was removed; its length is the old document's
  node count. A batch with no document change (only linked or loose sheets) restyles the same document with no map.
- Each changed element with the `Attributes` flag is an `ElementChange`. Its names are those of the `SetAttribute` and
  `RemoveAttribute` edits that targeted it, in lower case (`style` for `SetStyle` and `RemoveStyle`); they are null (any
  attribute) when no such edit explains the flag or the element is not in the HTML namespace.
- An element with the `Children` flag, and the parent of a text node with the `Data` flag, is an `ElementChange` with an
  empty name list. Added, removed and moved nodes are left to the restyle's own tree comparison.
- `SheetsChanged` is set when a sheet update of the batch has edits, when a `style`, `link` or `base` element or a doctype
  was added, removed or changed, or when the text of a `style` element changed. Narrowing a sheet change is the restyle's
  own: it gathers the sheets again and restyles the elements matched by the rules between the common prefix and suffix of the
  old and new rule lists (the rules of the `StylesheetChangeSet`, found by comparison).
- A linked sheet the batch edited is served from its new text: the new resolver returns it for `LinkedStylesheet.Url`
  (which must be the absolute URL the cascade asks for) and delegates every other URL to the resolver the styles were made
  with. The old styles keep the old sheet.

The restyle keeps an old style object for an element whose recomputed values are textually equal only when it still hangs
below the same parent style object: `em`, `%`, `currentcolor` and `bolder` resolve through the parent chain, so a
replaced parent replaces every descendant style that the new rules reach.

A retained style also needs the same origin for each winning declaration (user agent, user, author): the same `display: none`
from the user-agent rule for `[hidden]` and from an author rule are different answers to the accessibility tree, which tells
a hidden attribute from a style.

`RestyleResult.PseudoElementsMayDiffer` lists, apart from `RestyledElements`, the elements whose `::before`, `::after` or
`::marker` style may differ. An element's own style does not include its generated boxes, so a change that reaches only a
pseudo-element rule (a class on an ancestor in `.on .b::before`, an edited `p::after` rule) restyles nothing. The list is the
changed elements, the elements the shape change touches, the elements the pseudo-element selectors match differently before
and after (matched up to the pseudo-element), the elements matched by an added, removed or edited pseudo-element rule, and
`RestyledElements` (a pseudo-element inherits from its element). `GetPseudoStyle` always computes under the view's own
element style, so a retained object is never reused under another parent. A change of `StyleContext` does not fill the list;
`DocumentStyles.HasInteractivePseudoElementRules` says when such a rule exists (the `:hover` of `a:hover::before`).

Measured on a 3,600-node page with 300 rules: a class change restyles 3 elements in 1.7 ms against 11 ms for a full
compute of the new document; a declaration change in the `style` element takes 3.6 ms against 8 ms.

## Limits

`StyleSourceOptions`: `MaxImportDepth` 16, `MaxSheets` 4096, `MaxRules` 2,000,000, `MaxLayers` 65,536. Reaching one is
reported as a diagnostic (`LimitExceeded`, `ImportDepthExceeded`) and the excess is dropped. Diagnostics are capped at 256.
No loop follows input depth: gathering uses an explicit stack, ancestor chains and the restyle worklist are iterative, and
`var()` substitution has step and size limits. Selector complexity limits are those of `selectors.md`.

## Not supported

- **Other pseudo-elements.** `::before`, `::after` and `::marker` get styles (see [Pseudo-element styles](#pseudo-element-styles)); rules for the other pseudo-elements are parsed and never match.
- `@scope` and `@container` rules are reported (`UnsupportedRule`) and skipped. `@property` registrations, `@starting-style`,
  keyframes, animations and transitions are ignored. `ident()`, `if()` and container-query units are not implemented.
- `var(--x, revert-layer)`: a substituted rollback keyword behaves as `unset` instead of rolling back.
- Typed values cover the accessibility set only. `GetComputedValue` for any other property returns the cascaded text, so
  `box-shadow` is not reordered or normalized; layout-dependent values (percentages of a containing block, `auto` sizes)
  stay as specified. `font-style: oblique calc(...)` is not typed.
- Shadow DOM, slots and `:host` do not exist in the document model.

## Behaviour of the typed serialization (`GetComputedValue`)

- `font-size` is never negative; `outline-width` is never negative and snaps down to whole pixels (at least 1px when
  positive); `outline-offset: inset` is kept as the keyword when the declaration is accepted.
- `font-family` names that are runs of identifiers serialize without quotes; names that are not (digits, symbols, the
  generic keywords written as strings, CSS-wide keywords) keep quotes.
- `font-style: oblique` alone stays `oblique`; a written angle is kept; `oblique 0deg` serializes as `normal`.
- `overflow-x`/`overflow-y`: `visible` computes to `auto` when the other axis is `hidden`, `scroll` or `auto`; the
  `overflow` shorthand serializes as one keyword when both axes are equal.

## Pseudo-element styles

`GetPseudoStyle(element, PseudoElementKind)` returns the computed style of the `::before`, `::after` or `::marker` of an
element, or `null` when no rule styles it (then no box is generated for `::before` and `::after`). A selector is indexed
only when the pseudo-element is the last simple selector of its last compound; it matches when everything before the
pseudo-element matches the originating element (Selectors 4 section 3.6), with the originating element's specificity plus
one type selector for the pseudo-element. The cascade is the element cascade restricted to those rules: no `style`
attribute and no presentational hints reach a pseudo-element, and the style inherits from the element's own computed style.
The box exists for `::before` and `::after` only when `content` is neither `normal` nor `none`; the typed `Content`
accessor gives strings, `attr()`, `counter()`/`counters()`, quotes and the alternative text after `/`. Counter values and
attribute lookups are the caller's to resolve (the accessibility tree does both). User-agent rules apply, for example
`q::before { content: open-quote }`. Not done: `::first-line`, `::first-letter`, `::placeholder`, `::selection`, `::backdrop`
and the other pseudo-elements, pseudo-classes after a pseudo-element (the selector is not indexed), and generation of
`::marker` content.

## Conformance (web-platform-tests, pinned commit in the notices file)

The replay in `tests/OneHtml.Tests/Style/WptStyleTests.cs` translates `getComputedStyle` assertions, `test_computed_value`
calls, `testCases` tables and reference tests to this API without a browser. A reference test passes when the page
paints red exactly as its reference does, using a conservative notion of painting (visible background, border, outline or
text colour; a red box counts as covered when a descendant, or an absolutely positioned box, has an opaque non-red
background). Files that need script to change the page, the event loop, layout or animations are counted as not applicable
with the reason. Every failure is listed with its reason in `testdata/css/wpt-style-expectations.txt`; the test fails on an
undocumented failure.

| Directory | Pass | Known failure | N/A |
|---|---|---|---|
| `css/css-cascade` | 104 | 12 | 314 |
| `css/css-variables` | 179 | 10 | 164 |
| `css/css-nesting` | 23 | 1 | 84 |
| `css/selectors` (specificity files) | 12 | 0 | 18 |
| `css/css-fonts/parsing` (computed) | 49 | 4 | 0 |
| `css/css-display/parsing` | 108 | 0 | 0 |
| `css/css-position/parsing` | 25 | 0 | 2 |
| `css/css-overflow/parsing` | 34 | 0 | 0 |
| `css/css-ui/parsing` | 20 | 1 | 5 |

The largest N/A groups are tests that need script (`@scope` and `CSSOM` manipulation, `CSS.registerProperty`, events) and
pages whose script changes the document before asserting. The known failures are `@scope`, `ident()`, `var()` with a
`revert-layer` fallback, the tentative revert-rule cycle, `calc()` angles and container units, and reference tests that
depend on pseudo-elements, glyph painting or sibling stacking.


<!-- https://recursiveai.org/onehtml/docs/accessibility-tree/ -->

# The accessibility tree

`AccessibilityTree.Build(document, styles, context?, options?, cancellationToken)` in `RecursiveAI.OneHtml.Accessibility`
computes the objects a browser exposes to assistive technology, from a parsed document and its cascade. This file is
normative for what the tree contains and how each part is computed; the choices the specifications leave open are in
`accessibility-chromium-profile.md`, and the role layer it builds on is in `accessibility-roles.md`.

## Pipeline

All walks are loops over explicit stacks or cursors; nothing recurses on the depth of the input.

1. **Hidden status** of every element and text node (below).
2. **`aria-owns`** re-parenting (below).
3. **Roles**, twice. The first pass leaves name-dependent roles unresolved (`RoleWhenNamed`) so that a name computation
   can run; the second pass supplies that computation as `RoleOptions.HasAccessibleName`, which decides `section`, `form`,
   `aside` and the `region` and `form` role tokens. The tree's roles are the second pass's.
4. **Nodes** for the document, every element that is rendered and every text node that is kept, in document order, then
   linked into children (own DOM children that were not adopted, then owned elements) and numbered depth first.
5. **Per node:** name and description, states, relations, focus, ignored status.
6. **Whole tree:** sequential focus order, position in set, required context and owned elements, diagnostics.

Cost: linear in the document apart from name computation, which is bounded by `AccessibilityOptions.MaxNameWork` (node
visits across all names, default 32 million) and `MaxNameLength` (65,536). `aria-owns` ancestor checks are bounded by
`MaxOwnsWork` (16 million steps) and ID lists by `MaxIdReferences` (4,096 per attribute). When a limit is reached the
result is partial for the nodes affected, `AccessibilityTree.LimitReached` is true and a `LimitExceeded` diagnostic is
recorded. The cancellation token is observed every few hundred nodes.

A style context other than the one `styles` was created with is applied with `DocumentStyles.WithContext`, so the tree for
"this menu item focused" is `Build(doc, styles, StyleContext.Default.WithFocus(item))`.

## Hidden status

`AccessibilityTree.GetHidden(node)` gives a `HiddenInfo` for any element or text node, whether or not it has a tree node:
the set of `HiddenReasons`, the element that causes the strongest one (`Origin`) and whether that is an ancestor
(`IsInherited`). The reasons:

| Reason | Source | Effect |
|---|---|---|
| `DisplayNone` | computed `display: none` on the element | no tree node, for it and its subtree |
| `HiddenAttribute` | the `hidden` attribute through the user-agent sheet (HTML 15.3.1); `until-found` is `content-visibility` instead | as above |
| `Template` | a `template` element | as above |
| `ClosedDetails` | any child of a `details` without `open` except its first `summary` | as above |
| `ContentVisibilityHidden` | the parent (or an ancestor) has `content-visibility: hidden` | the element has a node; its contents have none |
| `VisibilityHidden` | computed `visibility: hidden` or `collapse` on the element; a descendant with `visibility: visible` shows again; a text node follows its parent | node present and ignored |
| `AriaHidden` | `aria-hidden="true"` on the element or an ancestor; a descendant cannot undo it | node present and ignored |
| `Inert` | the `inert` attribute on the element or an ancestor | node present, ignored, not focusable |

`Primary` orders them: not-rendered kinds, then `AriaHidden`, `Inert`, `VisibilityHidden`. Hiding that depends on layout
(zero size, clipping, off-screen) is not known without layout: `HiddenInfo.LayoutDependent` is `LayoutHiding.Unknown`. With
rendered facts the only layout-dependent hiding is an element that has no box although its style renders it (profile entry
`layout-hidden`); Chrome does not hide zero-size, clipped or off-screen content.
An `area` inside a `map` is not hidden although the rendering rules give it `display: none`.

## The tree

`Nodes` lists every node in tree order (`AxNode.Id` is the index; `Root` is the document). Each node is one of
`Document`, `Element` (rendered), `Text` or, in a tree built with rendered facts, `Generated` (a node Chromium creates from layout: a list marker or a drop-down select's popup; its `DomNode` is the owning element and `Find` never returns it).

- **`aria-owns`** (WAI-ARIA 1.2 6.6.6, Core-AAM 5.2): owners are processed in document order; the first owner of an element
  wins; an element never owns itself, the root element, or an ancestor of the owner in the tree as built so far (a cycle);
  an owner that is not rendered, `aria-hidden` or `inert` does not resolve `aria-owns`; a target that is not rendered or has
  `visibility: hidden` is skipped. An owned element leaves its DOM parent and is appended, in the order of the attribute,
  after the owner's own children. Every skipped reference is an `AriaOwnsIgnored` diagnostic with the reason.
- **Text** nodes are `StaticText` with their text, white space collapsed. White-space-only text is kept (and ignored) only in
  an inline parent. At the start and end of a block, leading and trailing white space is trimmed.
- **Role** is the Core-AAM computed role name of the role layer (`image`, `none`, `generic`, …), with `Role` empty for an
  element with no role, `RoleOrigin` the derivation and `AriaRole` the record. `RootWebArea` is the document.
  `InternalRole` names the role Chromium gives the elements WAI-ARIA has no role for (`LabelText`, `Legend`, `LineBreak`,
  `Iframe`, `DisclosureTriangle`, `Date`, `ColorWell`) and the SVG and MathML roots and tokens (`SvgRoot`, `MathMLMath`,
  `MathMLIdentifier`, `MathMLOperator`, `MathMLNumber`); an element with one is not ignored as uninteresting. A `textarea`, an `option` and an SVG
  `title`, `desc` or `metadata` element have no child nodes (the name computation still reads their text).
- **Ignored** nodes stay in the tree with `IsIgnored` and `IgnoredReasons`: `notVisible`, `ariaHiddenElement`,
  `ariaHiddenSubtree`, `inertElement`, `inertSubtree`, `presentationalRole` (role `none`/`presentation`, including
  imposed ones), `uninteresting` (the `html`, `body`, `b` and `i` elements; an element with no role and no internal role;
  `tbody` with its implicit role; white-space-only text; every other generic element is exposed, as Chrome does). SVG
  `foreignObject` is `presentationalRole`. The children of an
  ignored node are still its children; a consumer that wants the pruned tree skips ignored nodes and lifts their children.
- **Locator** is generated on demand (`AxNode.Locator`), **source range** is `AxNode.SourceBytes`.

## Accessible name and description

`AxNode.Name` / `Description` are `AxText`: the text (white space collapsed and trimmed), the step that produced it
(`AxTextSource`), the attribute involved and the elements read. `AccessibilityTree.ComputeName(element)` gives the same
for any element, including one with no node.

The name follows AccName 1.2 section 4.3.2 as a loop over frames. For a node, in order:

1. **2A hidden:** see "Hidden nodes in a name" in the profile. The root and directly referenced nodes are exempt.
2. **2B `aria-labelledby`** (skipped inside another labelledby): referenced elements in order, de-duplicated, joined with
   one space; each is read with 2C–2I as a root. When nothing results, continue.
3. **2C `aria-label`**, unless the node is an embedded control (2E).
4. **2E embedded control** inside a label, a referenced node or contents: textbox value, selected options, range value.
5. **2D native sources** (HTML-AAM section 4, SVG-AAM): label elements, `alt`, `value`, legend, caption, figcaption, `label`
   attribute, SVG `title` child, per element as in the profile entry `native-name-sources`.
6. **2F contents,** when the role allows name from contents, or the node is read as part of another's name: `::before`
   content, the children (DOM children not adopted elsewhere, then owned elements), `::after` content. Text nodes
   contribute their text with `text-transform` applied. A child that is not inline is set off by a space on each side.
7. **2I `title`**, then `placeholder` and `aria-placeholder` for text fields, then the default `Submit`/`Reset`.

A node is read at most once per mode at a time (a cycle contributes nothing), a node used as a labelledby target is not read
again as content, and the element being named is not part of its own label. A role that prohibits naming still gets a name
from `aria-labelledby`, `aria-label` and `title`.

Generated content (profile `generated-content-names`): `content` strings, `attr()` (with fallback), `counter()` and
`counters()` (CSS Lists 3 scoping; the pseudo-element's own `counter-*` properties count; a list item increments
`list-item`), `open-quote`/`close-quote`, and the alternative text after `/`, which replaces the content.

**Description:** `aria-describedby` (as labelledby, with the node as the root), else `aria-description`, else `title` when
the name did not come from `title`.

## States, properties, relations

`AxNode.States` (`AxStates`) holds, when present: expanded, checked, selected, pressed (tristate where ARIA has one),
disabled (own, fieldset, `aria-disabled` of an ancestor), required, invalid, readonly, level, position in set and set size,
value, range (now, min, max, text), live, atomic, relevant, busy, modal, current, haspopup, orientation, multiselectable,
multiline, autocomplete, keyshortcuts, roledescription, url, editable. ARIA attributes count only for roles that support
them (global attributes always), prohibited ones never; the native mapping of HTML-AAM section 3.6 (`HtmlImplicitProperties`)
comes first. Default values are in profile entry `default-states`; heading level defaults to 2.

**Position in set** is the given `aria-posinset`/`aria-setsize` or computed per profile entry `set-position`.

**Relations** (`AxNode.Relations`): `Owns` (adopted elements only), `Controls` (also the `list` attribute of an input),
`LabelledBy`, `DescribedBy`, `Details`, `ErrorMessage`, `FlowTo`, `ActiveDescendant`. Each lists the elements the valid IDs
name, the tree nodes among them, and the IDs that name nothing.

## Focus

`AxNode.Focus`: `IsFocusable` (focusable by markup per the role layer, rendered, not `visibility: hidden`, not inert, not
disabled), the parsed `TabIndex`, and `SequentialIndex` (position in `AccessibilityTree.FocusOrder`, -1 when not tabbable).
`FocusOrder` is positive `tabindex` ascending (document order breaks ties), then the rest in document order.

## Diagnostics

`AccessibilityTree.Diagnostics` (and `AxNode.Diagnostics`) in tree order:

| Kind | When |
|---|---|
| `Role` | every diagnostic of the role layer (invalid role tokens, prohibited, unsupported or deprecated attributes, invalid values, broken ID references, missing required attributes) |
| `BrokenIdReference` | `aria-controls`, `aria-details`, `aria-errormessage`, `aria-flowto`, `aria-activedescendant` or `list` names an element that is not in the tree (the role layer reports IDs that name nothing) |
| `MissingRequiredContext` | the role needs an ancestor role (WAI-ARIA 1.2 5.2.3) that the final tree lacks, `aria-owns` included |
| `MissingRequiredOwnedElements` | the role needs owned descendants (5.2.4) that are not there; `combobox` and `aria-busy="true"` are exempt |
| `FocusableUnderAriaHidden` | an element that would take focus is hidden by `aria-hidden` |
| `NamelessInteractive` | an included button, link, checkbox, radio, switch, textbox, searchbox, combobox, listbox, slider, spinbutton, menu item, tab, treeitem or option with no name |
| `EmptyNameRequired` | an included node whose role requires a name has none |
| `AriaOwnsIgnored` | an `aria-owns` reference was not honoured (reason in the message) |
| `LimitExceeded` | a limit was reached |

## Rendered facts

`AccessibilityOptions.Facts` takes the `RenderedFacts` of a Chrome `DOMSnapshot.captureSnapshot` of the same document under the
same style context (`docs/rendered-facts.md`). `Build` throws `ArgumentException` for facts of another document (id and node count)
or another context. With facts the tree applies the choices Chromium makes once layout is known, each a profile entry:

| Choice | Entry |
|---|---|
| which generic containers (and empty or block-only paragraphs) are left out as uninteresting; plain inline ones have no node | `layout-generic-pruning` |
| data tables against layout tables (`LayoutTable`, `LayoutTableRow`, `LayoutTableCell` internal roles) | `layout-table` |
| a `ListMarker` node with the marker text (or plain static text for a non-list item) | `list-marker-node` |
| a `MenuListPopup` node between a drop-down select and its options | `layout-select-popup` |
| static text of drawn white space | `layout-white-space` |
| elements with no box that the cascade renders are hidden | `layout-hidden` |

The Chrome-shaped export of such a tree has the extra nodes (without `backendDOMNodeId`). Without facts none of this happens
and the tree is exactly what it is without layout. Chrome's `getFullAXTree` has no bounding box, off-screen state or scrollable
property, so the export has none either. A scroll container is kept as an exposed generic when it has more content than room
(four nodes in the corpus sample; the keyboard-focusable-scroller behaviour is not visible in the `focusable` property).

Facts describe one snapshot, so nothing carries them over: `Update(edit, restyle)` and `WithContext(context)` return a tree with
no facts, built afresh (`UpdateInfo.FullRebuildReason` says so) when the tree had them; `Update(edit, restyle, facts)` and
`WithContext(context, facts)` take facts captured from the edited document or the new context and build afresh with them, equal
to `Build` with those facts. A tree without facts updates incrementally as before.

## Updating after an edit

`tree.Update(editResult, restyleResult)` (and the overload for an `EditBatch` result) returns the tree of the edited
document. It equals `AccessibilityTree.Build` on the new document with the same options and a style context that
`styles.Restyle(editResult)` carried over, field for field and in the same node order. `tree.WithContext(context)` does the
same for another style context of the same document. `UpdateInfo` on the result says what happened.

What is carried over is the accessible name and description of each element (with the elements they read mapped to the new
snapshot through the change set); the rest of the pipeline (hidden status, `aria-owns`, roles, states, relations, focus
order, position in set, diagnostics) is a linear pass and runs again, because it is cheap and because most of it reads
neighbours. The names are the part that walks contents and references, so they are the part that is worth skipping.

An element's name and description are recomputed when any of these holds, and so are the elements that read it:

| Input | Seed |
|---|---|
| its attributes, children or text | the node is in the change set's `Changed` list; it is `Added` (no counterpart in the old snapshot) |
| its style, or its `::before`, `::after` or `::marker` style | the element is in `RestyleResult.RestyledElements` or `PseudoElementsMayDiffer` |
| hidden status of the node (display, visibility, `hidden`, `aria-hidden`, `inert`, closed `details`, `content-visibility`, template) | the hidden reasons differ from the old tree's |
| role, role origin, disabled | the role layer's answer differs from the old tree's |
| its parent, or the element that owns it through `aria-owns` | the new parent or owner is not the old one, mapped |
| a removed node it read | the node was removed; what read it (below) is recomputed |

Readers of a recomputed node, taken as a closure: its parent (name from content, and `legend`, `caption`, `figcaption`
children); the elements that name its ID in `aria-labelledby`, `aria-describedby` or `aria-owns`; for a `label`, the element
its `for` names and the elements inside it; for a child of a `figure`, the figure's other children (an `img` that fills its figure is named by the `figcaption`). The old snapshot's readers of a changed or removed node are included, mapped to
the new snapshot, so a reference that lost its target is recomputed. An ID names the first element that carries it, so an
element that gains, loses or changes an ID also recomputes the element that held the ID before and the one that holds it
now (a label's control is found through the ID in `for`).

The dependency index is the set of ID tokens of `aria-labelledby`, `aria-describedby` and `aria-owns` per document, built on
first use and kept with the tree. Everything else the closure reads comes from the document.

The tree is built afresh instead, and `UpdateInfo.Incremental` is false with the reason, when:

- the restyle recomputed every style (`FullRecompute`);
- the previous tree reached a work limit (the carried-over names could differ from a fresh run's);
- CSS counters took part in a name (a counter value depends on every earlier element);
- a context change has other media features, or a pseudo-element rule reads an interaction state (such a rule's reach is not
  in `ChangedElements`);
- the dependency walk reached its bound (eight visits per node plus 100,000, which nested `label` elements can force).

`UpdateInfo` also gives the number of element nodes whose names were recomputed and reused.

Measured on a page of 35,892 DOM nodes (32,624 tree nodes), one `aria-label` edit, steady state on a shared 32-core
host: restyle 2 ms and update 27 ms (45 MB allocated, 6 of 16,313 element names recomputed), against 58 ms and 52 MB for
a build of the new document. The rest of the update is the linear passes above and the tree's own objects.

## Differences between trees

`tree.Diff(laterTree, changeSet?)` returns a `TreeDiff`. Nodes are matched by identity: for one document (two style
contexts) by DOM node; across an edit through `ChangeSet.MapToNew`, with the document node matching the document node and,
when several text nodes merged into one, the first claiming it. `Added` lists the later tree's unmatched nodes and `Removed`
the earlier tree's, in tree order, every node of an added or removed subtree. `Changed` lists matched nodes whose properties
differ: role, name, description, ignored, hidden reasons, `focusable` and `tabbable`, each relation (the related elements' IDs,
unresolved IDs after them with a leading `?`), and each state by its attribute-style name. A property that exists in only one tree has a null
value in the other. The order of properties is fixed.

`ReadingView.Diff` is the same for reading steps; see `reading-view.md`.

## Chrome-shaped export

`AccessibilityTree.ToChromeJson()` writes `{"schema":"onehtml-ax/1","nodes":[…]}`. `nodes` is the array
`Accessibility.getFullAXTree` returns (Chrome DevTools Protocol `AXNode`), one entry per tree node in tree order:

| Field | Value |
|---|---|
| `nodeId` | the tree node's `Id` as a string |
| `ignored`, `ignoredReasons` | `ignored`; reasons as `[{"name":…,"value":{"type":"boolean","value":true}}]` when ignored |
| `role` | `{"type":"role","value":<computed role>}`; ignored nodes are `none`; `{"type":"internalRole",…}` for `RootWebArea`, `StaticText` and every node with an `InternalRole` |
| `name` | not ignored only: `{"type":"computedString","value":…,"sources":[{"type":"attribute"|"relatedElement"|"contents"|"placeholder","value":{…},"attribute"?,"attributeValue"?,"nativeSource"?}]}`; one source, the one that produced the name |
| `description` | present when not empty |
| `value` | `{"type":"string","value":…}` for text fields, selects and ranges |
| `properties` | `[{"name":…,"value":{"type":…,"value":…}}]` for a not ignored node, in this order: busy, disabled, editable, focusable, invalid, keyshortcuts, roledescription, live, atomic, relevant, autocomplete, hasPopup, level, multiselectable, orientation, multiline, readonly, required, valuemin, valuemax, valuetext, checked, expanded, modal, pressed, selected, posinset, setsize, then the relations (activedescendant, controls, describedby, details, errormessage, flowto, labelledby, owns), url. Value types: `boolean`, `booleanOrUndefined`, `tristate` (`"true"`, `"false"`, `"mixed"`), `token`, `tokenList`, `integer`, `number`, `string`, `idref`, `idrefList` (with `relatedNodes`). An ignored node lists only `hidden` when hidden |
| `parentId`, `childIds` | tree ids; an ignored node keeps its children |
| `backendDOMNodeId` | the arena index of the node in the OneHtml document (not Chrome's id); absent for the document |

`posinset` and `setsize` are exported only when the author gave them; a node named by a label, caption or legend gets a
`labelledby` property naming it; `url` is resolved against `AccessibilityOptions.BaseUrl`. Not exported: `InlineTextBox` nodes, `frameId`, `chromeRole`, `focused`, the `hiddenRoot` and `root` properties, name sources
that lost. The export is deterministic. The spellings are profile entries; the Chrome differential
(`chrome-ax-differential.md`) compares the export's content with captures, and a change that alters meaning raises the schema
version.

## Conformance

`tests/OneHtml.Accessibility.Tests/WptAccnameTests.cs` runs the pages in `testdata/wpt/accname/` statically
(web-platform-tests commit `68d964a5f292bc4b2c2eba2f21e2b916190b6ad2`): the expectations in the markup
(`data-expectedlabel`, `data-expecteddescription`, `data-expectedproperties`), an expected subtree in a script call, the JSON
of the manual pages, and, for the html-aam name pages, the markup their script builds (reproduced step by step by the test).
Known failures, each with its reason, are in `testdata/wpt/accname/expectations.tsv`.

| Directory | Pages | Pass | Fail (known) | N/A |
|---|---|---|---|---|
| `accname/` | 2 | 11 | 0 | 0 |
| `accname/name/` | 16 | 463 | 13 | 3 |
| `accname/name/shadowdom/` | 2 | 0 | 0 | 6 |
| `accname/manual/` | 159 | 152 | 7 | 0 |
| `html-aam/accname-computation-by-element/` | 17 | 518 | 6 | 0 |
| `html-aam/` (`names`, `hidden-names`, `figure-name…`) | 3 | 139 | 3 | 0 |
| `html-aam/heading/` | 1 | 14 | 0 | 0 |
| `wai-aria/` `checked`, `pressed`, `subtree` | 3 | 9 | 0 | 0 |
| `wai-aria/heading/` | 2 | 8 | 0 | 6 |
| total | 205 | 1,314 | 29 | 15 |

Not applicable: shadow DOM is built by script (`shadowdom/`, 6), `comp_name_from_content_alt_counter_invalidation.html`
changes style by script (3), and `wai-aria/heading/invalid-nesting.tentative.html` marks its expectations ambiguous (6).
Known failures (29): the tentative `::marker` text in names (8), the tentative naming of dialog and article from a heading
(5), the tentative cell and header pages that name them only from author attributes (4), the tentative page that does not
name a figure from its figcaption (3), a menu inside a label on five manual pages (5), two legacy manual pages that expect
the label's title between its generated content (2), and the image-map area page, whose setup leaves an `alt` in place for
its title and empty cases (2). The reasons are in the expectations file.


<!-- https://recursiveai.org/onehtml/docs/accessibility-roles/ -->

# Roles: the WAI-ARIA data and the role computation

`RecursiveAI.OneHtml.Accessibility` computes the role of every element from markup alone, before any style is known.
This document is normative for that part: the data it is built from, the algorithm, and what it reports. Choices the
specifications leave open are in `accessibility-chromium-profile.md`.

## Data

The taxonomy is generated by `tools/aria/generate-aria.py` from specification documents pinned in
`tools/aria/pins.json` (URL, title, SHA-256 of the document as retrieved on 2026-10-25). `tools/aria/fetch-specs.py CACHE`
downloads them and checks the hashes; `generate-aria.py CACHE` rewrites the JSON under
`src/OneHtml.Accessibility/Aria/Data/` byte for byte reproducibly. The files are embedded in the assembly and read with
`System.Text.Json`; each has a `version` field (currently 1).

| Source | Used for |
|---|---|
| WAI-ARIA 1.2, W3C Recommendation, 6 June 2023 | roles, states and properties |
| Digital Publishing WAI-ARIA Module 1.1, W3C Recommendation, 12 June 2025 | the `doc-*` roles |
| WAI-ARIA Graphics Module 1.0, W3C Recommendation | the `graphics-*` roles |
| HTML Accessibility API Mappings 1.0, W3C Working Draft, 21 October 2026 | element and attribute mapping tables (text extract) |
| WAI-ARIA 1.3, W3C Editor's Draft, 21 October 2026 | only what browsers already ship and the 1.2 text lacks (below) |

**Draft additions.** Three roles, `comment`, `mark` and `suggestion`, and five properties, `aria-braillelabel`,
`aria-brailleroledescription`, `aria-description`, `aria-colindextext` and `aria-rowindextext`, come from the 1.3 draft
(module `Aria13Draft`). `mark` is needed by HTML-AAM's `mark` element. The draft properties are added to the supported
lists of the roles they apply to (the first three to every role). `image` is not a role of its own: it is treated as
the preferred synonym of `img`, as the draft and Core-AAM's computed role do. The draft's `sectionheader` and
`sectionfooter` roles are not included (see the profile entry `section-header-footer`).

### Counts

| | |
|---|---|
| Roles | 141: WAI-ARIA 1.2 94 (12 abstract), Digital Publishing 41, Graphics 3, 1.3 draft 3 |
| States and properties | 53: 10 states and 43 properties; 20 are global |
| HTML-AAM element entries | 147 |
| HTML-AAM attribute entries | 162 |

### Role record

For every role: `name`, `module`, `abstract`, `superclasses`, `requiredContext`, `requiredOwned` (each entry a chain such
as `["group", "option"]`; any chain satisfies the requirement), `required`, `requiredWhenFocusable` (separator's
`aria-valuenow`), `supported` (own, required and inherited, flattened), `deprecated` (the supported ones the specification
marks deprecated on that role), `prohibited`, `nameFrom` (`author`, `contents`, `prohibited`), `nameRequired`,
`childrenPresentational` and `implicit` (default values, such as `aria-live` `polite` for `log`). `none` shares the
characteristics of `presentation`; the data of `presentation` is used for both.

One entry is added to the generated data by `tools/aria/generate-aria.py`: `list` owns `listitem` directly or through a
`group` (`["group", "listitem"]`). The WAI-ARIA 1.2 role table names only `listitem`; WAI-ARIA 1.1 listed the group chain
and ACT rule bc4a75 still passes that shape, so the chain is kept.

### Property record

For every state and property: `name`, `module`, `isState`, `type` (`boolean`, `booleanUndefined`, `tristate`, `idref`,
`idrefList`, `integer`, `number`, `string`, `token`, `tokenList`), `tokens`, `default`, `global`, `globalExceptRoles`
(the roles a global attribute is prohibited on), `usedInRoles`, `inheritsIntoRoles` and `deprecated` (the whole attribute).

## HTML-AAM mapping

`HtmlRoleMapper` implements section 3.5 (element role mappings), with every condition the tables state. The text of the
tables (heading, WAI-ARIA mapping column, comments) is kept in `html-aam-elements.json`, and the attribute tables of
section 3.6 in `html-aam-attributes.json`; a test compares every entry that is a plain tag name with the mapper.

| Element | Role |
|---|---|
| `a`, `area` | `link` with `href`, otherwise `generic` |
| `img` | `img` (computed `image`); with an empty `alt` after trimming ASCII whitespace, `none` unless `aria-label` has text or `aria-labelledby` names an element |
| `header`, `footer` | `banner`, `contentinfo` when no `article`, `aside`, `main`, `nav` or `section` ancestor exists; otherwise `generic` |
| `section`, `form` | `region`, `form` when the element has an accessible name; otherwise `generic` |
| `aside` | `complementary` when the nearest ancestor among `article`, `aside`, `nav`, `section`, `main`, `body` is `main` or `body`; otherwise `complementary` only with a name, else `generic` |
| `select` | `listbox` with `multiple` or `size` above 1, otherwise `combobox` |
| `input` | by `type`: button, image, reset, submit: `button`; checkbox: `checkbox` (`switch` with the `switch` attribute); radio; number: `spinbutton`; range: `slider`; search: `searchbox`; text, tel, url, email: `textbox`; text, search, tel, url and email become `combobox` when `list` names a `datalist` of the document; color, date, datetime-local, file, hidden, month, password, time, week: no role. An invalid `type` is `text`. |
| `th` | `columnheader` for `scope` `col` or `colgroup`, `rowheader` for `row` or `rowgroup`; with `scope` auto, `columnheader` in a `thead` or a row without `td`, `rowheader` in a row with one |
| `td` | `gridcell` when the nearest `table` ancestor has an explicit `grid` or `treegrid` role, otherwise `cell` |
| `li` | `listitem` when the nearest ancestor whose role is not generic or presentational has the `list` role; otherwise `generic` |
| `option` | `option` in a `select`, an `optgroup` of a `select`, or a `datalist`; otherwise no role |
| `summary` | none for the first `summary` child of a `details`, otherwise `generic` |
| others | as the table lists; elements it does not list are `generic`; "No corresponding role" is no role |

"Has an accessible name" is not computed here. `RoleOptions.HasAccessibleName` supplies the answer; without it the role
without a name is reported and `NodeRole.RoleWhenNamed` holds the role the name would give.

`HtmlImplicitProperties.Get(element)` returns the implied states and properties of section 3.6 that markup alone
determines (`required` → `aria-required`, `disabled`, `readonly`, `checked`, `selected`, `multiple`, `placeholder`,
`list` → `aria-controls`, `min`/`max`/`value` of `meter`, `progress`, range and number inputs, `colspan`, `rowspan`,
`open` of `details` on its `summary`, the heading level, `textarea` multiline), each with the id of the table entry.

## Role computation

`RoleComputer.Compute(document, options, cancellationToken)` visits every element in document order with an explicit
stack. It does not enter `template` content. For each element:

1. **Explicit role** (WAI-ARIA 1.2 section 8.1). Split the `role` attribute on ASCII whitespace; the first token that
   names a non-abstract role, ASCII case-insensitively, wins (`image` counts as `img`). Tokens before it that are unknown
   or abstract are reported. `region` and `form` tokens are skipped when the element has no accessible name (profile
   entry `unnamed-landmark-token`). At most `MaxRoleTokens` (1024) tokens are examined.
2. **Implicit role** from the mapping above.
3. **Static focusability** (HTML 6.6.3 without style): a `tabindex` that parses as an integer, links with `href`,
   enabled `button`, `select`, `textarea` and non-hidden `input`, `iframe`, the first `summary` of a `details`, media with
   `controls`, editing hosts; never inside an `inert` subtree, and never for a control disabled by its own attribute or by
   a disabled `fieldset` ancestor (outside that fieldset's first `legend`).
4. **Resolution.**
   - explicit non-presentational role: that role (`Explicit`);
   - explicit `none` or `presentation`: if the element is focusable or has any global `aria-*` attribute, the implicit
     role (`ConflictResolved`); otherwise `none` (`Explicit`). Non-global attributes do not prevent it;
   - no explicit role, the element is a required owned element of a presentational parent (the closure of the parent's
     native role's required owned elements: `table` owns `row`, `rowgroup`, `cell`, `columnheader`, `gridcell`,
     `rowheader`; `list` owns `listitem`) and is not focusable: `none` (`InheritedPresentational`); an element with its
     own non-presentational explicit role keeps it;
   - otherwise the implicit role (`Implicit`), or no role (`None`).
5. **Presentational children.** A descendant of an element whose resolved role has presentational children is `none`
   (`ChildrenPresentational`) unless focusable. The element's attribute checks still use its own role.

The result for each element is a `NodeRole`: `Role`, `ComputedRole` (Core-AAM's names: `presentation` is `none`, `img` is
`image`, `directory` is `list`; empty when there is no role), `ExplicitRole`, `ImplicitRole`, `RoleWhenNamed`, `Origin`,
`IsFocusable`, `IsDisabled`, `IsInert` and `Diagnostics`.

## Diagnostics

For the element's own role (an inherited presentational role is not used for these checks):

| Kind | When |
|---|---|
| `InvalidRoleToken`, `AbstractRole` | a token before the chosen one (or every token when none is usable) is unknown or abstract |
| `ProhibitedAttribute` | the role prohibits the attribute, or the attribute is global with the role in its exception list |
| `UnsupportedAttribute` | a non-global attribute the role does not support |
| `DeprecatedAttribute` | deprecated on the role, or the whole attribute is |
| `UnknownAttribute` | an `aria-` name that is not a state or property |
| `InvalidAttributeValue` | the value does not fit the type: booleans, tristates and tokens against the token list, token lists token by token, integers (with the lower bounds in the profile), real numbers, an ID reference with more than one token |
| `BrokenIdReference` | an ID reference names no element of the document (each token of a list) |
| `MissingRequiredAttribute` | an explicit role that differs from the element's native role lacks a required state or property that the element does not supply natively (profile entry `required-attribute-native`); `requiredWhenFocusable` applies to focusable elements |
| `MissingRequiredContext`, `MissingRequiredOwnedElements` | reserved: they depend on the tree with `aria-owns` re-parenting, which a later step builds. `AriaRole.RequiredContext` and `AriaRole.RequiredOwned` hold the data for it. |
| `LimitExceeded` | a limit stopped the scan of role tokens, ID references or diagnostics |

An empty attribute value is treated as not specified and is not reported. Diagnostics are in attribute order.

## Limits

No recursion follows the depth of the input. Everything is linear in the number of elements, attributes and tokens:
`MaxRoleTokens` (1024), `MaxIdReferencesPerAttribute` (4096) and `MaxDiagnosticsPerElement` (64) bound the work and the
output per element; the per-row header scan runs once per row. The computation observes the cancellation token every 1024
nodes.

## Conformance

`testdata/wpt/aria/` holds the role pages of web-platform-tests `html-aam/` and `wai-aria/role/` at the commit
recorded in `MANIFEST.md`. `WptRoleTests` translates the `AriaUtils.verify*` and `assignAndVerifyRolesByRoleNames` calls
and the `get_computed_role` assertions of those pages, with a name probe of `aria-label`, a resolvable
`aria-labelledby`, or `title`. `testdata/wpt/aria/expectations.tsv` lists each known failure with its reason.

| Result | Count |
|---|---|
| Pass | 536 |
| Known failure (tentative pages) | 18 |
| Not applicable | 5 |

Known failures are all on tentative pages: `sectionheader`/`sectionfooter` for `header` and `footer` inside sectioning
content or `main` (the profile exposes `generic`), the draft "minimum role" rule that gives `div` elements with
`autofocus`, `draggable` or `popover` the `group` role, and a `li` that only `aria-owns` makes a list item. The five
not-applicable cases are expectations the pages themselves mark ambiguous (`SPEC_AMBIGUOUS_LOG_VALUE`). Cases a page
builds with script (`document.createElement`) are not run. The pages `html-aam/names.html`, `hidden-names.html`,
`figure-name-no-figcaption.tentative.html`, `img-src-srcset-roles.tentative.html` and `accname-computation-by-element/` test
names or need layout and are not included.


<!-- https://recursiveai.org/onehtml/docs/accessibility-chromium-profile/ -->

# Chromium profile for roles

Where WAI-ARIA 1.2, HTML-AAM and Core-AAM leave a choice, the accessibility tree follows what Chromium exposes. This
file lists every such choice made in the role computation (`RecursiveAI.OneHtml.Accessibility.Aria`). It is normative for
the library: a port must make the same choices. The same list is available in code as `ChromiumProfile.Entries`.

Each entry has an id, the choice, the browser behaviour it matches with where that is documented, and its evidence:

- **test suite**: a web-platform-tests page expects the behaviour and the library passes it. The pages test browsers
  through `get_computed_role`, so this is evidence of what Chromium and the other engines agree on;
- **specification**: a normative statement in the specification fixes the choice;
- **observed in Chrome output**: the Chrome differential saw it in `Accessibility.getFullAXTree` output of the pinned Chrome on the fixture pages; the entry names the pages and says what was not seen;
- **unverified until the Chrome differential**: inferred from public documentation or spec notes. The differential that
  compares the computed tree with Chrome's `Accessibility.getFullAXTree` output either confirms or corrects it.

Entries are added when a choice is made, never silently. The entries after `value-minimums` belong to the tree, the
name computation, states and focus.

## `generic-fallback`

- **Topic:** HTML elements HTML-AAM does not list
- **Choice:** Exposed with the generic role (font, center, marquee, unknown elements, autonomous custom elements).
- **Matches:** Chrome exposes unlisted elements as generic containers.
- **Evidence:** **unverified until the Chrome differential**

## `empty-alt-image`

- **Topic:** img with an empty alt
- **Choice:** The role is none unless aria-label has text or aria-labelledby names an element. A title does not name it. Presentational conflict resolution then restores the role img when the image is focusable (any tabindex) or has a global WAI-ARIA attribute with a non-blank value that is not deprecated; an empty aria-label does not count.
- **Matches:** wpt html-aam/roles-contextual.html el-img-empty-alt-title and the aria-label and aria-labelledby cases (including the empty and blank aria-label cases); WAI-ARIA 1.2 section 8.4; ACT 46ca7f.
- **Evidence:** test suite

## `unnamed-landmark-token`

- **Topic:** role=region or role=form without a name
- **Choice:** The token is skipped like an unknown token, so the next token or the native role applies.
- **Matches:** wpt wai-aria/role/region-roles.html, form-roles.html, fallback-roles.html; WAI-ARIA 1.2 section 9.1.
- **Evidence:** test suite

## `named-native-landmarks`

- **Topic:** section, form and sectioned aside
- **Choice:** region and complementary only with an accessible name; otherwise generic. A title attribute counts as a name. (form is always form, see unnamed-form.)
- **Matches:** wpt html-aam/roles-contextual.html el-section-title, el-aside-in-section-title.
- **Evidence:** test suite

## `section-header-footer`

- **Topic:** header and footer outside the body scope
- **Choice:** Role generic with the internal role sectionheader or sectionfooter, exposed (not ignored), exported under those names. A header or footer whose role is explicit keeps that role.
- **Matches:** Chrome 156 output on the svg probe fixture (header and footer in main, section and article are sectionheader and sectionfooter; the body-level ones are banner and contentinfo) and 96 such elements on 240 corpus pages. The HTML-AAM draft names the roles; the wpt pages that expect them stay known failures because the role API reports generic.
- **Evidence:** **observed in Chrome output**

## `landmark-scope`

- **Topic:** What scopes header, footer and aside
- **Choice:** The nearest ancestor among article, aside, nav, section (sectioning), main, body. header and footer are landmarks only with no such ancestor except body; aside is complementary when the nearest is main or body.
- **Matches:** wpt html-aam/roles-contextual.html and aside-in-prefixed-article.html.
- **Evidence:** test suite

## `li-accessibility-parent`

- **Topic:** li
- **Choice:** listitem when the nearest ancestor with a role other than generic or presentational has the list role (ul, ol, menu, dir, role=list); otherwise generic.
- **Matches:** wpt html-aam/roles-generic.tentative.html el-li-within-generic-within-list-parent, el-li-within-explicit-role-list-parent.
- **Evidence:** test suite

## `th-header-kind`

- **Topic:** th in the auto scope state
- **Choice:** columnheader inside thead or in a row with no td; rowheader in a row that has a td. scope=col|colgroup gives columnheader, scope=row|rowgroup gives rowheader.
- **Matches:** wpt html-aam/table-roles.html. The auto rule is a simplification of the HTML header-cell algorithm; Chrome 156 agrees on the table fixture, which sets scope on every th.
- **Evidence:** **unverified until the Chrome differential**

## `computed-role-names`

- **Topic:** Names of computed roles
- **Choice:** presentation is reported as none, img as image, directory as list.
- **Matches:** wpt wai-aria/role/synonym-roles.html; Core-AAM computed role.
- **Evidence:** test suite

## `role-token-matching`

- **Topic:** Role tokens
- **Choice:** Split on the HTML ASCII whitespace; matched ASCII case-insensitively; the first valid, non-abstract token wins; image is accepted for img.
- **Matches:** wpt wai-aria/role/fallback-roles.html, invalid-roles.html, roles.html.
- **Evidence:** test suite

## `presentational-conflict`

- **Topic:** none or presentation on a focusable element or one with a global aria-* attribute
- **Choice:** Ignored: the implicit role applies. Any state or property marked global in WAI-ARIA 1.2 counts, deprecated ones and prohibited ones included. Non-global attributes do not.
- **Matches:** wpt wai-aria/role/role_none_conflict_resolution.html and .tentative.html.
- **Evidence:** test suite

## `inherited-presentational`

- **Topic:** Required owned elements of a presentational element
- **Choice:** They are presentational too, even with global aria-* attributes; a focusable one is not. An owned element with its own non-presentational role keeps it.
- **Matches:** wpt wai-aria/role/role_none_conflict_resolution_spec_ambiguities.tentative.html.
- **Evidence:** test suite

## `children-presentational`

- **Topic:** Descendants of roles with presentational children
- **Choice:** Descendants of a button, tab or image role keep their own roles; they are not made presentational (WAI-ARIA 1.2 section 5.2.9 says they are).
- **Matches:** Chrome 156 output on the corpus: svg, heading and span inside a button keep their roles.
- **Evidence:** **observed in Chrome output**

## `static-focusable`

- **Topic:** Focusable by markup
- **Choice:** Valid tabindex, links with href, enabled form controls except hidden inputs, iframe, the first summary of a details, audio and video with controls, editing hosts, none of it inside an inert subtree. Style is not consulted.
- **Matches:** HTML 6.6.3 focusable area; iframe, media controls and summary behaviour are unverified.
- **Evidence:** **unverified until the Chrome differential**

## `empty-aria-value`

- **Topic:** An empty aria-* value
- **Choice:** Treated as not specified and not reported.
- **Matches:** WAI-ARIA 1.2 section 9.2 for booleans; extended to all types.
- **Evidence:** **unverified until the Chrome differential**

## `heading-default-level`

- **Topic:** role=heading without aria-level
- **Choice:** Level 2 (DefaultHeadingLevel).
- **Matches:** Browsers expose level 2; WAI-ARIA 1.2 leaves it undefined.
- **Evidence:** **unverified until the Chrome differential**

## `option-context`

- **Topic:** option outside select and datalist
- **Choice:** No role.
- **Matches:** HTML-AAM lists option only in a list of options.
- **Evidence:** **unverified until the Chrome differential**

## `summary-role`

- **Topic:** summary
- **Choice:** The first summary child of a details has no role of its own; any other summary is generic.
- **Matches:** wpt html-aam/summary.html.
- **Evidence:** test suite

## `foreign-elements`

- **Topic:** SVG and MathML elements
- **Choice:** The roots are mapped (svg: graphics-document, math: math), and an SVG a element with an href or xlink:href is a link, so it is named from its contents like an HTML link; other foreign elements have no implicit role until SVG-AAM is applied further.
- **Matches:** HTML-AAM defers both to their own mapping documents; SVG-AAM maps a to link when it has a link target; ACT b20e66 and 5effbb use such links.
- **Evidence:** specification

## `switch-input`

- **Topic:** input type=checkbox with the switch attribute
- **Choice:** switch.
- **Matches:** wpt html-aam/roles.tentative.html el-input-checkbox-switch.
- **Evidence:** test suite

## `select-kind`

- **Topic:** select
- **Choice:** listbox when multiple is present or size is above 1; otherwise combobox.
- **Matches:** wpt html-aam/roles.html el-select-listbox; HTML-AAM select entries.
- **Evidence:** test suite

## `input-suggestions`

- **Topic:** input with a list attribute
- **Choice:** combobox when list names a datalist in the same document, for the text, search, tel, url and email types.
- **Matches:** HTML-AAM el-input-textetc-autocomplete.
- **Evidence:** specification

## `required-attribute-native`

- **Topic:** Required states and properties of an explicit role on a native element
- **Choice:** Supplied by the native element: heading level for h1-h6, checked for checkbox and radio inputs, selected for option, valuenow for range and number inputs, meter and progress, expanded and controls for select and text inputs. Required attributes are checked only for explicit roles that differ from the element's native role.
- **Matches:** ARIA in HTML conformance model and HTML-AAM section 3.6.
- **Evidence:** **unverified until the Chrome differential**

## `value-minimums`

- **Topic:** Lower bounds of integer attributes
- **Choice:** aria-level, aria-posinset, aria-colindex, aria-rowindex, aria-colspan at least 1; aria-rowspan at least 0; aria-setsize, aria-colcount, aria-rowcount at least -1.
- **Matches:** WAI-ARIA 1.2 prose of those properties.
- **Evidence:** specification


## Tree, names, states, focus

The entries below belong to the accessibility tree (`docs/accessibility-tree.md`).
## `tree-keeps-ignored`

- **Topic:** Ignored nodes in the tree
- **Choice:** The tree keeps nodes that are ignored (hidden by visibility, aria-hidden or inert, presentational, uninteresting) with their reasons, and the children of an ignored node stay its children. Nodes that are not rendered at all have no tree node. Chrome returns no node at all for a visibility: hidden or aria-hidden element and its subtree, and none for a noscript element; those are the nodes only we list (oursOnlyIgnored in the differential), and they are ignored, so the exposed tree is the same.
- **Matches:** Chrome 156 output on the hidden and script fixture pages. The children of a visibility: hidden element that are visible again appear under its nearest exposed ancestor, which is what lifting the children of an ignored node gives.
- **Evidence:** **observed in Chrome output**

## `ignored-reason-names`

- **Topic:** Spelling of ignored reasons
- **Choice:** notVisible (visibility), ariaHiddenElement and ariaHiddenSubtree, inertElement and inertSubtree, presentationalRole, uninteresting. An ignored node is exported with the role none. Chrome also uses labelFor (a label whose text is the control name) and notRendered, which we do not produce.
- **Matches:** Names follow what the DevTools Protocol returns for ignoredReasons; uninteresting and presentationalRole observed in Chrome 156 on the fixture pages.
- **Evidence:** **observed in Chrome output**

## `generic-pruning`

- **Topic:** Generic elements
- **Choice:** A generic element is exposed (not ignored) whatever it contains or carries, including div, span and an empty container with only element children. The exceptions that are ignored as uninteresting are the html and body elements and the b and i elements (their children belong to the nearest exposed ancestor). An element with no role at all is ignored too, unless it has an internal role (see internal-roles).
- **Matches:** Chrome 156 output on the fixture pages hidden, landmarks, overflow, positioned, whitespace and background: every div and span is generic and exposed, html and body are ignored as uninteresting, b and i have no node. Not observed: an empty div or span, other inline formatting elements (u, s, small and so on) and a template inside a list (ignored there, exposed as generic under body).
- **Evidence:** **observed in Chrome output**

## `static-text-nodes`

- **Topic:** Text nodes
- **Choice:** Each text node is a StaticText node with its text, white space collapsed. A white-space-only text node is kept, as an ignored node, only when its parent is inline. Leading and trailing white space is trimmed at the start and end of a block. There are no InlineTextBox children, and no StaticText for the text of a textarea, an option or an SVG title, desc or metadata element (see text-control-leaves). Generated text (::before, ::after, list markers) is not a node (needs rendering).
- **Matches:** Chrome exposes StaticText with InlineTextBox children; the boxes need layout. Names and text of every matched StaticText equal Chrome 156 on the fixture pages, except mathematical alphanumerics (mi text uses text-transform: math-auto).
- **Evidence:** **observed in Chrome output**

## `not-rendered-absent`

- **Topic:** Elements that are not rendered
- **Choice:** display: none (including the hidden attribute and template through the user-agent sheet), the contents of a closed details other than its first summary, and the contents of content-visibility: hidden have no tree node. An area inside a map is exposed although the rendering rules give it display: none.
- **Matches:** HTML section 15.3.1, HTML section 4.11.1, CSS Containment 2 section 4.2; the area exception follows browsers that expose image-map areas.
- **Evidence:** **unverified until the Chrome differential**

## `name-hidden-referenced`

- **Topic:** Hidden nodes in a name
- **Choice:** A hidden node contributes nothing, except a root of the computation or a node named by aria-labelledby or aria-describedby. Below such a root, a node is left out only when hidden for a reason the root does not have: a hidden root brings its whole subtree in. A node hidden only by visibility still lets its visible descendants through. Native label, caption and legend elements are not directly referenced: hidden ones are skipped.
- **Matches:** wpt accname/name/comp_labelledby_hidden_nodes.html, comp_hidden_not_referenced.html, html-aam/hidden-names.html.
- **Evidence:** test suite

## `labelledby-fallthrough`

- **Topic:** aria-labelledby that names no text
- **Choice:** When every referenced node gives no text, the computation continues with aria-label and the later steps.
- **Matches:** AccName 1.2 step 2B is silent; wpt accname/name/comp_label.html passes with this reading.
- **Evidence:** test suite

## `labelledby-used-once`

- **Topic:** A node named by aria-labelledby inside another computation
- **Choice:** A node used as an aria-labelledby or aria-describedby target in a computation is left out when the same computation meets it again as content.
- **Matches:** wpt accname/name/comp_name_from_content.html (heading with two links).
- **Evidence:** test suite

## `embedded-controls`

- **Topic:** Embedded controls
- **Choice:** A textbox, combobox, listbox, slider, spinbutton, progressbar, meter or scrollbar inside a label, a referenced node or contents being read contributes its value (input value, textarea text, selected options, aria-valuetext or aria-valuenow) and its own aria-label is ignored. The element being named is exempt, so aria-labelledby naming itself still reads its aria-label. A non-native combobox with no selected option is read as contents.
- **Matches:** wpt accname/name/comp_embedded_control.html and manual/name_*_label_embedded_*.
- **Evidence:** test suite

## `name-prohibited-roles`

- **Topic:** Naming of roles that prohibit it
- **Choice:** aria-labelledby, aria-label and title still name elements whose role prohibits naming (generic, paragraph and so on); such roles never take a name from contents.
- **Matches:** wpt html-aam/accname-computation-by-element/phrasing-elements.html and accname/name/comp_label.html.
- **Evidence:** test suite

## `native-name-sources`

- **Topic:** Native name sources
- **Choice:** Form controls: label elements, then (buttons) value, then title, then placeholder, then aria-placeholder; input type=image: labels, alt, title, then Submit; submit and reset buttons fall back to Submit and Reset. img and area: alt (an img with alt="" has no name from title or contents); an img with no alt that fills its figure takes the figcaption after title. fieldset: the first rendered legend; table: the first rendered caption; figure: its figcaption; optgroup, option and track: label; svg elements: the first title child. A select is never named from its options.
- **Matches:** wpt html-aam/accname-computation-by-element/*, accname/name/comp_tooltip.html, comp_host_language_label.html.
- **Evidence:** test suite

## `generated-content-names`

- **Topic:** CSS generated content in names
- **Choice:** ::before and ::after content is part of the name of the contents: strings, attr(), counter() and counters() (CSS Lists 3 scopes, including the counter properties of the pseudo-element itself) and quotes (open-quote and close-quote as the curly double quotes). Alternative text after / replaces the content and is set off by a space on each side; a block-level pseudo-element likewise. ::marker boxes are not generated.
- **Matches:** wpt accname/name/comp_name_from_content.html, comp_name_from_content_alt_counter_multi_instance.html; the ::marker pages are tentative and listed as known failures.
- **Evidence:** test suite

## `text-transform-in-names`

- **Topic:** text-transform in names
- **Choice:** The transform of the parent element (uppercase, lowercase, capitalize) is applied to the text of a text node before it joins a name.
- **Matches:** wpt accname/name/comp_name_from_content.html.
- **Evidence:** test suite

## `name-spacing`

- **Topic:** Joining in name from contents
- **Choice:** A child whose display is not inline (or contents) is set off by a space on each side; br adds a space; inline children run together; a descendant holding only white space keeps it. The result has white space collapsed and trimmed (ASCII white space only).
- **Matches:** wpt accname/name/comp_name_from_content.html, comp_text_node.html.
- **Evidence:** test suite

## `aria-owns-resolution`

- **Topic:** aria-owns
- **Choice:** Owners are visited in document order and the first owner of an element wins. An element never owns itself, the root element or an ancestor of the owner in the tree as built so far. aria-owns on an element that is not rendered, aria-hidden or inert, or naming an element that is not rendered or has visibility: hidden, is ignored. Owned elements follow the DOM children of the owner in the order of the attribute. Work is bounded.
- **Matches:** wpt accname/aria-owns.html; WAI-ARIA 1.2 section 6.6.6.
- **Evidence:** test suite

## `aria-disabled-inherited`

- **Topic:** aria-disabled on ancestors
- **Choice:** An element is disabled when an ancestor has aria-disabled="true", as well as by its own attribute or a disabled fieldset.
- **Matches:** Chrome exposes disabled on descendants of an aria-disabled element.
- **Evidence:** **unverified until the Chrome differential**

## `default-states`

- **Topic:** States exposed without an attribute
- **Choice:** A combobox is expanded=false; checkbox, radio, switch and menuitem checkbox and radio roles are checked=false; option and tab are selected=false. Range roles (slider, scrollbar, meter, progressbar) default to 0 and 100 and a slider with no value sits at the midpoint; an input type=range clamps its value into its range. The first summary of a details is expanded=false when closed.
- **Matches:** HTML section 4.10.5.1.13; observed in Chrome 156 on the forms fixture (combobox, checkbox, radio, option, slider, progress, meter, details).
- **Evidence:** **observed in Chrome output**

## `set-position`

- **Topic:** posinset and setsize
- **Choice:** Items with the role listitem, menuitem (and its checkbox and radio forms), option, radio, tab, treeitem, or article directly in a feed, form a set with the siblings of that kind under the nearest ancestor that is not generic, none, ignored or (for treeitem and menuitem) a group. A native radio button belongs to the set of its name in its form. Ignored items are not counted; an explicit aria-posinset restarts the count and the first aria-setsize found is used for the set. The tree holds the computed values; the Chrome-shaped export leaves them out unless the author gave them (see export-set-position).
- **Matches:** Core-AAM section 5.4 and HTML-AAM.
- **Evidence:** **unverified until the Chrome differential**

## `focus-order`

- **Topic:** Sequential focus order
- **Choice:** Positive tabindex values ascending, then tabindex 0 and natively focusable elements in document order. A negative tabindex is focusable but not in the order. Disabled, inert, not rendered and visibility: hidden elements are not focusable. Radio buttons are not collapsed to one tab stop per group and scrollers are not made focusable.
- **Matches:** HTML section 6.6.3; Chrome differs for radio groups and scrollers.
- **Evidence:** **unverified until the Chrome differential**

## `export-role-names`

- **Topic:** Role names in the Chrome-shaped export
- **Choice:** Core-AAM computed role names are used, except the nodes with an internal role (see internal-roles), StaticText for text and RootWebArea for the document.
- **Matches:** Chrome DevTools Protocol AXNode role values; observed on all fixture pages.
- **Evidence:** **observed in Chrome output**

## `unnamed-form`

- **Topic:** form without an accessible name
- **Choice:** A form element has the form role whether or not it has a name.
- **Matches:** Chrome 156 exposes the unnamed form of the forms fixture as form (HTML-AAM maps form to form; the landmark rule needs a name, the role does not).
- **Evidence:** **observed in Chrome output**

## `internal-roles`

- **Topic:** Roles that are not WAI-ARIA roles
- **Choice:** Elements WAI-ARIA has no role for, and that Chrome exposes, have AxNode.InternalRole and are not ignored: label (LabelText), legend (Legend), br (LineBreak), iframe (Iframe), the first summary of a details (DisclosureTriangle), input type=date (Date) and type=color (ColorWell), which also state their value. The MathML elements math, mi, mo and mn (MathMLMath, MathMLIdentifier, MathMLOperator, MathMLNumber) keep their WAI-ARIA role and are exported under these names; svg is covered by svg-root-role. Other date and time input types, other MathML elements and the SVG graphics elements are not covered.
- **Matches:** Chrome 156 output on the forms, implied and iframe fixture pages (label, iframe, summary, date, colour, svg, math, mi, mo, mn); legend and br are inferred from the same naming.
- **Evidence:** **observed in Chrome output**

## `svg-root-role`

- **Topic:** Role of an svg element
- **Choice:** An svg with an implicit role keeps graphics-document and has the internal role image, exported as image. When something inside it is exposed (rendered text, a link, a foreignObject, an element with a role; graphics elements and nested svg elements do not count) the internal role is SvgRoot instead. An svg with no children, or nested in another svg, and no name is ignored (uninteresting). An svg with an explicit role keeps it.
- **Matches:** Chrome 156 output on the svg probe fixture: title, desc, path, g, use, nested, tabindex and aria-label svgs are image and an empty svg has no node; text, foreignObject, a link, a role=group child make SvgRoot, with or without a name; 1,381 image and 3 SvgRoot svg elements on 240 corpus pages.
- **Evidence:** **observed in Chrome output**

## `input-password-file`

- **Topic:** input type=password and type=file
- **Choice:** A password field is a textbox whose value is one bullet for each character of its value attribute (the characters are not exposed); a file field is a button whose value is the label No file chosen, whatever its multiple attribute.
- **Matches:** Chrome 156 output on the property probe pages (testdata/rendered/pages/axprops*.html, captures beside them) and the corpus; HTML-AAM lists no role for either.
- **Evidence:** **observed in Chrome output**

## `row-name`

- **Topic:** Name of a table row
- **Choice:** A row is not named from its cells; aria-label, aria-labelledby and title still name it. Cells are named from their contents.
- **Matches:** Chrome 156 output on the table fixture (rows have no name, cells do).
- **Evidence:** **observed in Chrome output**

## `text-control-leaves`

- **Topic:** Children of textarea, option and SVG title
- **Choice:** A textarea and an option have no child nodes, and neither do the SVG title, desc and metadata elements; the text is the control value, the option label or not rendered. The name computation still reads it.
- **Matches:** Chrome 156 output on the forms and implied fixtures (no StaticText for the textarea text, the option labels or the SVG title).
- **Evidence:** **observed in Chrome output**

## `option-focusable`

- **Topic:** Options of a select
- **Choice:** An enabled option inside a select is focusable (focusable=true) but not a stop of the sequential focus order.
- **Matches:** Chrome 156 output on the forms fixture.
- **Evidence:** **observed in Chrome output**

## `list-item-level`

- **Topic:** level of a list item
- **Choice:** A listitem has the level property: the number of list ancestors, unless aria-level is given.
- **Matches:** Chrome 156 output on the implied and whitespace fixtures: level=1 for items of a top-level list. Depth greater than 1 is inferred from the property name and unobserved.
- **Evidence:** **observed in Chrome output**

## `select-popup`

- **Topic:** haspopup of a select
- **Choice:** A drop-down select (combobox role) has haspopup=menu.
- **Matches:** Chrome 156 output on the forms fixture.
- **Evidence:** **observed in Chrome output**

## `number-input-bounds`

- **Topic:** Bounds of input type=number
- **Choice:** A number input without min and max has valuemin=0 and valuemax=0; with them, their values. A native slider or spin button states its value as its value text as well.
- **Matches:** Chrome 156 output on the forms fixture (spinbutton 0, 0 and valuetext 3; slider valuetext 4).
- **Evidence:** **observed in Chrome output**

## `export-native-labelledby`

- **Topic:** labelledby in the export for native labels
- **Choice:** In the Chrome-shaped export a node named by a label, caption or legend (not by aria-labelledby) has a labelledby property naming those elements. The tree API reports only aria-labelledby as the LabelledBy relation. SVG title elements are not reported.
- **Matches:** Chrome 156 output on the forms and table fixtures (controls and the captioned table); an svg named by its title has none.
- **Evidence:** **observed in Chrome output**

## `export-set-position`

- **Topic:** posinset and setsize in the export
- **Choice:** The export never states posinset or setsize, whether the author gave aria-posinset and aria-setsize or the tree computed them. The tree keeps both.
- **Matches:** Chrome 156 output on the property probe pages (testdata/rendered/pages/axprops*.html, captures beside them) and the corpus: 214 occurrences on 28 corpus pages where only we stated them, and none stated by Chrome in 12,788 captures.
- **Evidence:** **observed in Chrome output**

## `foreign-object`

- **Topic:** SVG foreignObject
- **Choice:** The foreignObject element is ignored with the reason presentationalRole.
- **Matches:** Chrome 156 output on the implied fixture.
- **Evidence:** **observed in Chrome output**

## `link-url`

- **Topic:** url of links and images
- **Choice:** The url property is the href of a link or area, or the src of an img, resolved against AccessibilityOptions.BaseUrl (and a base element). Without a base URL it is the attribute as written.
- **Matches:** Chrome 156 output on the fixture pages: absolute URLs for links and the image.
- **Evidence:** **observed in Chrome output**

## `layout-facts-scope`

- **Topic:** What rendered facts change
- **Choice:** Facts are optional (AccessibilityOptions.Facts). Without them every choice below is off and the tree is what it is without layout. With them, only the choices in the entries layout-generic-pruning, layout-table, list-marker-node, layout-select-popup, layout-white-space and layout-hidden apply. Facts must describe the same document under the same style context, or the build is refused; an update never keeps them (a new snapshot needs new facts, so the update builds afresh and equals Build with those facts).
- **Matches:** Facts are one capture of one page (DOMSnapshot.captureSnapshot), so a changed document or context makes them stale; reusing them would put Chrome's layout of the old page on the new one.
- **Evidence:** specification

## `layout-generic-pruning`

- **Topic:** Which generic containers Chromium leaves out (with facts)
- **Choice:** A generic container (div, span, li, p without a better role, unknown elements, body, b, i) is ignored with the reason uninteresting unless one of these holds: it is a section, header, footer or aside; it has an id, title, tabindex, role or any aria-* attribute; it is positioned; it scrolls (overflow auto or scroll and more content than room); its display is inline-block, inline-flex or another inline-level non-inline value; or it is a block, flow-root or list-item box whose own children are inline content (laid-out text, inline boxes, floats or out-of-flow boxes) with no in-flow block-level child. A display: inline box (an a with no href is one) and a span whose display is not inline-level, and flex, grid and table containers, are ignored unless an attribute keeps them; a span that is inline-block or inline-flex stays. A ::before or ::after block-level box is a block-level child, an inline one with text is inline content (profile entry generated-content-node); an inline box that has a ::before or ::after box is not left out. A p is ignored the same way when it has no inline content. A plain inline box that is ignored has no node at all (its children belong to the nearest ancestor with a node); a block one stays as an ignored node.
- **Matches:** Chrome 156 output on 634 corpus pages (two samples, one used to find the rule and one held out) and the layout fixture, where the exposed structure equals Chrome's. Over the paired nodes the ignored flag differs for 0.9% of them on each sample, against 12% to 15% without facts. On 240 pages, of 15,681 blocks without id or attributes whose children were all blocks Chrome ignored 15,667, and of 2,947 holding only text or inline boxes it ignored none; of 12,589 static spans without attributes it ignored 12,542. Not explained: blocks whose only children are floats (48 exposed, 22 ignored), a handful of positioned boxes, generics inside video elements, and a share of the paragraphs that Chrome ignores.
- **Evidence:** **observed in Chrome output**

## `layout-table`

- **Topic:** Layout tables (with facts)
- **Choice:** An HTML table is a data table (role table, its rows and cells row and cell) when it has a summary attribute, any aria-* attribute, a caption or a cell with scope; or, when it has more than one cell (td or th), a th, a thead, or a visible border on the table or on its first cell; or, whatever else it has, 20 or more rows (tr). Cells, captions, headers and rows of a table nested inside it belong to the nested table. Any other table is a layout table: its internal role is LayoutTable, its rows LayoutTableRow, its cells (td and th) LayoutTableCell; the Core-AAM role stays table, row and cell. The evidence scan is bounded (20,000 elements). A generic element laid out as display: table, table-row or table-cell has the same internal roles.
- **Matches:** Chrome 156 output on 171 tables of 240 corpus pages (162 judged as Chrome did: 6 layout tables looked like data tables, 3 data tables like layout tables) and the layout and table fixtures. A table with one cell is a layout table even with borders or a th (the table fixture; 12 of 12 one-cell tables with a th and no aria, summary or scope attribute on 6,000 corpus pages), while a caption makes even a one-cell table a data table (3 of 3). Among 1,604 tables with none of this evidence and no nested table, 35 of the 88 that Chrome called data tables had 20 or more rows and no table with that many rows was a layout table (at 16 rows: 9 layout tables); the other 53 data tables are small ones whose cause is not known (a background colour on the first cell is 8 times as common among them). The large layout tables that had header cells were holding nested tables whose header cells they had counted, which is why nested tables are not scanned.
- **Evidence:** **observed in Chrome output**

## `list-marker-node`

- **Topic:** List markers (with facts)
- **Choice:** An element whose layout has a ::marker box with text (a list item with a visible marker, not summary, not hidden or visibility: hidden) gets a ListMarker node as its first child, named by the marker text ("• ", "1. "), with one ignored child (none, presentationalRole). The node has no DOM node of its own: its kind is Generated and the export gives it no backendDOMNodeId.
- **Matches:** Chrome 156 output on 634 corpus pages and the whitespace, layout and implied fixtures: the node is named by the marker text and has one ignored child. An item whose role is not listitem (a list item made presentational) has the marker as plain static text instead. A marker is also absent when the item is hidden.
- **Evidence:** **observed in Chrome output**

## `layout-select-popup`

- **Topic:** Drop-down select popup (with facts)
- **Choice:** A select with the combobox role that has a box has one MenuListPopup child (a Generated node), and its options and option groups are children of that node. Options are focusable as before.
- **Matches:** Chrome 156 output on 27 corpus pages (3,400 options) and the layout fixture. Not reproduced: the extra ignored node Chrome puts between the popup and the options of a select that has an option group (forms fixture, 3 nodes).
- **Evidence:** **observed in Chrome output**

## `layout-white-space`

- **Topic:** Static text of white space (with facts)
- **Choice:** A text node of white space only has a static text when it was drawn (it has a text box) between two elements that are display: inline; any other white space has none. Text with characters is unchanged. Such a static text is not ignored.
- **Matches:** Chrome 156 output on 240 corpus pages: of 2,099 drawn spaces between two display: inline elements Chrome has a static text for 1,485; of 1,377 drawn elsewhere it has one for 33; of 24,339 collapsed spaces (no text box) it has one for 34. The 614 spaces between inline elements that have none are not explained by position, line, parent role or display.
- **Evidence:** **observed in Chrome output**

## `layout-hidden`

- **Topic:** Hiding that depends on layout (with facts)
- **Choice:** An HTML element whose style renders it but whose capture has no box is hidden as not rendered, except display: contents, option, optgroup, area, map, slot, html and body; SVG and MathML elements are never hidden this way. Zero size, clipping and an off-screen position do not hide anything: Chrome keeps such nodes in the tree. Chrome reports no bounding box, off-screen state or scrollable state in Accessibility.getFullAXTree, so the export has none.
- **Matches:** Chrome 156 output on the overflow and positioned fixtures (clipped, rect-clipped and off-screen elements are exposed) and the corpus: of about 220,000 nodes with a box on 240 pages, 2 are notRendered; none of 121,682 nodes of 120 pages has a bounding-box, off-screen or scrollable property.
- **Evidence:** **observed in Chrome output**

## `text-transform-static-text`

- **Topic:** text-transform on static text
- **Choice:** The text of a static-text node is the rendered text: text-transform (uppercase, lowercase, capitalize) applies, as it does in names.
- **Matches:** Chrome 156 output on the corpus: StaticText of an uppercased link is upper case.
- **Evidence:** **observed in Chrome output**

## `generic-title`

- **Topic:** title on a generic element
- **Choice:** A generic element with a title has the title as its description, not as its name: WAI-ARIA 1.2 lists generic as Name From: prohibited. Elements with other roles keep naming from title. The nine WPT html-aam cases that expect a name from title on b, bdi, bdo, i, q, samp, small, u and application are known failures; application is not an HTML element, so it is an unknown element with the generic role.
- **Matches:** Chrome 156 output on the corpus: generic nodes with a title have no name and the title as description. HTML-AAM maps these elements to generic and its tooltip rule would name them; Chromium does not.
- **Evidence:** **observed in Chrome output**

## `description-repeats-name`

- **Topic:** title that repeats the name
- **Choice:** A title is not also the description when the name is made from text alone and equals the title.
- **Matches:** Chrome 156 output on the corpus: no description on links whose text equals their title.
- **Evidence:** **observed in Chrome output**

## `description-list-role`

- **Topic:** dl element
- **Choice:** A dl has the role DescriptionList (an internal role), not list; its items do not count as list levels.
- **Matches:** Chrome 156 output on the corpus.
- **Evidence:** **observed in Chrome output**

## `figcaption-role`

- **Topic:** figcaption element
- **Choice:** A figcaption has the internal role Figcaption, not caption.
- **Matches:** Chrome 156 output on the corpus.
- **Evidence:** **observed in Chrome output**

## `orphan-list-item`

- **Topic:** li outside a list
- **Choice:** An li whose parent is not a list is still a listitem.
- **Matches:** Chrome 156 output on the corpus.
- **Evidence:** **observed in Chrome output**

## `aside-in-sectioning`

- **Topic:** aside nested in sectioning content
- **Choice:** An aside with no name inside article, aside, nav, section or a complementary role is generic, not a complementary landmark.
- **Matches:** Chrome 156 output on the corpus.
- **Evidence:** **observed in Chrome output**

## `presentational-table`

- **Topic:** table with role none or presentation
- **Choice:** Cells inside are generic; rows and row groups are ignored as uninteresting. WAI-ARIA 5.2.7 would make all of them presentational.
- **Matches:** Chrome 156 output on the corpus.
- **Evidence:** **observed in Chrome output**

## `noscript-not-rendered`

- **Topic:** noscript
- **Choice:** noscript is not rendered (display: none), as HTML section 15.3.1 says when scripting is enabled.
- **Matches:** Chrome 156 lists noscript elements in body as ignored with the reason notRendered (corpus page 00c499). Hiding it adds 1,611 Chrome-only nodes and 235 name mismatches to the sample compared with leaving it visible; the cause is not traced.
- **Evidence:** **observed in Chrome output**

## `live-region-properties`

- **Topic:** live region properties
- **Choice:** live, atomic and relevant are exposed only on live regions. An alert, log or status is live by its role; relevant defaults to additions text; atomic defaults to the role's value, else false.
- **Matches:** Chrome 156 output on the corpus: no live, atomic or relevant on other nodes; WAI-ARIA 1.2 defaults.
- **Evidence:** **observed in Chrome output**

## `accesskey-shortcut`

- **Topic:** accesskey
- **Choice:** An element with an accesskey has keyshortcuts Alt+ followed by the attribute exactly as written: an empty value gives Alt+, a list such as a b or a multi-character key is kept whole. aria-keyshortcuts wins when both are given.
- **Matches:** Chrome 156 output on the property probe pages (testdata/rendered/pages/axprops*.html, captures beside them) and the corpus (Linux).
- **Evidence:** **observed in Chrome output**

## `autocomplete-popup`

- **Topic:** hasPopup
- **Choice:** hasPopup is menu for aria-haspopup true and the token for menu, listbox, tree, grid or dialog on any element, a summary or a div included. A missing, false or unknown value (1, bogus) states none. Every combobox that names none has listbox (a drop-down select has menu, see select-popup), and aria-haspopup false does not remove it. A text field with aria-autocomplete adds no popup unless it is a combobox.
- **Matches:** Chrome 156 output on the property probe pages (testdata/rendered/pages/axprops*.html, captures beside them) and the corpus.
- **Evidence:** **observed in Chrome output**

## `option-selectedness`

- **Topic:** selected state of options
- **Choice:** An option is selected by its selectedness (HTML 4.10.7), including the first enabled option of a single-choice select that has none selected; aria-selected on the option overrides. A disabled native option states no selected. The value of the select is the text of that option, with the select text-transform applied.
- **Matches:** Chrome 156 output on the property probe pages (testdata/rendered/pages/axprops*.html, captures beside them) and the corpus.
- **Evidence:** **observed in Chrome output**

## `constraint-invalid`

- **Topic:** invalid from form constraints
- **Choice:** invalid is true when a control that is not disabled and has no readonly attribute fails one of: a required checkbox that is unchecked; a required radio group (same name in the same form) with no checked button; a required file field; a required date, time, month, week or datetime-local field with no valid value; a required list box or multiple select with nothing selected; a required drop-down whose chosen option is the empty-valued first option (also when it is marked selected and disabled); a number below min, above max or off the step grid counted from min; a date or month outside min and max; an email or url value that does not parse; a pattern that does not match the whole value of a text, search, tel, url, email or password field. Text fields, number fields and text areas are not reported when required and empty. An explicit aria-invalid=false replaces the report. Kept internal; the public invalid state follows ARIA. Step mismatch with no min is never reported because the step base is then the value itself.
- **Matches:** Chrome 156 output on the property probe pages (testdata/rendered/pages/axprops*.html, captures beside them) and the corpus.
- **Evidence:** **observed in Chrome output**

## `required-exposure`

- **Topic:** required
- **Choice:** The export states required for roles that take it, and not for searchbox, native select, checkbox, radio, date and button.
- **Matches:** Chrome 156 output on the corpus.
- **Evidence:** **observed in Chrome output**

## `url-roles`

- **Topic:** url property
- **Choice:** Only a link and an image state a URL; an anchor an author gave another role does not.
- **Matches:** Chrome 156 output on the corpus.
- **Evidence:** **observed in Chrome output**

## `url-serialization`

- **Topic:** url serialization
- **Choice:** URLs are resolved and serialized as the URL Standard does: host lower-cased, default port dropped, dot segments removed, percent-escape case kept, and an empty path serialized as /.
- **Matches:** Chrome 156 output on the corpus.
- **Evidence:** **observed in Chrome output**

## `expanded-list-item`

- **Topic:** expanded on a list item
- **Choice:** aria-expanded is exposed on a list item although WAI-ARIA 1.2 does not allow it there.
- **Matches:** Chrome 156 output on the corpus.
- **Evidence:** **observed in Chrome output**

## `relation-targets`

- **Topic:** relation targets in the export
- **Choice:** controls, details, errormessage, flowto and activedescendant list only targets that are exposed; labelledby, describedby and owns list every referenced element. A target that is not rendered is still a node in Chromium when it computes a name.
- **Matches:** Chrome 156 output on the corpus.
- **Evidence:** **observed in Chrome output**

## `ignored-reasons`

- **Topic:** ignored reasons
- **Choice:** The export gives one reason, the first that applies in the order notRendered, ariaHiddenElement, ariaHiddenSubtree, inertElement, inertSubtree, notVisible, emptyAlt, labelFor, presentationalRole, uninteresting. An img with an empty alt is emptyAlt. An element with aria-hidden=true of its own is ariaHiddenElement even inside another aria-hidden element; its descendants are ariaHiddenSubtree (Chrome 156 output on 400 corpus captures: 104 of 2,901 own-aria-hidden nodes were nested, and every one was the element).
- **Matches:** Chrome 156 output on the corpus.
- **Evidence:** **observed in Chrome output**

## `positioned-blockification`

- **Topic:** display of positioned and floated elements, flex and grid items, and contents elements
- **Choice:** An absolutely or fixed positioned or floated element has its display blockified (CSS Display 3 section 2.7) before names add spaces around inline-level text, and so does a child of a flex or grid container (CSS Display 3 section 2.7 blockifies flex and grid items too). A display: contents element counts as a block for the spaces. Spaces are added on each side of such a child; plain inline children run together.
- **Matches:** Chrome 156 output on the corpus (hidden-text spans in links) and on a generated probe page of 150 links (10 parent displays by 15 child displays) and 20 flex, grid and inline-flex links mixing text and spans: all agree with this rule (testdata/rendered/pages/nameprobe.html); CSS Display 3 section 2.7.
- **Evidence:** **observed in Chrome output**

## `list-item-in-widget`

- **Topic:** li inside a list with another role
- **Choice:** An li with no role of its own whose ul, ol or menu parent has an explicit role other than list, none, presentation or generic (menu, menubar, tablist) is ignored as presentational. An li whose parent is not a list element stays a listitem.
- **Matches:** Chrome 156 output on 500 corpus captures: 273 such li ignored as presentationalRole (parents menu, menubar, tablist), none exposed as listitem; 40,000 li in plain lists are listitems.
- **Evidence:** **observed in Chrome output**

## `label-for`

- **Topic:** text-only label of a checkbox or radio
- **Choice:** A label that holds only text, and the checkbox or radio button it labels when it wraps it, and labels a checkbox or a radio button, whether it wraps the control or names it with for, before or after it, is ignored with the reason labelFor, and its text nodes are ignored as presentational. A label with an element child, or a label of any other control, stays a LabelText.
- **Matches:** Chrome 156 output on 300 corpus captures: all 65 text-only labels of checkboxes and radios are ignored as labelFor, all 66 labels with element children are LabelText, and text labels of text fields, selects and textareas are LabelText.
- **Evidence:** **observed in Chrome output**

## `wbr-not-rendered`

- **Topic:** wbr
- **Choice:** A wbr element is ignored with the reason notRendered.
- **Matches:** Chrome 156 output on the corpus: every wbr in 600 captures (5,021 nodes).
- **Evidence:** **observed in Chrome output**

## `generated-content-node`

- **Topic:** ::before and ::after boxes
- **Choice:** With rendered facts, each ::before and ::after box that was laid out is a node under its element (first, after a list marker; last), holding the static text of its generated text when it has some. A box whose display is inline (or contents) is ignored with the reason uninteresting. Any other display is a generic node. An empty block-level box is a node only inside an inline-level host (a link, an inline-block); an empty inline-block box is always one; an empty block box in a block host has none. A container with no children but generated inline text is kept like one with text (it has inline content), and an inline element with a box of generated content is a node (ignored) rather than left out. Not matched: pseudo boxes whose display is table, flex, grid, table-cell or list-item (Chromium nests them differently).
- **Matches:** Chrome 156 output on two generated probe pages (testdata/rendered/pages/pseudoprobe.html and pseudoprobe2.html: inline, block, inline-block, empty, sized, absolute and floated boxes in links, divs, buttons, headings and list items) and 2,095 corpus captures, where chromeOnly nodes fell from 1.98% to 0.9%.
- **Evidence:** **observed in Chrome output**

## `control-text-node`

- **Topic:** what a form control draws inside itself
- **Choice:** With rendered facts, a text field (an input exposed as textbox, searchbox or spinbutton, and a textarea) has a generic child with the editable state holding a static text of the value (a password shows bullets; text with a line break is left out); a search or number field, and a text field showing a placeholder, add an ignored node with no reason (the placeholder is a leaf before the editor, for a search or number field the editor sits inside it). An input of type submit, button or reset has a static text of its value, or Submit or Reset. Not matched: date and time inputs (several spinbuttons and a picker button), type image, select and range.
- **Matches:** Chrome 156 output on a generated probe page (testdata/rendered/pages/controlprobe.html) and the corpus.
- **Evidence:** **observed in Chrome output**

## `svg-unrendered-elements`

- **Topic:** style and script inside svg
- **Choice:** The text of an SVG style or script element is never part of a name from contents: the elements are not rendered (SVG 2, rendering model).
- **Matches:** Chrome 156 output: 176 links on 26 corpus pages whose svg held a style element; SVG 2 section Rendering order and elements that are never rendered.
- **Evidence:** **observed in Chrome output**

## `name-from-contents-roles`

- **Topic:** roles named from contents
- **Choice:** A dt (role term) is named from its contents although WAI-ARIA 1.2 allows only an author name for term; a dfn is not (WPT html-aam phrasing-elements expects that). A time element is not named from its contents.
- **Matches:** Chrome 156 output: 929 dt on 98 corpus pages have their text as the name, 114 time elements on 13 pages have none; WPT html-aam/accname-computation-by-element/phrasing-elements.html for dfn.
- **Evidence:** **observed in Chrome output**

## `disabled-inheritance`

- **Topic:** disabled on descendants
- **Choice:** A disabled element passes the state to the descendants that can take focus (a link, a control, an element with a tabindex), not to the others: not to a paragraph, a span, a generic, or a role=button without a tabindex. The ancestor is one with aria-disabled=true or a disabled button or select; a disabled fieldset or optgroup passes nothing on and states nothing itself. An explicit aria-disabled=false ends the inheritance. An option of a disabled select or optgroup is disabled whether or not it can take focus (and stays focusable, see option-focusable).
- **Matches:** Chrome 156 output on the property probe pages (testdata/rendered/pages/axprops*.html, captures beside them) and the corpus.
- **Evidence:** **observed in Chrome output**

## `selected-states`

- **Topic:** selected on items that say nothing
- **Choice:** An option, tab or treeitem with no aria-selected states selected=false, unless an item in the same list box, tab list, tree or tree grid carries an aria-selected attribute (any value), when it states nothing. An item outside such a container stands alone. A row, a button or a link states selected only when asked; a row with aria-selected=false states nothing.
- **Matches:** Chrome 156 output on the property probe pages (testdata/rendered/pages/axprops*.html, captures beside them) and the corpus.
- **Evidence:** **observed in Chrome output**

## `option-needs-listbox`

- **Topic:** role=option outside a listbox
- **Choice:** An explicit role option is dropped when the first ancestor that is not generic, group or presentational is not a listbox or combobox (and no aria-owns gives the element to one): a button, link or list item keeps its own role, a div is generic. A list between the option and the listbox (an ul inside it) counts.
- **Matches:** Chrome 156 output on the property probe pages (testdata/rendered/pages/axprops*.html, captures beside them) and the corpus: 478 buttons, 31 links and 6 list items on 7 corpus pages that Chrome exposes as button, link and listitem.
- **Evidence:** **observed in Chrome output**

## `readonly-exposure`

- **Topic:** readonly
- **Choice:** The export states readonly on text boxes and on grids, tree grids and their cells, and nowhere else: not on a spin button, combobox, checkbox, radio, search box, slider or list box, whatever the markup says. A disabled control states none, and an input of a type other than text, tel, url, email or password with the role textbox states none.
- **Matches:** Chrome 156 output on the property probe pages (testdata/rendered/pages/axprops*.html, captures beside them) and the corpus.
- **Evidence:** **observed in Chrome output**

## `autocomplete-text-fields`

- **Topic:** autocomplete
- **Choice:** autocomplete is stated for input and textarea elements only (from aria-autocomplete), and as list for an input with a list attribute that is a combobox, disabled or not. An author aria-autocomplete on a button or a div is not stated.
- **Matches:** Chrome 156 output on the property probe pages (testdata/rendered/pages/axprops*.html, captures beside them) and the corpus.
- **Evidence:** **observed in Chrome output**

## `roledescription-roles`

- **Topic:** aria-roledescription
- **Choice:** Not stated on a generic or presentational element; stated on any other role. Chrome hands the text over as UTF-8 bytes read as Latin-1, so a non-ASCII description arrives with each byte as one character (cafe with an acute e becomes the two characters C3 A9); the export does the same.
- **Matches:** Chrome 156 output on the property probe pages (testdata/rendered/pages/axprops*.html, captures beside them) and the corpus: 22 occurrences; "Kunngjøring".
- **Evidence:** **observed in Chrome output**

## `editable-inherited`

- **Topic:** editable on the content of an editing host
- **Choice:** An element inside contenteditable (true or empty, or plaintext-only) states editable richtext or plaintext, down to a contenteditable=false element and its content. A static text node inherits its parent state. The editing host inside a disabled or read-only text field keeps its generic node but states no editable.
- **Matches:** Chrome 156 output on the property probe pages (testdata/rendered/pages/axprops*.html, captures beside them) and the corpus.
- **Evidence:** **observed in Chrome output**

## `range-values`

- **Topic:** value, valuemin, valuemax and valuetext of ranges
- **Choice:** An author aria-valuenow, aria-valuemin or aria-valuemax wins over the native attribute of an input. A spin button gives no bounds and no value: 0, 0 and 0; a focusable separator is a slider with 0 to 100; a progress bar whose aria-valuenow is not a number rests at 0. Bounds are stated as single-precision numbers (5.56 is 5.559999942779541). The export never states aria-valuetext: valuetext is the value attribute of an input slider or spin button as written (1.00, $675,000), or the number a native slider rests at, and nothing for a progress bar, meter or div.
- **Matches:** Chrome 156 output on the property probe pages (testdata/rendered/pages/axprops*.html, captures beside them) and the corpus.
- **Evidence:** **observed in Chrome output**

## `text-values`

- **Topic:** value of text-like controls
- **Choice:** A custom text box, search box or combobox (a div, or a button with the role) states its text, white space collapsed; a text input loses its line breaks; a date input with an invalid value has none; a color input is lower case; a list box states no value. An editing host without block children states its text; one with blocks would need line breaks worked out, which is left out.
- **Matches:** Chrome 156 output on the property probe pages (testdata/rendered/pages/axprops*.html, captures beside them) and the corpus.
- **Evidence:** **observed in Chrome output**

## `placeholder-leaf`

- **Topic:** placeholder before the inner editor
- **Choice:** A text, tel, url, email or password field with a placeholder and no value has an ignored leaf before the generic that holds the editor; a search or number field has it before the ignored node that holds the editor, a combobox input the same.
- **Matches:** Chrome 156 output on the property probe pages (testdata/rendered/pages/axprops*.html, captures beside them) and the corpus (axprops3).
- **Evidence:** **observed in Chrome output**

## `combobox-expanded`

- **Topic:** expanded on a combobox
- **Choice:** Only a drop-down select states expanded=false; an ARIA combobox states it when its author does.
- **Matches:** Chrome 156 output on the property probe pages (testdata/rendered/pages/axprops*.html, captures beside them) and the corpus.
- **Evidence:** **observed in Chrome output**

## `invalid-spelling`

- **Topic:** aria-invalid=spelling
- **Choice:** The export states true.
- **Matches:** Chrome 156 output on the property probe pages (testdata/rendered/pages/axprops*.html, captures beside them) and the corpus.
- **Evidence:** **observed in Chrome output**

## `treeitem-level`

- **Topic:** level of a tree item
- **Choice:** A tree item is at level 1 plus the number of groups it sits in, when aria-level is absent.
- **Matches:** Chrome 156 output on the property probe pages (testdata/rendered/pages/axprops*.html, captures beside them) and the corpus.
- **Evidence:** **observed in Chrome output**


<!-- https://recursiveai.org/onehtml/docs/rendered-facts/ -->

# Rendered facts and the DOMSnapshot adapter

`RecursiveAI.OneHtml.Accessibility.Rendered` holds what a browser's layout engine said about a page, keyed by the nodes of a OneHtml document. The library never drives a browser: the caller captures a `DOMSnapshot.captureSnapshot` result (and the page's serialized DOM) and passes the JSON in.

## Pinned format

| | |
|---|---|
| Source | Chrome DevTools Protocol, domain `DOMSnapshot`, method `captureSnapshot` (protocol version `1.3`; documented at chromedevtools.github.io/devtools-protocol/tot/DOMSnapshot/) |
| Facts model version | `RenderedFacts.FormatVersion` = 1; raised only when the meaning of a fact changes |
| Accepted inputs | the protocol result `{"documents", "strings"}`; a protocol response `{"id", "result": {...}}`; the repository's capture file `{"schema", "format", "snapshot"}` |
| Checks on the capture file's `format` | `domain` must be `DOMSnapshot`, `method` `captureSnapshot`, `protocolVersion` major `1`; anything else is refused with `DomSnapshotFormatException`. `product` and `protocolVersion` are kept on the facts |
| Request parameters assumed | `includePaintOrder`, `includeDOMRects`, `includeBlendedBackgroundColors`, `includeTextColorOpacities` (each optional: a fact whose table is absent reads as absent) and a `computedStyles` list |
| Computed-style list | the result does not say which properties were requested; the capture file's `format.parameters.computedStyles` does, and a caller with a bare result passes the list to `DomSnapshot.Parse`. `layout.styles[i]` holds one string-table index per requested property, in that order |

The snapshot's format is not a stable API of Chrome. Re-run the fixture captures on each Chrome upgrade; a change shows up as a refusal or a failed key-fact test.

## Reading (`DomSnapshot.Parse`)

`Utf8JsonReader` over the whole input, no reflection, nested values skipped by the reader's own explicit stack, so nesting never recurses. Unknown members are ignored. Tables are validated once after reading so later stages index without checks:

- `parentIndex`, `nodeType`, `nodeName` have one entry per node (`nodeValue`, `backendNodeId`, `attributes` are optional but, when present, equal in length); a parent index is `-1` (exactly one root, node 0) or the index of an earlier node;
- every string index is in `[-1, strings.Length)`; `attributes` entries have an even length;
- rare data (`pseudoType`, `shadowRootType`, `contentDocumentIndex`, `inputValue`, `textValue`, `inputChecked`, `optionSelected`, `isClickable`, …) refers to existing nodes; frame links to existing documents;
- layout arrays equal the layout item count when present; rectangles are `[x, y, width, height]`, or `[]`/`null` for none (read as absent); text boxes refer to existing layout items; every `stackingContexts` entry is a layout item;
- with a style list, every layout item has none or exactly that many style values.

Limits (`DomSnapshotLimits`), each checked before the array that would exceed it grows. The first column is the property name; a violation throws `DomSnapshotFormatException` whose `LimitName`, `Limit` and `Actual` say which:

| Limit | Default |
|---|---|
| `MaxInputBytes` | 256 MiB |
| `MaxStrings` / `MaxStringChars` | 16 Mi entries / 256 Mi UTF-16 units |
| `MaxDocuments` | 4096 |
| `MaxNodes` / `MaxLayoutNodes` / `MaxTextBoxes` (over all documents) | 8 Mi / 8 Mi / 16 Mi |
| `MaxArrayElements` (one flattened table) | 128 Mi |
| `MaxNodeDepth` (DOM nesting, from `parentIndex`, computed without recursion) | 10 000 |
| `MaxComputedStyleNames` | 1024 |
| `MaxJsonDepth` | 64 |

Anything else wrong with the input (malformed JSON, a wrong type, an inconsistent table, another protocol version) is also a `DomSnapshotFormatException`. Mismatch between a snapshot and a document is never an exception: it is a refusal (below).

## The facts

`RenderedFacts` is immutable and thread-safe, holds no reference to the document (it records `Document.Id` and the node count), and is queried with a `Node`: `facts[node]` (or `TryGet`) gives a `NodeFacts` view over shared tables.

Per node (`NodeFacts`): `HasLayout`; `Layout` (a `BoxFacts`); `IsStackingContext`; `StackingContextNodeIndex` (nearest ancestor-or-self whose box begins a stacking context); `BackendNodeId`; `SnapshotNodeIndex`; `InputValue`, `TextValue`, `InputChecked`, `OptionSelected`, `IsClickable`; `GeneratedBoxes`; `Background`.

Per box (`BoxFacts`): `BorderBox` (the layout item's `bounds`, document coordinates, CSS pixels); `OffsetRect`, `ClientRect`, `ScrollRect` (`offsetRects`, `clientRects`, `scrollRects` as reported, null when absent); `PaintOrder` (global; boxes painted together share a value; larger paints later); `IsStackingContext`; `LayoutText`; `TextBoxes` (start and length in UTF-16 units of the layout text, and bounds); `BlendedBackgroundColor` and `TextColorOpacity` (as reported); `GetStyle(name)` (the raw string Chrome serialized, for a property in `ComputedStyleNames`).

A node **was laid out** iff it has a box: `display: none` elements and their descendants, and `display: contents` elements, have none; `visibility: hidden` and zero-opacity elements do. Facts say nothing about states the capture did not have (hover, focus); `RenderedFacts.Context` and `ViewportWidth`/`ViewportHeight` record what the caller said the capture was taken under.

Boolean rare data (`inputChecked`, `optionSelected`, `isClickable`) lists only the nodes where it is true, so these facts are `false` for every other node, not "unknown".

## Choosing the document

The intended input is Chrome's serialized DOM (`document.documentElement.outerHTML`, optionally preceded by the serialized doctype) parsed by OneHtml, captured in the same session as the snapshot with page script disabled. Parsing the original bytes also works when no script ran or changed the DOM. A DOM that script changed, parsed from the original bytes, is refused (below).

## Mapping rules (`DomSnapshotAdapter.Map`)

Every snapshot node of the chosen snapshot document lands in exactly one category, and `SnapshotAccounting.IsComplete` states that none is lost:

| Category | Which nodes | Facts |
|---|---|---|
| mapped | the document node, elements, text nodes, comments, and template content (the fragment under a `template` pairs with `TemplateContent`) | on the OneHtml node |
| pseudo | a node with a `pseudoType` (or a name starting with `::`) and all its descendants | `GeneratedBox` on the host element: type, identifier, the pseudo-element's box, the boxes of its generated children, and the generated text (the layout text of those boxes in layout order) |
| shadow | a shadow root (any `shadowRootType`: user-agent, open, closed) and everything below it, including pseudo-elements whose host is inside it | none; user-agent shadow trees of form controls have no OneHtml nodes. The host element keeps its own facts |
| prolog | document-level nodes other than the root element (doctype, comments before or after `<html>`) | none; the document is not required to have them, and when it does they are not compared |
| other documents | the nodes of every other snapshot document | map each with `Map(..., new DomSnapshotMapOptions { DocumentIndex = n })` against a document parsed from that frame; `RenderedFacts.Frames` lists the frame owner elements and their document indexes |

Layout items follow their node: a mapped node's first layout item becomes its box (a second item for the same node is counted as `LayoutDuplicate` and dropped); items of pseudo-element nodes become generated boxes; items inside shadow trees are dropped (`LayoutShadow`).

Pairing walks both trees in document order, iteratively. Under each pair of parents, the snapshot's children (leaving out pseudo-elements, shadow roots and prolog nodes) and the document's children must line up one to one:

- elements by local name, compared ASCII case-insensitively (Chrome reports `DIV`, SVG keeps `foreignObject`);
- text nodes (and CDATA nodes) by their exact characters, including whitespace-only text nodes;
- comments and processing instructions by position only (they never affect rendering);
- attributes per `AttributeCheck` (below).

### The refusal rule

A snapshot is refused (`DomSnapshotMapResult.Succeeded` is false, `Refusal` says why, nothing throws) unless the DOM it describes is the document's DOM:

1. **Counts.** The number of elements, text nodes and comments (outside template content and the document prolog) must match. A removed or added node fails here: `NodeCountMismatch`, with both sides' counts. The refusal also names the first difference of the walk below and its path, when the walk finds one.
2. **Walk.** The first difference in document order, with the snapshot node, the document node and a path such as `html[1] > body[2] > div[1] > span[1]` (elements numbered among element siblings): `StructureMismatch` (a different element name or kind, or different child counts), `TextMismatch` (shows both strings, clipped), `AttributeMismatch`.
3. **Fingerprint.** A 64-bit FNV-1a hash over the pre-order stream of (depth, kind, ASCII-lower-cased element name) for elements and text nodes. Both sides compute it (`DomSnapshotAdapter.StructureFingerprint`); the document's is stored in the facts. After a clean walk the fingerprints must agree (`FingerprintMismatch`; not expected, but never ignored).

`AttributeCheck` decides how attributes weigh in:

| Mode | Rule |
|---|---|
| `Values` (default) | every element has the same attributes (same names, same values, any order). A changed value can change layout, so the facts no longer describe the page |
| `Names` | the same names; values may differ. For a document whose attribute values were edited where layout is known not to depend on them (for example `aria-*`, `title`) |
| `None` | attributes are not compared |

**Line breaks.** Text and attribute values are compared with every line break (CR LF, lone CR, LF) as one. The document is parsed from markup, and the HTML input stream preprocessing (HTML 13.2.3.5) turns CR LF and CR into LF. A browser's DOM keeps a CR that came from a character reference (`&#13;`) or from script, and serializes it as a raw CR, which the parser then loses. So a snapshot with CR LF in an attribute or text value is the same DOM as a document with LF there. On the corpus capture this was 38 of 67 refusals.

**What stays refused.** A snapshot that cannot be a re-parse of its own serialized DOM. On the corpus capture, 29 pages of 12,750: about 20 hold a custom element with a shadow root, where Chrome's snapshot lists the shadow tree under the host and leaves out the host's light-DOM children (a `<style>` or white space between the tags); a form element the parser would move or drop (a `form` inside a table or another form) so the re-parse has a `div` or `input` where the DOM has the `form`; text nodes the serialization merges or splits; and attribute values that script generated at random between the two reads (`id`). Facts for such a page would have no counterpart for some nodes, so the refusal is the answer.

Also refused: a snapshot document index that does not exist (`DocumentIndexOutOfRange`), a fragment document (`DocumentIsFragment`), and a snapshot document that does not start with a document node (`MalformedSnapshot`).

Declarative shadow DOM written as `<template shadowrootmode>` in the source is consumed by Chrome, so a document parsed from the original bytes keeps the `template` element and is refused; parse the serialized DOM instead.

## Background samples

Chrome's snapshot carries no pixels. A caller who has colour summaries of the pixels behind elements supplies them as JSON (`BackgroundSamples.Parse`), and `RenderedFacts.WithBackgroundSamples` returns new facts with them attached (`NodeFacts.Background`); the original facts are unchanged.

```json
{
  "format": "onehtml-background-samples",
  "version": 1,
  "viewport": { "width": 1280, "height": 800 },
  "samples": [
    { "backendNodeId": 12, "median": "#003366", "p5": "rgb(0, 30, 80)", "p95": "#114477", "pixels": 4800 },
    { "snapshotNode": 31, "median": "rgba(10, 20, 30, 0.5)" }
  ]
}
```

- `format` and `version` are required; the reader refuses another version. Unknown members are ignored.
- `viewport` is optional; when both it and the facts' viewport are known and differ, `WithBackgroundSamples` throws `ArgumentException`.
- Each sample names its element by `backendNodeId` (preferred when both are given) or by `snapshotNode`, the node's index in the snapshot's main document. Entries that name no mapped element are reported in `BackgroundSampleApplication.Unmatched`. A later entry for the same element replaces an earlier one.
- `median`, `p5`, `p95` are per-channel median and 5th and 95th percentiles over the pixels behind the element's text, as `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `rgb(r, g, b)` or `rgba(r, g, b, a)`. `p5` and `p95` default to `median`. `pixels` (optional, ≥ 0) is the sample size.
- Limits: 64 MiB of input, 1 000 000 samples, JSON depth 16; violations throw `BackgroundSamplesFormatException`.

## What Chrome 156 does (observed on the fixture captures)

- The snapshot has **no shadow roots and no template content fragment**: form controls show no user-agent shadow tree and a `template` element has no children in the node table. The mapper still handles both if a capture has them (tested on synthetic snapshots).
- A **pseudo-element** (`::before`, `::after`, `::marker`) is an element node (`nodeType` 1, name `::before`) child of its host with `pseudoType` set. It has **two layout items under the same node index**: the element's box (no layout text), then an anonymous box carrying the generated text (`layoutText`) with the text box. The first becomes the generated box's own layout; the rest are its further boxes, and their text is the generated text.
- Every **text node** that is laid out has a layout item with `layoutText`; text boxes refer to it (`start` is relative to that text). Collapsed whitespace text can have a layout item with an empty rectangle.
- `offsetRects` are relative to the offset parent, `clientRects` are `[clientLeft, clientTop, clientWidth, clientHeight]`, `scrollRects` are `[scrollLeft, scrollTop, scrollWidth, scrollHeight]`; text items have `[]`. `bounds` are absolute document coordinates.
- `blendedBackgroundColors` is one string index per layout item, `-1` when the element has no background of its own; `textColorOpacities` is a number per item (0.9 inside an element with `opacity: .9`).
- `nodeName` is upper case for HTML elements (`DIV`), `#text`, `#document`; the doctype node (type 10) is named in lower case (`html`) and is absent for pages without a doctype.
- `position: sticky`, `fixed`, `opacity < 1` and `z-index` on positioned elements begin stacking contexts (`stackingContexts`).
- Frames: each `iframe` has a `contentDocumentIndex` entry, including empty and `display: none` frames; every frame document is its own `documents` entry.

## Testing

- `FakeSnapshot` (tests) writes snapshot-shaped JSON for a document with pseudo-elements, shadow trees, frames and template content, for cases a given capture does not have.
- `testdata/rendered/pages/` holds the fixture pages; `testdata/rendered/captures/` holds Chrome's output on them (snapshot, serialized DOM, browser version), and `CaptureTests` maps each and asserts key facts.
- Fuzz target `domsnapshot` (`fuzz/`): reader, adapter and background-sample reader; a successful mapping must account for every node.


<!-- https://recursiveai.org/onehtml/docs/checker/ -->

# The checker

`RecursiveAI.OneHtml.Accessibility.Validation` runs accessibility rules over a document and its accessibility tree and
returns labelled results. This page covers the API, how rules are selected, and how to add a private rule. The shape of
the results and the two JSON exports is in [results.md](https://recursiveai.org/onehtml/docs/results/); the rules that ship are in
[rules/aria.md](https://github.com/recursive-ai-oss/onehtml-csharp/blob/cecf589eb9acfc9e1fbc529486dfef519a32c19c/docs/rules/aria.md), [rules/names.md](https://github.com/recursive-ai-oss/onehtml-csharp/blob/cecf589eb9acfc9e1fbc529486dfef519a32c19c/docs/rules/names.md), [rules/structure.md](https://github.com/recursive-ai-oss/onehtml-csharp/blob/cecf589eb9acfc9e1fbc529486dfef519a32c19c/docs/rules/structure.md), [rules/tables.md](https://github.com/recursive-ai-oss/onehtml-csharp/blob/cecf589eb9acfc9e1fbc529486dfef519a32c19c/docs/rules/tables.md),
[rules/forms.md](https://github.com/recursive-ai-oss/onehtml-csharp/blob/cecf589eb9acfc9e1fbc529486dfef519a32c19c/docs/rules/forms.md), [rules/language.md](https://github.com/recursive-ai-oss/onehtml-csharp/blob/cecf589eb9acfc9e1fbc529486dfef519a32c19c/docs/rules/language.md), [rules/contrast.md](https://github.com/recursive-ai-oss/onehtml-csharp/blob/cecf589eb9acfc9e1fbc529486dfef519a32c19c/docs/rules/contrast.md), [rules/presentation.md](https://github.com/recursive-ai-oss/onehtml-csharp/blob/cecf589eb9acfc9e1fbc529486dfef519a32c19c/docs/rules/presentation.md),
[rules/media.md](https://github.com/recursive-ai-oss/onehtml-csharp/blob/cecf589eb9acfc9e1fbc529486dfef519a32c19c/docs/rules/media.md) and [rules/act-gaps.md](https://github.com/recursive-ai-oss/onehtml-csharp/blob/cecf589eb9acfc9e1fbc529486dfef519a32c19c/docs/rules/act-gaps.md) (with the per-rule ACT account in [act-coverage.md](https://recursiveai.org/onehtml/docs/act-coverage/)); the data about the standards they cite is in [catalogue.md](https://recursiveai.org/onehtml/docs/catalogue/).

## Running a check

```csharp
Document doc = Document.Parse(bytes);
var checker = new Checker();
CheckReport report = checker.Check(doc);                       // default cascade and style context
CheckReport focused = checker.Check(AccessibilityTree.Build(doc, styles, StyleContext.Default.WithFocus(button)));
```

`Checker.Check(Document)` builds the cascade and the tree itself. `Checker.Check(AccessibilityTree)` checks a tree you
built, under any style context. Both take a `CheckOptions` and a `CancellationToken`; the token is observed between
rules and every few hundred nodes inside a rule, and cancelling throws `OperationCanceledException`. Nothing else
leaves a public method except argument exceptions.

The library does not read files or the network. Linked stylesheets reach the cascade through the style options you pass
when you build the `DocumentStyles`, as everywhere else in the family.

## Selecting rules

`CheckOptions` has four selections. A rule runs only if it satisfies every selection that is not empty.

| Option | Selects |
|---|---|
| `Profile` | rules that check a criterion of the profile (`ValidationProfile.Wcag20AA`, `Wcag21AA`, `Wcag22AA`, `All`). A rule with no criterion (a best practice) belongs to `All` only. |
| `Tags` | rules carrying at least one of the tags (`cat.aria`, `best-practice`, `wcag2a`, …; axe's tags for axe rules). |
| `Criteria` | rules that check at least one criterion by number (`4.1.2`). |
| `RuleIds` | exactly these rules; an unknown id is an `ArgumentException`. |

`IncludePasses = false` drops passed results; `MaxResultsPerRule` (default 100,000) stops one rule from filling memory
on a hostile page. A rule that reaches it drops further results and `CheckReport.LimitReached` is set.

A profile names the standard that cites the criteria (Section 508 and WCAG 2.0 AA, ADA Title II, EN 301 549 and WCAG 2.1
AA); it selects rules and is not a statement about legal compliance.

## The report

`CheckReport.Results` is ordered by rule id (ordinal), then by the document order of the target, then by outcome
(failed, passed, needs-review, needs-render). A rule that found nothing to check contributes one `Inapplicable` result
with no target. The order does not depend on the order rules were registered in or on the number of threads. `WithOutcome`,
`Count`, `RulesRun`, `Tree`, `Document` and `StyleContext` are there for convenience.

`report.SuggestedEdits()` returns the suggested edits of all results as one edit-format envelope (`docs/edit-format.md`),
without duplicates, and `report.SuggestedEditList()` returns the same edits as `Edit` objects for `Document.Apply`. The
library never applies them. Each carries `meta`: `{ "rule": id, "criteria": [...], "suggested": true }`. `aria-valid-attr-value`, `aria-prohibited-attr` and `listitem` have no public fix: the correct edit depends on what the author meant (a mistyped value, a name meant for another element, a layout choice), so they report the problem and offer no suggestion.

## Private rules

A rule implements `IAccessibilityRule`:

```csharp
public interface IAccessibilityRule
{
    RuleDescriptor Descriptor { get; }   // id, sources, criteria, needs, fix or why none, tags
    string Description { get; }          // what the rule checks, one sentence
    string Help { get; }                 // how to fix a failure, one sentence
    Impact Impact { get; }               // minor, moderate, serious, critical
    void Evaluate(CheckContext context, RuleReporter reporter);
    RuleScope Scope => RuleScope.Unspecified;                       // optional: see "Re-checking after an edit"
    IReadOnlyCollection<string>? RelevantElements => null;          // optional, for page-level rules
}
```

`CheckContext` gives the `Document`, the `Styles` (the cascade), the `Tree`, the `StyleContext` and two helpers:
`Find(element)` (the tree node, or null when the element is not rendered) and `IsExposed(element)` (in the tree and not
hidden by `aria-hidden`, `inert` or `visibility`). The reporter has `Passed`, `Failed`, `NeedsReview` and
`NeedsRender`, each with a target and a sentence; `Failed` also takes findings and suggested edits, and `Suggest(edit,
description)` builds a suggested edit with the metadata filled in. Report in document order; the checker sorts anyway.

Register private rules with `new Checker(privateRules)`; their ids must differ from each other and from the built-in
ones (`ArgumentException` otherwise). `Checker.WithRules(rules)` makes a checker with only the rules given. Tags work
the same for private rules, so a consumer can mark its own with a tag and select them.

`Scope` and `RelevantElements` have default implementations, so a rule written before they existed still compiles and
behaves as before: it runs in full on every re-check. `CheckContext.Elements()` and `CheckContext.TreeNodes()` are the
elements and tree nodes a rule should iterate; in a re-check they are narrowed to the ones that need a second look.
`AllElements()` is the whole page, for a rule that needs to look beyond its targets to decide about one.

A rule must be deterministic, must not keep state between calls, must not recurse on the depth of the document, and
should observe `reporter.CancellationToken` in loops over the document.

## Task impact, context and facts

Each result says whether the problem can stand between a person and a task (`TaskImpact.BlocksTask`): the target is
focusable or has a widget role, or sits inside a `form`, a `dialog` or an `alertdialog` (element or role). The reason is
`interactive`, `form` or `dialog`. This is computed from the tree and does not depend on the rule.

`CssOnly` is true when the style context has interaction state (focus, hover, active, target). Script-driven states
are invisible to the library, so such results reflect the CSS alone.

Rules declare `RuleNeeds.Static` or `RuleNeeds.RenderedFacts`. Rendered facts reach the rules through
`CheckOptions.Facts` and `CheckContext.Facts` (null when the caller has none). They must have been captured for the
same `Document` object the tree was built from, or the checker throws `ArgumentException`. A rule that needs layout
decides from the facts when they are there and lists them in `FactsUsed`; when they are not, it either decides from the
cascade where nothing can move the text, or reports `NeedsRender` with the missing facts in `FactsMissing`, so the caller
knows what to capture. `label-content-name-mismatch` is the one rule of the names area that reads facts; the ARIA rules
and the rest of the names rules are static and leave both lists empty.

## Re-checking after an edit

A fixing loop is edit, check, keep or discard. `Checker.Recheck` makes the check after an edit cost what the edit
touched:

```csharp
EditResult edit = doc.Apply(edits);
RestyleResult restyle = styles.Restyle(edit);
AccessibilityTree updated = tree.Update(edit, restyle);
CheckReport next = checker.Recheck(previousReport, edit, restyle, updated);   // or the BatchResult overload
```

The result is equal to `checker.Check(updated, sameOptions)`: the same results, outcomes, messages, targets (handles into
the new snapshot, locators and byte ranges of the new source), suggested edits (aimed at the new snapshot) and order. The
report remembers the options it was made with. Only what an edit reached is re-run; everything else is carried over.
`report.Recheck` (a `RecheckInfo`) says how: whether it was incremental, how many rules ran in full, in part or were
carried over, and the number of nodes the edit reached.

**What an edit reaches.** A node is reached when any of these holds, comparing the old and new snapshots through the
edit's change set (`ChangeSet.MapToNew`):

- it was added, or the change set lists it as changed (attributes, text, children, parent);
- the restyle reports its style, or its pseudo-element styles, as possibly different;
- its accessibility-tree node was added or removed, or differs in anything a rule can read: role and how it was derived,
  name and description with their sources and the elements they came from, ignored status and reasons, hidden status and
  its origin, states, relations, focusability, parent in the tree, diagnostics. Position in the focus order is the one
  exception, because inserting one focusable shifts every later one; a rule that reads it must not declare a scope.

**Rule scopes.** A rule declares what its result for a target reads, with `RuleScope` flags. The checker widens the
reached nodes by those flags and runs the rule over the result only:

| Flag | The result also depends on | Widening |
|---|---|---|
| `Node` | the target's own attributes, text, style and tree node | none |
| `Descendants` | the target's DOM descendants | the DOM ancestors of every reached node |
| `Ancestors` | the target's DOM ancestors | the DOM descendants of every reached node |
| `Siblings` | the own attributes, text and tree node of the target's siblings | the siblings of every reached node, and all children of a parent that lost a child |
| `IdReferences` | elements it names by ID and elements that name it (`aria-labelledby`, `aria-describedby`, `aria-owns`, `aria-controls`, `aria-flowto`, `aria-details`, `aria-errormessage`, `aria-activedescendant`, `for`, `headers`, `form`, `list`, a `#fragment` in `href`), and a control and its `label` | the elements carrying an ID that a reached node has, had or names, the elements that name those IDs, and a label with the controls it labels |
| `Page` | the page as a whole (counts, first occurrence, one element) | the rule runs in full when the edit touched anything, or, if `RelevantElements` lists local names, when it touched an element of one of those names (a text node counts for its parent) |
| none (`Unspecified`) | anything | the rule runs in full on every re-check |

A scope is a promise, and a rule that declares one must keep three: each result is reported on the node whose inputs
the scope names (the checker drops a result reported anywhere else during a partial run); targets are found by iterating
`Elements()` or `TreeNodes()`, or by examining nodes independently of each other; and whatever the rule reads about
other nodes in order to decide (a count of elements with the same id, the set of ids that are referenced) is read
through `AllElements()` or the whole tree, never through the narrowed iteration. A scope may be wider than the truth,
never narrower. The equivalence tests in `RecheckEquivalenceTests` run random edit sequences and compare every re-check
with a fresh check, which is how a scope that is too narrow shows up.

**When the whole check runs again.** `Recheck` runs every rule in full, and `RecheckInfo.FullRunReason` says why, when:

- rendered facts take part: the previous report used some (an edit makes facts stale, so they are never carried over), or
  `facts` were passed for the edited document (the tree's own `Update` follows the same rule);
- the previous report dropped results at `MaxResultsPerRule`;
- the restyle was a full recompute, or the style context of the new tree differs from the old one.

A single rule runs in full when it declares no scope, when the nodes its scope reaches are more than 40% of the page's
elements, when a previous result cannot be remapped (a suggested edit whose target was removed, or a result with no
target), or when the merged results would pass `MaxResultsPerRule`. `ArgumentException` is thrown when the edit was not
applied to the previous report's document, the tree is not the edited document's, or the report came from a checker with
other rules.

**Scopes of the built-in rules.**

| Scope | Rules |
|---|---|
| `Node` | `aria-allowed-attr`, `aria-command-name`, `aria-conditional-attr`, `aria-deprecated-role`, `aria-dialog-name`, `aria-input-field-name`, `aria-meter-name`, `aria-progressbar-name`, `aria-prohibited-attr`, `aria-required-attr`, `aria-roles`, `aria-tab-name`, `aria-toggle-field-name`, `aria-tooltip-name`, `aria-treeitem-name`, `aria-valid-attr`, `autoplay-audio-control`, `blink`, `frame-focusable-content`, `image-alt`, `label-title-only`, `marquee`, `meta-viewport`, `meta-viewport-large`, `no-autoplay-audio`, `presentation-role-conflict` |
| `Node`, `Descendants` | `aria-braille-equivalent`, `aria-hidden-focus`, `aria-text`, `definition-list`, `list`, `nested-interactive`, `object-alt`, and the media review rules (`audio-alternative`, `audio-caption`, `autoplay-audio-duration`, `video-*`), which read the `track` children |
| `Node`, `Ancestors` | `area-alt`, `button-name`, `dlitem`, `empty-heading`, `frame-title`, `image-name-descriptive`, `input-button-name`, `input-image-alt`, `label`, `link-descriptive`, `link-in-context-descriptive`, `link-name`, `role-img-alt`, `select-name`, `server-side-image-map`, `summary-name`, `svg-img-alt` |
| `Node`, `Descendants`, `Ancestors` | `hidden-content` |
| `Node`, `Ancestors`, `Siblings` | `listitem` |
| `Node`, `Descendants`, `Ancestors`, `Siblings` | `aria-allowed-role` |
| `Node`, `Descendants`, `Ancestors`, `IdReferences` | `aria-required-children`, `aria-required-parent` |
| `Node`, `Ancestors`, `IdReferences` | `color-contrast`, `color-contrast-enhanced` (background paint follows the ancestor chain; disabled controls exempt the labels that name them) |
| `Node`, `IdReferences` | `aria-valid-attr-value`, `duplicate-id`, `duplicate-id-active`, `duplicate-id-aria`, `skip-link` |
| `Page` (`body`) | `aria-hidden-body` |
| `Page` (`html`, `title`) | `document-title`, `document-title-descriptive` |
| `Page` (`html`) | `html-has-lang`, `html-lang-matches-content`, `html-lang-valid`, `html-xml-lang-mismatch` |
| none | the landmark, heading-order, table, language-content, focus-order, group-comparison (`frame-title-unique`, `identical-links-*`, `accesskeys`) and layout-reading rules, and `focus-visible-indicator`, `scrollable-region-focusable`, `region`, `link-in-text-block`, `target-size`, `label-content-name-mismatch`, `p-as-heading`, `image-redundant-alt`, `image-of-text`, `image-decorative`, `label-descriptive`, `avoid-inline-spacing`, `css-orientation-lock`, `bypass`, `autocomplete-valid`, `tabindex`, `meta-refresh*` |

`focus-visible-indicator` compares the style of every element under a focus on each focusable element, so one edit can
change any of its results; it stays unscoped and dominates the time of a re-check on a page with many focusable elements.

**Cost.** The checker reads both trees once to find what changed, which is linear in the page and cheap next to the rules.
The rest is the unscoped rules, plus carrying the results of every scoped rule over: each carried result is rebuilt for the
new snapshot (target, byte range, task impact, suggested-edit targets), so a re-check allocates in proportion to the
number of results as well as to what changed. Measured rows are in `bench/README.md`.


<!-- https://recursiveai.org/onehtml/docs/results/ -->

# Results and exports

A `CheckReport` (see [checker.md](https://recursiveai.org/onehtml/docs/checker/)) holds `RuleResult`s. This page defines the result model and the two JSON
exports. Both exports are deterministic: the same report gives the same bytes on every platform. Both are written with
`System.Text.Json` writers; nothing uses reflection.

## The result model

| Member | Meaning |
|---|---|
| `Rule`, `RuleId` | the rule that produced it, with its descriptor |
| `Outcome` | `Failed`, `Passed`, `NeedsReview` (static facts cannot decide), `NeedsRender` (rendered facts are needed), `Inapplicable` |
| `Target` | the element (or text node); the null node for `Inapplicable` |
| `Locator` | a selector unique in the document (generated on first use; null when none exists) |
| `SourceBytes` | the byte range of the target's start tag in the input, or none |
| `Message`, `Findings` | one sentence; and the attributes and values found, in attribute order |
| `TaskImpact`, `TaskImpactReason` | `BlocksTask` with `interactive`, `form` or `dialog`, or `Cosmetic` |
| `CssOnly` | the style context had interaction state, so the result reflects the CSS alone |
| `FactsUsed`, `FactsMissing` | rendered facts a result used (for example `layout text`, `text boxes`); for `NeedsRender`, the facts to supply |
| `SuggestedEdits` | edits, only where the rule names exactly one judgement-free fix |

Labels live on the rule: `Rule.Descriptor` has the sources (ACT id, axe id, failure technique, or ours), the criteria
(number, name, level, version introduced), `BestPractice`, `Needs`, the fix or the reason there is none, and tags; the rule
also has a description, a help sentence and an impact. Descriptions and help texts are written for this library.

A suggested edit is a normal `Edit` against the checked snapshot, carrying `meta` with the rule id, the criteria and
`"suggested": true`. Applying one is the caller's choice; `Document.Apply` and replay both accept them. `aria-valid-attr-value`, `aria-prohibited-attr` and `listitem` have no public fix: the correct edit depends on what the author meant (a mistyped value, a name meant for another element, a layout choice), so they report the problem and offer no suggestion.

## Native JSON: `onehtml-results` version 1

Top level, in this order:

| Field | Value |
|---|---|
| `format` | `"onehtml-results"` |
| `version` | `1`. A change that alters the meaning of a field raises it; new fields do not. Readers ignore unknown fields. |
| `document` | `{ "sha256": hex of the input bytes, "url": as given in the export options (omitted when none) }` |
| `styleContext` | `viewportWidth`, `viewportHeight`, `media` (`screen`/`print`), `colorScheme`, `reducedMotion`, `contrast`, `forcedColors`, `cssOnly`, and `focus`, `hover`, `active`, `target` (locators) when set |
| `profile` | the profile name (`wcag-2.1-aa`, `all`, …) or `null` |
| `limitReached` | a rule dropped results at `MaxResultsPerRule` |
| `rules` | the rules that ran, in id order: `id`, `description`, `help`, `impact`, `bestPractice`, `needs` (`static`/`rendered-facts`), `sources` (`kind`: `act`/`axe`/`failure-technique`/`own`, `id`), `criteria` (`number`, `handle`, `level`, `version`), `tags`, `fix`, `noFixReason` |
| `results` | see below |
| `suggestedEdits` | one edit-format envelope (`docs/edit-format.md`) holding every distinct suggested edit, so replay needs one document |

Each result: `rule`, `outcome` (`failed`, `passed`, `needs-review`, `needs-render`, `inapplicable`), `message`, `target`
(`null`, or `tag`, `locator`, `source` with byte `start` and `end`), `findings` (`attribute`, `value`, `message`),
`taskImpact` (`blocksTask`, `reason`), `cssOnly`, `factsUsed`, `factsMissing`, and `suggested`: a list of
`{ "description", "edit": n }` where `n` indexes `suggestedEdits.edits`. Results keep the report order: rule id, document
order of the target, outcome.

Strings are UTF-8 JSON with the characters `<`, `>`, `&` and `'` unescaped (the output is not meant to be embedded in
HTML). Numbers are integers except the viewport size.

## Axe-compatible JSON

The shape follows the results object that axe-core's public API documentation describes: `violations`, `passes`,
`incomplete` and `inapplicable`, each a list of rule results with `id`, `impact`, `tags`, `description`, `help`,
`helpUrl` and `nodes`; each node with `html`, `impact`, `target`, `any`, `all`, `none` and, for failures,
`failureSummary`. Top-level `testEngine`, `testRunner`, `testEnvironment` and `toolOptions` are present; `url` is present
when given.

The mapping is lossy, and these are its rules:

| Ours | Axe-compatible |
|---|---|
| failed | `violations` |
| passed | `passes` |
| needs-review, needs-render | `incomplete`; the node's `onehtml.outcome` says which |
| inapplicable | `inapplicable` (a rule with no target) |
| rule id | the axe id where an axe rule is a counterpart; ours otherwise, with our tags |
| rule impact | the rule's impact on violation and incomplete nodes; `null` on passes and inapplicable |
| `target` | `[locator]` (one selector; no frames or shadow roots) |
| `html` | the target's start tag as written in the source, cut to `MaxHtmlLength` (300) characters; axe gives the serialised element |
| `any`/`all`/`none` | a failure or incomplete node has one check in `any` (id = rule id, `data` = findings, `message`); `all` and `none` are empty. Passed nodes have empty arrays. Our rules are not built from axe's checks, so nothing finer is available. |
| `failureSummary` | the result message and the findings' messages on separate lines (our wording, not axe's) |
| `helpUrl` | the Deque University page of the axe version for rules with an axe source; empty otherwise |
| `description`, `help` | our own sentences |
| not exported | `timestamp` (it would make the output differ between runs), `relatedNodes` (always empty), frame and shadow paths |
| added | per node, `onehtml`: `outcome`, `blocksTask`, `cssOnly`, `factsMissing`, `suggestedEdits` (count) |

A rule appears once per group it has results in; a rule with failures and passes is in both `violations` and `passes`.
Within a group rules are in id order and nodes in document order.

## SARIF

`ToSarifJson` writes SARIF 2.1.0; the mapping is in `sarif.md`.

## Not provided yet

An EARL export. There is no reader for the native JSON; consumers read it with any JSON parser, and the edit
envelopes inside it are read with `EditJson.Parse`.


<!-- https://recursiveai.org/onehtml/docs/sarif/ -->

# SARIF export

`ToSarifJson` (an extension on `CheckReport`, in `SarifExport`) writes the report as SARIF 2.1.0, the OASIS Static
Analysis Results Interchange Format (Errata 01). The mapping is version 1 (`SarifExport.ExportVersion`, written to the
run's `properties.exportVersion`); a change that alters meaning raises it. The output is deterministic, uses
`System.Text.Json` writers only, and validates against the schema published with the standard
(`testdata/sarif/sarif-schema-2.1.0.json`, checked by the Validation tests for every golden page).

```csharp
string sarif = report.ToSarifJson(new ExportOptions { Url = "https://example.test/page.html", Indented = true });
```

## Options

`ExportOptions` is shared with the other exports.

| Option | Use in SARIF |
|---|---|
| `Url` | the artifact address, written to `artifactLocation.uri`; percent-encoded where it is not a legal URI reference. When absent, `urn:onehtml:document:sha256:<hash of the bytes>` |
| `Indented` | indented output |
| `MaxHtmlLength` | the longest region snippet, in characters (default 300) |
| `IncludePassed` | also write passed results (`kind: pass`); default off, since a pass is not a finding |
| `IncludeInapplicable` | also write one `notApplicable` result per rule that found nothing to check; default off |

## Run

One run. `tool.driver` is `RecursiveAI.OneHtml.Accessibility.Validation` with its semantic version; `columnKind` is
`utf16CodeUnits`. One artifact: the checked document, with its `uri`, `mimeType` `text/html`, byte `length`,
`sourceLanguage` `html`, the `encoding` it was decoded with and its `sha-256`. The run has one invocation, successful;
when a rule reached `CheckOptions.MaxResultsPerRule` it also carries a warning notification `limit-reached`. Run
`properties`: `exportVersion`, `profile` (the profile name or null) and `cssOnly` (the style context had interaction
state).

## Results

| Our outcome | `kind` | `level` | Written |
|---|---|---|---|
| failed | `fail` | from the rule's impact: critical and serious `error`, moderate `warning`, minor `note` | always |
| needs-review | `review` | `none` | always |
| needs-render | `review` | `none` | always |
| passed | `pass` | `none` | with `IncludePassed` |
| inapplicable | `notApplicable` | `none` | with `IncludeInapplicable` |

SARIF (3.27.9) requires level `none` on any result whose kind is not `fail`, which is why a review result carries no
severity; its `rank` (below) and its `properties.outcome` (`needs-review` or `needs-render`) tell a consumer how to
treat it. A consumer that filters by level alone will therefore not see review results; filter on `kind` as well.

Every result has `ruleId` and `ruleIndex`, `message.text` (the result's sentence), and, for fail and review results,
`rank` from the impact (critical 90, serious 70, moderate 50, minor 30). Results are in report order: rule id, then
target in document order.

**Locations.** A result with a target that has a source range gets one location. Results without one (the target is
parser-made and has no bytes, or the outcome is inapplicable) have no `locations`. The region is the target's source
range as the source map has it: an element's start tag, or the construct itself for a text node, comment or doctype. A
start tag the parser implied has an empty region at the token that caused it.

| Region member | Value |
|---|---|
| `startLine`, `startColumn`, `endLine`, `endColumn` | 1-based; columns count UTF-16 code units of the decoded file from the start of the line; the end is the position after the last character, as SARIF defines it |
| `byteOffset`, `byteLength` | offsets into the file's bytes, counting any byte order mark; authoritative for any encoding |
| `snippet.text` | the region's text, cut to `MaxHtmlLength` characters |

Lines end at LF, CR LF or a lone CR. A byte order mark is not counted in any column. Columns count characters of the
file as decoded with the encoding the library chose (byte order mark, then the transport label, then the `<meta>`
prescan, then the default of windows-1252), so they are right for Shift_JIS, windows-1252 and UTF-16 files as well as
UTF-8, and an astral character counts two. Character offsets (`charOffset`, `charLength`) are not written: the
library's decoded text has CR LF and lone CR turned into LF, as HTML parsing requires, so its offsets differ from the
file's. For the same reason a snippet of a start tag that spans lines has LF line ends even when the file uses CR LF.

`logicalLocations` has the target's tag name (`#text` for text), its locator as `fullyQualifiedName`, and kind `element`
or `text`. `partialFingerprints["onehtml/v1"]` is the first 32 hex digits of the SHA-256 of the rule id, a line feed and
the locator (the start offset when there is none); it is stable while the element keeps its place in the document.
`properties` has `outcome`, `locator`, `blocksTask`, `taskImpactReason`, `cssOnly`, `findings`, `factsUsed` and
`factsMissing`, as in the native export.

## Rules

`tool.driver.rules` lists every rule that ran, in id order (`ruleIndex` is the position).

| SARIF member | From |
|---|---|
| `id` | the rule id |
| `shortDescription` | the rule's description |
| `fullDescription` | the description, the success criteria it is relevant to with level and WCAG version (or that it is a best practice no criterion requires), and whether it needs rendered facts |
| `help` | the help sentence, then the suggested edit the rule names or why it has none (for example `aria-valid-attr-value`, `aria-prohibited-attr` and `listitem` always say why they have none) |
| `helpUri` | the ACT rule page if the rule has an ACT source, else the Deque University page of the pinned axe version if it has an axe source, else none |
| `defaultConfiguration` | `enabled`, `level` and `rank` from the impact, as for results |
| `relationships` | one per success criterion, kind `relevant`, targeting the WCAG taxon by `id` and `index` |
| `properties` | `tags` (the rule's tags), `impact`, `bestPractice`, `needs`, `sources` (kind and id: ACT, axe, failure technique, own), `criteria` (number, level, version), `fix`, `noFixReason` |

**Taxonomy.** `run.taxonomies` has one component, `WCAG` (W3C, version 2.2, `isComprehensive` false), whose taxa are the
success criteria that some rule that ran is relevant to, in number order. A taxon has the criterion number as `id`, its
handle as `name`, a `helpUri` to the Understanding page (the WCAG 2.1 pages for 4.1.1, which 2.2 removed), and
`properties`: `level`, `introducedIn`, `removedIn`. A rule maps to a criterion with kind `relevant` because a rule
usually checks one failure condition of a criterion, not the whole criterion.

## Fixes

A failed result with suggested edits has one SARIF `fix` per edit, with the edit's description. The replacements are not
translated from the edit; they are read from running it: the library applies the edit alone to the checked document
(`Document.Apply`, with its re-parse verification) and writes each changed byte range as a replacement. So
applying the replacements to the original bytes gives exactly the bytes `Apply` produces, and nothing outside the edited
ranges changes (a test checks this on every suggested edit of the golden pages and on edited documents in UTF-8,
windows-1252 and Shift_JIS).

- `deletedRegion` has the range's `byteOffset`/`byteLength` and its line and column members; an insertion has length 0.
- `insertedContent` is absent for a deletion. It is `text` when the inserted bytes are valid UTF-8 in a UTF-8 document or
  plain ASCII in an ASCII-compatible one, and otherwise `binary` (base64 of the exact bytes in the document's encoding).
  In UTF-16 and ISO-2022-JP documents it is always `binary`.
- Replacements are in ascending offset order and do not overlap.
- If an edit cannot be applied, which would be a library fault, the result carries no `fix` for it.

Each fix costs one `Apply` (about one parse of the document), cached per distinct edit. The library never applies a fix.

## What is not exported

EARL, which is a separate export. The native export's style context and suggested-edit envelope have no SARIF counterpart.


<!-- https://recursiveai.org/onehtml/docs/catalogue/ -->

# Rule catalogue data

The Validation package ships reference data about the standards its rules check against, and a few types to hang rule
implementations on. This page lists the data, where each file comes from, and how a rule is added.
The criterion-by-rule table is in [coverage.md](https://recursiveai.org/onehtml/docs/coverage/).

## Data files

All files are JSON in `src/OneHtml.Accessibility.Validation/Catalogue/Data/`, embedded in the assembly, with a top-level
`version` (currently `1`) and a `source` block (URL, SHA-256 of the input, retrieval date, notes). They are generated
by `tools/catalogue/generate.py` from inputs that `tools/catalogue/sources.py` downloads and hash-checks; running the
generator twice gives identical bytes. The library reads them through a small `System.Text.Json` document reader: no
reflection, trim- and AOT-safe. The library does not fetch anything.

| File | Contents | Source and pin | Count |
|---|---|---|---|
| `wcag-criteria.json` | number, anchor id, published short name, level, version introduced, version removed | W3C `https://www.w3.org/WAI/WCAG22/wcag.json`, SHA-256 `3a034865…cf75`, retrieved 2026-10-25 | 87 criteria |
| `act-rules.json` | id, name, status, type, WCAG criteria, techniques, other requirements, input aspects, input rules | `w3c/wcag-act-rules` `wcag-mapping.json` at commit `a7a18b1d…`, SHA-256 `5d111710…c4f5` | 94 rules |
| `axe-rules.json` | rule id, section, impact, tags, result kinds, linked ACT rules | axe-core 4.14.0 published `doc/rule-descriptions.md`, SHA-256 `635ad70e…f261` | 105 rules |

### WCAG criteria

- WCAG 2.0 has 61 criteria (25 A, 13 AA, 23 AAA), 2.1 has 78 (30, 20, 28) and 2.2 has 86 (31, 24, 31).
  The table has 87 rows because 4.1.1 Parsing is in 2.0 and 2.1 and was removed in 2.2 (`removedIn` is `2.2`).
- The published data leaves the level of 4.1.1 empty and adds a note to its name. The generator sets level A and the
  name `Parsing`, as the 2.0 and 2.1 Recommendations define it.
- A criterion belongs to a version when `introducedIn <= version < removedIn`.

### ACT rules

- Status is `deprecated` when the W3C list flags the rule deprecated, `proposed` when it flags it proposed, otherwise
  `approved`. Today: 37 approved, 50 proposed, 7 deprecated.
- `criteria` are the WCAG criteria in the rule's requirements (the `wcag20:`, `wcag21:` and `wcag22:` keys).
  `techniques` are the `wcag-technique:` keys; `otherRequirements` keeps the rest (for example `aria12:…`) as published.
- `inputAspects` are normalised to DOM Tree, CSS Styling, Accessibility Tree, Language, Audio output, Visual output and
  Source code. Composite rules list `inputRules` instead of aspects.
- The ACT test cases are in `testdata/act/`: the index `testcases.json` (1134 cases for 91 rules) and the case files. [act-coverage.md](https://recursiveai.org/onehtml/docs/act-coverage/) lists every ACT rule with the rule that implements it, or the reason none does, and how its cases came out.
  Their SHA-256 values are in `testdata/SHA256SUMS`, and a test checks them. `ActTestCases.Parse` reads the index text
  the caller supplies. Media and other assets that cases refer to are not copied (see `testdata/MANIFEST.md`).

### axe-core identifiers

- Only facts are taken from the published table: identifiers, tags, impact, result kinds and links to ACT rules. No
  description or help text is copied, and none is stored; add our own wording when a rule is implemented.
- Sections: 60 WCAG 2.0 A/AA, 3 WCAG 2.1 A/AA, 1 WCAG 2.2 A/AA, 3 WCAG 2.x AAA, 27 best practice, 6 experimental and
  5 deprecated rules.
- A tag `wcagNNN` names a criterion: principle and guideline are one digit each, so `wcag1410` is 1.4.10 and `wcag143`
  is 1.4.3. Level tags (`wcag2a`, `wcag21aa`, …) name a version and level. `AxeRule.CriterionNumbers` and
  `AxeRule.LevelTags` do both.

## Types

In `RecursiveAI.OneHtml.Accessibility.Validation.Catalogue`:

- `SuccessCriterion`, `WcagVersion`, `WcagLevel`, `WcagCriteria` (the table, lookups by number).
- `ActRule`, `ActRuleStatus`, `ActRules`, `ActTestCase`, `ActTestCases`.
- `AxeRule`, `AxeRules`.
- `RuleSource` (ACT id, axe id, failure technique or ours), `RuleNeeds` (`Static` or `RenderedFacts`) and
  `RuleDescriptor` (id, sources, criteria, best-practice flag, needs, fix or the reason there is none, tags).
- `ValidationProfile`: `Wcag20AA`, `Wcag21AA`, `Wcag22AA` and `All`.
- `CoverageMatrix.ToMarkdown()`, which writes `docs/coverage.md`.

### Profiles

A profile for version V and level L includes the criteria that are in V (introduced at or before V and not removed by
it) and have a level at or below L. So 2.1 AA includes the 2.0 criteria that 2.1 kept, and 2.2 AA leaves out 4.1.1.
The names cite standards (Section 508 cites WCAG 2.0 AA; ADA Title II and EN 301 549 cite WCAG 2.1 AA); a profile is a
selection of criteria, not a claim about legal compliance. `All` includes every criterion, the removed one too, and
every best practice. A rule is in a profile when any criterion it checks is; a rule with no criteria is in `All` only.

| Profile | Criteria |
|---|---|
| `wcag-2.0-aa` | 38 |
| `wcag-2.1-aa` | 50 |
| `wcag-2.2-aa` | 55 |
| `all` | 87 |

## Adding a rule

1. Give the rule a stable id (axe's id when an axe rule is its counterpart) and a `RuleDescriptor`: every source it has,
   the criteria by number (the constructor rejects unknown numbers), `BestPractice` for rules with no criterion,
   `Needs` (`RenderedFacts` when layout or painting is required), and either a `Fix` (exactly one judgement-free
   edit) or a `NoFixReason`. Write the description in our own words.
2. If it has an ACT source, its id must exist in `act-rules.json`; the ACT cases in `testdata/act/` are its acceptance
   tests.
3. Implement `IAccessibilityRule` with that descriptor and add it to `BuiltInRules` (see [checker.md](https://recursiveai.org/onehtml/docs/checker/); the ARIA
   rules are in [rules/aria.md](https://github.com/recursive-ai-oss/onehtml-csharp/blob/cecf589eb9acfc9e1fbc529486dfef519a32c19c/docs/rules/aria.md)).
4. Refresh `docs/coverage.md` with `ONEHTML_UPDATE_DOCS=1` when running the Validation tests.

## Refreshing the data

```
python3 tools/catalogue/sources.py <cache-dir> [--act-testcases]   # download, check against the pins
python3 tools/catalogue/generate.py <cache-dir>                    # rewrite Catalogue/Data/*.json
```

To move to a newer source, change the pin in `sources.py`, run both, and review the diff of the data files and
`coverage.md`.


<!-- https://recursiveai.org/onehtml/docs/act-coverage/ -->

# ACT rule coverage

Generated by `ActCoverageTests`; do not edit by hand. To refresh it after a rule or an expectation changes, run the
Validation tests with `ONEHTML_UPDATE_DOCS=1`. The rule list and its status come from `Catalogue/Data/act-rules.json`
(see `catalogue.md`); the cases are the W3C test cases vendored under `testdata/act/`.

Columns: *Our rules* are the rules of this package that take the ACT rule as a source (or that the ACT harness runs
for it). The case columns count the vendored cases of the rule: *pass* the rule gave the expected outcome, *review*
the rule asks a person (needs-review) where ACT expects passed or failed, which is the honest answer for a judgement
rule, *n/a* cases a static check cannot judge (each is listed with its reason in the `testdata/act/*-expectations.tsv`
files), and *fail* cases where the rule disagrees with ACT. *Fail* is 0 everywhere; ACT wins disagreements.

- Approved: 37 rules, 37 implemented.
- Proposed: 50 rules, 36 implemented, 14 not automatable or not implemented (reason in the table).
- Deprecated: 7 rules, 4 implemented, 3 not automatable or not implemented (reason in the table).

| ACT id | Name | Status | Our rules | Cases | pass | review | n/a | fail |
|---|---|---|---|---|---|---|---|---|
| 09o5cg | Text has enhanced contrast | approved | `color-contrast-enhanced` | 29 | 25 | 0 | 4 | 0 |
| 0ssw9k | Scrollable content can be reached with sequential focus navigation | approved | `scrollable-region-focusable` | 10 | 6 | 0 | 4 | 0 |
| 0va7u6 | HTML images contain no text | approved | `image-of-text` | 14 | 2 | 12 | 0 | 0 |
| 23a2a8 | Image has non-empty accessible name | approved | `image-alt`, `role-img-alt`, `svg-img-alt` | 18 | 18 | 0 | 0 | 0 |
| 24afc2 | Important letter spacing in style attributes is wide enough | approved | `avoid-inline-spacing` | 16 | 16 | 0 | 0 | 0 |
| 2779a5 | HTML page has non-empty title | approved | `document-title` | 11 | 10 | 0 | 1 | 0 |
| 2t702h | Summary element has non-empty accessible name | approved | `summary-name` | 0 | | | | |
| 307n5z | Element with presentational children has no focusable content | approved | `nested-interactive` | 7 | 7 | 0 | 0 | 0 |
| 46ca7f | Element marked as decorative is not exposed | approved | `presentation-role-conflict` | 10 | 10 | 0 | 0 | 0 |
| 4e8ab6 | Element with role attribute has required states and properties | approved | `aria-required-attr` | 8 | 8 | 0 | 0 | 0 |
| 59796f | Image button has non-empty accessible name | approved | `input-image-alt` | 12 | 12 | 0 | 0 | 0 |
| 5f99a7 | ARIA attribute is defined in WAI-ARIA | approved | `aria-valid-attr` | 7 | 7 | 0 | 0 | 0 |
| 674b10 | Role attribute has valid value | approved | `aria-roles` | 10 | 10 | 0 | 0 | 0 |
| 6a7281 | ARIA state or property has valid value | approved | `aria-valid-attr-value` | 24 | 24 | 0 | 0 | 0 |
| 6cfa84 | Element with aria-hidden has no content in sequential focus navigation | approved | `aria-hidden-focus` | 14 | 13 | 0 | 1 | 0 |
| 73f2c2 | Autocomplete attribute has valid value | approved | `autocomplete-valid` | 20 | 20 | 0 | 0 | 0 |
| 78fd32 | Important line height in style attributes is wide enough | approved | `avoid-inline-spacing` | 21 | 14 | 0 | 7 | 0 |
| 7d6734 | SVG element with explicit role has non-empty accessible name | approved | `svg-img-alt` | 10 | 10 | 0 | 0 | 0 |
| 8fc3b6 | Object element rendering non-text content has non-empty accessible name | approved | `object-alt` | 14 | 14 | 0 | 0 | 0 |
| 97a4e1 | Button has non-empty accessible name | approved | `aria-command-name`, `button-name`, `input-button-name` | 17 | 17 | 0 | 0 | 0 |
| 9e45ec | Important word spacing in style attributes is wide enough | approved | `avoid-inline-spacing` | 16 | 16 | 0 | 0 | 0 |
| a25f45 | Headers attribute specified on a cell refers to cells in the same table element | approved | `td-headers-attr` | 17 | 16 | 0 | 1 | 0 |
| afw4f7 | Text has minimum contrast | approved | `color-contrast` | 28 | 24 | 0 | 4 | 0 |
| akn7bn | Iframe with interactive elements is not excluded from tab-order | approved | `frame-focusable-content` | 6 | 5 | 0 | 1 | 0 |
| b33eff | Orientation of the page is not restricted using CSS transforms | approved | `css-orientation-lock` | 10 | 10 | 0 | 0 | 0 |
| b4f0c3 | Meta viewport allows for zoom | approved | `meta-viewport` | 11 | 11 | 0 | 0 | 0 |
| b5c3f8 | HTML page has lang attribute | approved | `html-has-lang` | 7 | 5 | 0 | 2 | 0 |
| bc659a | Meta element has no refresh delay | approved | `meta-refresh` | 15 | 15 | 0 | 0 | 0 |
| bf051a | HTML page lang attribute has valid language tag | approved | `html-lang-valid` | 7 | 7 | 0 | 0 | 0 |
| bisz58 | Meta element has no refresh delay (no exception) | approved | `meta-refresh-no-exceptions` | 14 | 14 | 0 | 0 | 0 |
| c487ae | Link has non-empty accessible name | approved | `area-alt`, `aria-command-name`, `link-name` | 28 | 28 | 0 | 0 | 0 |
| c4a8a4 | HTML page title is descriptive | approved | `document-title-descriptive` | 6 | 1 | 5 | 0 | 0 |
| de46e4 | Element with lang attribute has valid language tag | approved | `valid-lang` | 19 | 19 | 0 | 0 | 0 |
| e086e5 | Form field has non-empty accessible name | approved | `aria-input-field-name`, `aria-toggle-field-name`, `label`, `select-name` | 17 | 17 | 0 | 0 | 0 |
| m6b1q3 | Menuitem has non-empty accessible name | approved | `aria-command-name` | 8 | 8 | 0 | 0 | 0 |
| oj04fd | Element in sequential focus order has visible focus | approved | `focus-visible-indicator` | 9 | 8 | 0 | 1 | 0 |
| qt1vmo | Image accessible name is descriptive | approved | `image-name-descriptive` | 16 | 10 | 6 | 0 | 0 |
| 047fe0 | Document has heading for non-repeated content | proposed | not automatable — its verdict depends on which content repeats across the pages of a site; one page cannot say (bypass answers the page-level question of cf77f2) | 14 | | | | |
| 1a02b0 | Audio and visuals of video element have transcript | proposed | `video-transcript` | 5 | 1 | 4 | 0 | 0 |
| 1ea59c | Video element visual content has audio description | proposed | `video-audio-description` | 7 | 1 | 6 | 0 | 0 |
| 1ec09b | Video element visual content has strict accessible alternative | proposed | `video-strict-alternative` | 7 | 1 | 6 | 0 | 0 |
| 2eb176 | Audio element content has transcript | proposed | `audio-caption` | 11 | 1 | 10 | 0 | 0 |
| 2ee8b8 | Visible label is part of accessible name | proposed | `label-content-name-mismatch` | 13 | 12 | 0 | 1 | 0 |
| 36b590 | Error message describes invalid form field value | proposed | not automatable — the error indicators of a form field (wording, icons, colour, position) are presentation with no markup that names them, so no element set can be offered for review | 9 | | | | |
| 3e12e1 | Block of repeated content is collapsible | proposed | not automatable — its verdict depends on which content repeats across pages and on what a script does to collapse it | 8 | | | | |
| 4b1c6c | Iframe elements with identical accessible names have equivalent purpose | proposed | `frame-title-unique` | 23 | 12 | 9 | 2 | 0 |
| 4c31df | Audio or video element that plays automatically has a control mechanism | proposed | `autoplay-audio-control` | 11 | 4 | 7 | 0 | 0 |
| 59br37 | Zoomed text node is not clipped with CSS overflow | proposed | not automatable — it needs the text laid out at 200% zoom to see whether an overflow clips it; there is no layout without a browser | 14 | | | | |
| 5c01ea | ARIA state or property is permitted | proposed | `aria-allowed-attr`, `aria-conditional-attr`, `aria-prohibited-attr` | 15 | 15 | 0 | 0 | 0 |
| 5effbb | Link in context is descriptive | proposed | `link-in-context-descriptive` | 18 | 3 | 15 | 0 | 0 |
| 7677a9 | Device motion based changes to the content can also be created from the user interface | proposed | not automatable — it depends on what a script does with device-motion events; scripts are inert text here | 6 | | | | |
| 80af7b | Focusable element has no keyboard trap | proposed | not automatable — it depends on running focus and key handlers; a keyboard trap is made by script | 16 | | | | |
| 80f0bf | Audio or video element avoids automatically playing audio | proposed | `no-autoplay-audio` | 8 | 3 | 5 | 0 | 0 |
| 9bd38c | Content has alternative for visual reference | proposed | not automatable — it asks whether instructions rely only on shape, size, position or colour; that is a judgement about the wording of the content, with no element to point at | 21 | | | | |
| a1b64e | Focusable element has no keyboard trap via standard navigation | proposed | not automatable — it depends on running focus and key handlers; a keyboard trap is made by script | 10 | | | | |
| aaa1bf | Audio or video element that plays automatically has no audio that lasts more than 3 seconds | proposed | `autoplay-audio-duration` | 7 | 2 | 5 | 0 | 0 |
| ab4d13 | Video element content is media alternative for text | proposed | `video-media-alternative` | 7 | 1 | 6 | 0 | 0 |
| afb423 | Audio element content is media alternative for text | proposed | `audio-caption` | 7 | 1 | 6 | 0 | 0 |
| aizyf1 | Link is descriptive | proposed | `link-descriptive` | 12 | 3 | 9 | 0 | 0 |
| b20e66 | Links with identical accessible names have equivalent purpose | proposed | `identical-links-same-purpose` | 21 | 6 | 14 | 1 | 0 |
| b40fd1 | Document has a landmark with non-repeated content | proposed | not automatable — its verdict depends on which content repeats across the pages of a site; one page cannot say | 8 | | | | |
| b49b2e | Heading is descriptive | proposed | `heading-descriptive` | 17 | 4 | 13 | 0 | 0 |
| bc4a75 | ARIA required owned elements | proposed | `aria-required-children` | 19 | 19 | 0 | 0 | 0 |
| c249d5 | Device motion based changes to the content can be disabled | proposed | not automatable — it depends on what a script does with device-motion events; scripts are inert text here | 5 | | | | |
| c3232f | Video element visual-only content has accessible alternative | proposed | `video-only-alternative` | 9 | 1 | 8 | 0 | 0 |
| c5a4ea | Video element visual content has accessible alternative | proposed | `video-visual-alternative` | 9 | 1 | 8 | 0 | 0 |
| cae760 | Iframe element has non-empty accessible name | proposed | `frame-title` | 10 | 10 | 0 | 0 | 0 |
| cc0f0a | Form field label is descriptive | proposed | `label-descriptive` | 14 | 2 | 11 | 1 | 0 |
| cf77f2 | Bypass Blocks of Repeated Content | proposed | `bypass` | 14 | 9 | 0 | 5 | 0 |
| d0f69e | Table header cell has assigned cells | proposed | `th-has-data-cells` | 16 | 16 | 0 | 0 | 0 |
| d7ba54 | Video element visual-only content has audio track alternative | proposed | `video-only-audio-track` | 5 | 1 | 4 | 0 | 0 |
| e7aa44 | Audio element content has text alternative | proposed | `audio-alternative` | 8 | 2 | 6 | 0 | 0 |
| e88epe | Image not in the accessibility tree is decorative | proposed | `image-decorative` | 20 | 7 | 10 | 3 | 0 |
| eac66b | Video element auditory content has accessible alternative | proposed | `video-caption` | 6 | 1 | 5 | 0 | 0 |
| ebe86a | Focusable element has no keyboard trap via non-standard navigation | proposed | not automatable — it depends on running focus and key handlers; a keyboard trap is made by script | 7 | | | | |
| ee13b5 | Video element visual-only content has transcript | proposed | `video-only-transcript` | 8 | 1 | 7 | 0 | 0 |
| efbfc7 | Text content that changes automatically can be paused, stopped or hidden | proposed | not automatable — it depends on timing, scripts and animation to know that text changes by itself | 11 | | | | |
| f51b46 | Video element auditory content has captions | proposed | `video-captions` | 8 | 1 | 7 | 0 | 0 |
| fd26cf | Video element visual-only content is media alternative for text | proposed | `video-only-media-alternative` | 7 | 1 | 6 | 0 | 0 |
| fd3a94 | Links with identical accessible names and same context serve equivalent purpose | proposed | `identical-links-same-context` | 19 | 8 | 11 | 0 | 0 |
| ff89c9 | ARIA required context role | proposed | `aria-required-parent` | 15 | 13 | 0 | 2 | 0 |
| ffbc54 | No keyboard shortcut uses only printable characters | proposed | not automatable — it depends on the key handlers a script installs | 10 | | | | |
| ffd0e9 | Heading has non-empty accessible name | proposed | `empty-heading` | 15 | 14 | 0 | 1 | 0 |
| kb1m8s | ARIA global properties not used where prohibited | proposed | `aria-prohibited-attr` | 0 | | | | |
| off6ek | HTML element language subtag matches language | proposed | `element-lang-matches-content` | 14 | 12 | 0 | 2 | 0 |
| ucwvc8 | HTML page language subtag matches default language | proposed | `html-lang-matches-content` | 15 | 14 | 0 | 1 | 0 |
| ye5d6e | Document has an instrument to move focus to non-repeated content | proposed | not automatable — its verdict depends on which content repeats across the pages of a site; one page cannot say | 12 | | | | |
| 3ea0c8 | Id attribute value is unique | deprecated | `duplicate-id`, `duplicate-id-active`, `duplicate-id-aria` | 10 | 10 | 0 | 0 | 0 |
| 5b7ae0 | HTML page lang and xml:lang attributes have matching values | deprecated | `html-xml-lang-mismatch` | 12 | 11 | 0 | 1 | 0 |
| 9eb3f6 | Image filename is accessible name for image | deprecated | not implemented — deprecated by the ACT task force; a file name is not an accessible name | 15 | | | | |
| ac7dc6 | Video element visual-only content has description track | deprecated | `video-only-description-track` | 5 | 1 | 4 | 0 | 0 |
| e6952f | Attribute is not duplicated | deprecated | not implemented — duplicate attributes are dropped by the parser; only a document parsed with errors recorded could report them | 10 | | | | |
| f196ce | Video element visual content has description track | deprecated | `video-description-track` | 5 | 1 | 4 | 0 | 0 |
| in6db8 | ARIA required ID references exist | deprecated | not implemented — deprecated by the ACT task force; the check lives on in aria-valid-attr-value (6a7281) | 0 | | | | |


<!-- https://recursiveai.org/onehtml/docs/coverage/ -->

# Coverage matrix

Generated by `CoverageMatrix.ToMarkdown()`; do not edit by hand. To refresh it after the data changes, run the
Validation tests with `ONEHTML_UPDATE_DOCS=1`. The sources and their pins are in `docs/catalogue.md`.

How to read it: *In WCAG* gives the first version with the criterion (`2.0+` means that version and every later one).
*ACT rules* are the W3C ACT rules that list the criterion as a requirement (any status; deprecated ones are marked).
*axe-core rules* are the rules whose `wcagNNN` tag names the criterion in axe-core 4.14.0. *Implemented* lists the
rules this package implements. *Automation* says how far a machine can decide the criterion: *fully* when every failure
condition can be decided mechanically, *partly* when some can and the rest need a person, *not* when it needs human
judgement or running behaviour a static check cannot see. *Basis* gives the reason. The assessments are data in
`Catalogue/Data/automation.json`.

Criteria with at least one rule: 42 of 87.

| WCAG version | A | AA | AAA | Total |
|---|---|---|---|---|
| 2.0 | 25 | 13 | 23 | 61 |
| 2.1 | 30 | 20 | 28 | 78 |
| 2.2 | 31 | 24 | 31 | 86 |

Profile summaries (criteria in the profile; the automation columns split them by assessment; *Implemented* counts criteria that have at least one rule in this package; *Gaps* counts criteria assessed fully or partly automatable that have none):

| Profile | Criteria | Implemented | Implemented, fully | Implemented, partly | Implemented, not | Not automatable | Gaps (fully or partly, no rule) | Some ACT or axe-core rule, none ours |
|---|---|---|---|---|---|---|---|---|
| wcag-2.0-aa | 38 | 24 | 1 | 22 | 1 | 12 | 3 | 3 |
| wcag-2.1-aa | 50 | 28 | 1 | 26 | 1 | 18 | 5 | 6 |
| wcag-2.2-aa | 55 | 28 | 0 | 27 | 1 | 21 | 7 | 6 |
| all | 87 | 36 | 1 | 33 | 2 | 41 | 12 | 6 |

| Criterion | Name | Level | In WCAG | ACT rules | axe-core rules | Implemented | Automation | Basis |
|---|---|---|---|---|---|---|---|---|
| 1.1.1 | Non-text Content | A | 2.0+ | 23a2a8, 46ca7f, 59796f, 7d6734, 8fc3b6, 9eb3f6 (deprecated), c487ae, e88epe, qt1vmo | aria-meter-name, aria-progressbar-name, image-alt, input-image-alt, object-alt, role-img-alt, svg-img-alt | aria-meter-name, aria-progressbar-name, image-alt, image-decorative, image-name-descriptive, input-image-alt, object-alt, role-img-alt, svg-img-alt | partly | Whether an image, input, object or SVG has a text alternative or name is mechanical; whether the text serves the same purpose is judgement. |
| 1.2.1 | Audio-only and Video-only (Prerecorded) | A | 2.0+ | 1a02b0, c3232f, e7aa44, ee13b5, f51b46 | audio-caption (deprecated) | audio-alternative, audio-caption, video-captions, video-only-alternative, video-only-audio-track, video-only-description-track, video-only-media-alternative, video-only-transcript, video-transcript | partly | Whether an alternative or track exists is mechanical; whether it is equivalent is judgement. |
| 1.2.2 | Captions (Prerecorded) | A | 2.0+ | eac66b | video-caption | video-caption, video-captions | partly | Whether a captions track exists is mechanical; whether it is accurate and synchronised is judgement. |
| 1.2.3 | Audio Description or Media Alternative (Prerecorded) | A | 2.0+ | c5a4ea |  | video-media-alternative, video-visual-alternative | partly | Whether a description track or media alternative exists is mechanical; whether it conveys the visual content is judgement. |
| 1.2.4 | Captions (Live) | AA | 2.0+ |  |  |  | not | Live captions can only be judged by watching a live event. |
| 1.2.5 | Audio Description (Prerecorded) | AA | 2.0+ | 1ec09b, c5a4ea |  | video-audio-description, video-description-track, video-strict-alternative, video-visual-alternative | partly | Whether a description track or alternative exists is mechanical; its adequacy is judgement. |
| 1.2.6 | Sign Language (Prerecorded) | AAA | 2.0+ |  |  |  | not | A sign-language video cannot be recognised mechanically. |
| 1.2.7 | Extended Audio Description (Prerecorded) | AAA | 2.0+ |  |  |  | not | Whether extended description is needed and sufficient is judgement. |
| 1.2.8 | Media Alternative (Prerecorded) | AAA | 2.0+ | 1a02b0, c5a4ea |  | video-transcript, video-visual-alternative | partly | Whether a transcript or alternative is linked is mechanical; its completeness is judgement. |
| 1.2.9 | Audio-only (Live) | AAA | 2.0+ |  |  |  | not | Live audio can only be judged by listening to a live event. |
| 1.3.1 | Info and Relationships | A | 2.0+ | 1a02b0, 4e8ab6, 5c01ea, 5f99a7, 674b10, 6a7281, a25f45, bc4a75, d0f69e, e086e5, ee13b5, ff89c9, in6db8 (deprecated), kb1m8s | aria-hidden-body, aria-required-children, aria-required-parent, definition-list, dlitem, list, listitem, p-as-heading, table-fake-caption, td-has-header, td-headers-attr, th-has-data-cells | aria-hidden-body, aria-required-children, aria-required-parent, definition-list, dlitem, list, listitem, p-as-heading, table-fake-caption, td-has-header, td-headers-attr, th-has-data-cells, video-only-transcript, video-transcript | partly | Markup that breaks structure (lists, tables, required ARIA parents and children, fake headings) is detectable; whether visual structure is also in the markup is judgement. |
| 1.3.2 | Meaningful Sequence | A | 2.0+ |  |  |  | not | Whether the reading order is meaningful is judgement; a layout comparison only finds candidates. |
| 1.3.3 | Sensory Characteristics | A | 2.0+ | 9bd38c |  |  | not | Instructions that rely on shape, size or location are found by reading them. |
| 1.3.4 | Orientation | AA | 2.1+ | b33eff | css-orientation-lock | css-orientation-lock | partly | CSS orientation locks are detectable; locks made by script are invisible to a static check. |
| 1.3.5 | Identify Input Purpose | AA | 2.1+ | 73f2c2 | autocomplete-valid | autocomplete-valid | partly | Invalid autocomplete tokens are detectable; whether a field's purpose matches its token is judgement. |
| 1.3.6 | Identify Purpose | AAA | 2.1+ |  |  |  | not | Whether a component's purpose is programmatically identified needs judgement about purpose. |
| 1.4.1 | Use of Color | A | 2.0+ |  | link-in-text-block | link-in-text-block | partly | Links distinguished only by colour inside text are detectable; other uses of colour to convey meaning are judgement. |
| 1.4.2 | Audio Control | A | 2.0+ | 80f0bf | no-autoplay-audio | autoplay-audio-control, autoplay-audio-duration, no-autoplay-audio | partly | Autoplaying media markup is detectable; audio started by script is invisible. |
| 1.4.3 | Contrast (Minimum) | AA | 2.0+ | 09o5cg, afw4f7 | color-contrast | color-contrast | partly | Contrast is exact where the foreground and a solid background are known; images, gradients and overlaps need rendered facts or review. |
| 1.4.4 | Resize Text | AA | 2.0+ | 59br37, b4f0c3 | meta-viewport | meta-viewport | partly | Markup that blocks zoom is detectable; whether content survives 200% zoom needs rendering. |
| 1.4.5 | Images of Text | AA | 2.0+ | 0va7u6 |  | image-of-text | not | Recognising text rendered as an image, and whether it is essential, is judgement. |
| 1.4.6 | Contrast (Enhanced) | AAA | 2.0+ | 09o5cg, afw4f7 | color-contrast-enhanced | color-contrast-enhanced | partly | As 1.4.3, with the higher thresholds. |
| 1.4.7 | Low or No Background Audio | AAA | 2.0+ |  |  |  | not | Background audio levels need listening. |
| 1.4.8 | Visual Presentation | AAA | 2.0+ |  |  |  | partly | Computed line height, width, alignment and spacing are measurable; colour selection and the reading experience are judgement. |
| 1.4.9 | Images of Text (No Exception) | AAA | 2.0+ | 0va7u6 |  | image-of-text | not | As 1.4.5, without the exceptions. |
| 1.4.10 | Reflow | AA | 2.1+ | b4f0c3 |  |  | partly | Overflow and clipping at 320 CSS pixels are measurable from a layout at that viewport; whether lost content matters is judgement. |
| 1.4.11 | Non-text Contrast | AA | 2.1+ |  |  |  | partly | Contrast of boundaries and graphics is measurable where colours are known; which parts are needed to identify a component is judgement. |
| 1.4.12 | Text Spacing | AA | 2.1+ | 24afc2, 78fd32, 9e45ec | avoid-inline-spacing | avoid-inline-spacing | partly | Inline declarations that stop text spacing overrides are detectable; whether content survives the overrides needs rendering. |
| 1.4.13 | Content on Hover or Focus | AA | 2.1+ |  |  |  | not | Content revealed on hover or focus is usually script-driven; whether it is dismissible, hoverable and persistent needs interaction. |
| 2.1.1 | Keyboard | A | 2.0+ | 0ssw9k, akn7bn | frame-focusable-content, scrollable-region-focusable, server-side-image-map | frame-focusable-content, scrollable-region-focusable, server-side-image-map | partly | Scrollable regions and frames a keyboard cannot reach are detectable; handlers added by script are invisible. |
| 2.1.2 | No Keyboard Trap | A | 2.0+ | 80af7b |  |  | not | A keyboard trap shows only while tabbing through a running page. |
| 2.1.3 | Keyboard (No Exception) | AAA | 2.0+ | 0ssw9k, akn7bn | scrollable-region-focusable | scrollable-region-focusable | partly | As 2.1.1. |
| 2.1.4 | Character Key Shortcuts | A | 2.1+ | ffbc54 |  |  | not | Single-key shortcuts are installed by script. |
| 2.2.1 | Timing Adjustable | A | 2.0+ | bc659a, bisz58 | meta-refresh | meta-refresh | partly | Meta refresh time limits are detectable; timers in script are invisible. |
| 2.2.2 | Pause, Stop, Hide | A | 2.0+ | efbfc7 | blink, marquee | blink, marquee | partly | Blinking and scrolling markup is detectable; other moving content needs judgement and timing. |
| 2.2.3 | No Timing | AAA | 2.0+ |  |  |  | not | Whether time limits are essential is judgement. |
| 2.2.4 | Interruptions | AAA | 2.0+ | bc659a, bisz58 | meta-refresh-no-exceptions | meta-refresh-no-exceptions | partly | Automatic page refresh is detectable; other interruptions come from script. |
| 2.2.5 | Re-authenticating | AAA | 2.0+ |  |  |  | not | Session expiry is server behaviour. |
| 2.2.6 | Timeouts | AAA | 2.1+ |  |  |  | not | Whether users are warned about data loss is judgement of content. |
| 2.3.1 | Three Flashes or Below Threshold | A | 2.0+ |  |  |  | not | Flash analysis needs the rendered frames of the content. |
| 2.3.2 | Three Flashes | AAA | 2.0+ |  |  |  | not | Flash analysis needs the rendered frames of the content. |
| 2.3.3 | Animation from Interactions | AAA | 2.1+ |  |  |  | not | Motion triggered by interaction is script-driven. |
| 2.4.1 | Bypass Blocks | A | 2.0+ | cf77f2 | bypass | bypass | partly | Skip links and landmarks are detectable; whether they bypass the right blocks is judgement. |
| 2.4.2 | Page Titled | A | 2.0+ | 2779a5, c4a8a4 | document-title | document-title, document-title-descriptive | partly | A missing or empty title is detectable; whether it describes the page is judgement. |
| 2.4.3 | Focus Order | A | 2.0+ |  |  |  | partly | Positive tabindex and focusable elements without a role are detectable; whether the order is meaningful is judgement. |
| 2.4.4 | Link Purpose (In Context) | A | 2.0+ | 5effbb, c487ae, fd3a94 | area-alt, link-name | area-alt, identical-links-same-context, link-in-context-descriptive, link-name | partly | Links without a name are detectable; whether the name and context state the purpose is judgement. |
| 2.4.5 | Multiple Ways | AA | 2.0+ |  |  |  | not | Whether a site offers more than one way to find pages is a property of the whole site. |
| 2.4.6 | Headings and Labels | AA | 2.0+ | b49b2e, cc0f0a |  | heading-descriptive, label-descriptive | partly | Empty headings and labels are detectable; whether they describe their content is judgement. |
| 2.4.7 | Focus Visible | AA | 2.0+ | oj04fd |  | focus-visible-indicator | partly | Rules that remove the focus outline are detectable under a focus context; whether another indicator is visible needs rendering. |
| 2.4.8 | Location | AAA | 2.0+ |  |  |  | not | Whether a page tells the user where they are is judgement of the whole site. |
| 2.4.9 | Link Purpose (Link Only) | AAA | 2.0+ | 5effbb, aizyf1, b20e66, c487ae, fd3a94 | identical-links-same-purpose | identical-links-same-context, identical-links-same-purpose, link-descriptive, link-in-context-descriptive | partly | Identical link names with different targets are detectable; whether a name alone states the purpose is judgement. |
| 2.4.10 | Section Headings | AAA | 2.0+ |  |  |  | not | Whether sections need headings is judgement. |
| 2.4.11 | Focus Not Obscured (Minimum) | AA | 2.2+ |  |  |  | partly | Needs layout and paint order to know what covers the focused element; mechanical with rendered facts. |
| 2.4.12 | Focus Not Obscured (Enhanced) | AAA | 2.2+ |  |  |  | partly | As 2.4.11, with the stricter condition. |
| 2.4.13 | Focus Appearance | AAA | 2.2+ |  |  |  | partly | Indicator size and contrast are measurable with rendered facts; whether a custom indicator is distinguishable is judgement. |
| 2.5.1 | Pointer Gestures | A | 2.1+ |  |  |  | not | Multipoint and path gestures are handled by script. |
| 2.5.2 | Pointer Cancellation | A | 2.1+ |  |  |  | not | Pointer event handling is script behaviour. |
| 2.5.3 | Label in Name | A | 2.1+ | 2ee8b8, e086e5 | label-content-name-mismatch | label-content-name-mismatch | partly | Comparing visible label text with the accessible name is mechanical for text labels; labels made of images are judgement. |
| 2.5.4 | Motion Actuation | A | 2.1+ | 7677a9, c249d5 |  |  | not | Motion actuation is script behaviour. |
| 2.5.5 | Target Size (Enhanced) | AAA | 2.1+ |  |  |  | partly | Target size is measurable with rendered facts; the exceptions are judgement. |
| 2.5.6 | Concurrent Input Mechanisms | AAA | 2.1+ |  |  |  | not | Input mechanisms are script behaviour. |
| 2.5.7 | Dragging Movements | AA | 2.2+ |  |  |  | not | Dragging interactions are script behaviour. |
| 2.5.8 | Target Size (Minimum) | AA | 2.2+ |  | target-size | target-size | partly | Target size and spacing are measurable; the exceptions (inline, equivalent control, essential) are judgement. |
| 3.1.1 | Language of Page | A | 2.0+ | 5b7ae0 (deprecated), b5c3f8, bf051a, ucwvc8 | html-has-lang, html-lang-valid, html-xml-lang-mismatch | html-has-lang, html-lang-matches-content, html-lang-valid, html-xml-lang-mismatch | partly | A missing or malformed lang is detectable; whether it is the right language needs language identification. |
| 3.1.2 | Language of Parts | AA | 2.0+ | de46e4, off6ek | valid-lang | element-lang-matches-content, valid-lang | partly | Malformed lang on parts is detectable; whether passages are in the declared language needs language identification. |
| 3.1.3 | Unusual Words | AAA | 2.0+ |  |  |  | not | Unusual words and their definitions are judgement. |
| 3.1.4 | Abbreviations | AAA | 2.0+ |  |  |  | not | Abbreviations and their expansions are judgement. |
| 3.1.5 | Reading Level | AAA | 2.0+ |  |  |  | not | Reading level is judgement. |
| 3.1.6 | Pronunciation | AAA | 2.0+ |  |  |  | not | Ambiguous pronunciation is judgement. |
| 3.2.1 | On Focus | A | 2.0+ |  |  |  | not | Context changes on focus come from script. |
| 3.2.2 | On Input | A | 2.0+ |  |  |  | partly | Forms without a submit control are detectable; changes of context on input come from script. |
| 3.2.3 | Consistent Navigation | AA | 2.0+ |  |  |  | not | Consistency is a property of several pages. |
| 3.2.4 | Consistent Identification | AA | 2.0+ |  |  |  | not | Consistency is a property of several pages. |
| 3.2.5 | Change on Request | AAA | 2.0+ | bc659a, bisz58 | meta-refresh-no-exceptions | meta-refresh-no-exceptions | partly | Automatic refresh is detectable; other changes of context come from script. |
| 3.2.6 | Consistent Help | A | 2.2+ |  |  |  | not | Consistency of help is a property of several pages. |
| 3.3.1 | Error Identification | A | 2.0+ | 36b590 |  |  | partly | Invalid-state and error-message association markup is detectable; whether an error is identified in text depends on runtime validation. |
| 3.3.2 | Labels or Instructions | A | 2.0+ |  | form-field-multiple-labels | form-field-multiple-labels | partly | Controls without labels are detectable; whether labels and instructions are sufficient is judgement. |
| 3.3.3 | Error Suggestion | AA | 2.0+ |  |  |  | not | Error suggestions are runtime content. |
| 3.3.4 | Error Prevention (Legal, Financial, Data) | AA | 2.0+ |  |  |  | not | Whether a page is legal or financial, and its safeguards, are judgement. |
| 3.3.5 | Help | AAA | 2.0+ |  |  |  | not | Whether help is available is judgement. |
| 3.3.6 | Error Prevention (All) | AAA | 2.0+ |  |  |  | not | Submission safeguards are runtime behaviour. |
| 3.3.7 | Redundant Entry | A | 2.2+ |  |  |  | not | Redundant entry spans steps of a process. |
| 3.3.8 | Accessible Authentication (Minimum) | AA | 2.2+ |  |  |  | partly | Missing autocomplete on authentication fields is detectable; script blocking of paste is invisible and the alternatives are judgement. |
| 3.3.9 | Accessible Authentication (Enhanced) | AAA | 2.2+ |  |  |  | partly | As 3.3.8. |
| 4.1.1 | Parsing | A | 2.0 (removed in 2.2) | 3ea0c8 (deprecated), e6952f (deprecated) | duplicate-id (deprecated), duplicate-id-active (deprecated) | duplicate-id, duplicate-id-active | fully | Duplicate ids and malformed nesting are decided by the parser and the document; the criterion is obsolete from WCAG 2.2. |
| 4.1.2 | Name, Role, Value | A | 2.0+ | 2t702h, 307n5z, 4b1c6c, 4e8ab6, 59796f, 5c01ea, 5f99a7, 674b10, 6a7281, 6cfa84, 97a4e1, c487ae, cae760, e086e5, in6db8 (deprecated), m6b1q3 | area-alt, aria-allowed-attr, aria-braille-equivalent, aria-command-name, aria-conditional-attr, aria-deprecated-role, aria-hidden-body, aria-hidden-focus, aria-input-field-name, aria-prohibited-attr, aria-required-attr, aria-roledescription (deprecated), aria-roles, aria-tab-name, aria-toggle-field-name, aria-tooltip-name, aria-valid-attr, aria-valid-attr-value, button-name, duplicate-id-aria, frame-title, frame-title-unique, input-button-name, input-image-alt, label, link-name, nested-interactive, select-name, summary-name | area-alt, aria-allowed-attr, aria-braille-equivalent, aria-command-name, aria-conditional-attr, aria-deprecated-role, aria-hidden-body, aria-hidden-focus, aria-input-field-name, aria-prohibited-attr, aria-required-attr, aria-roles, aria-tab-name, aria-toggle-field-name, aria-tooltip-name, aria-valid-attr, aria-valid-attr-value, button-name, duplicate-id-aria, frame-title, frame-title-unique, input-button-name, input-image-alt, label, link-name, nested-interactive, select-name, summary-name | partly | Roles, names and states in markup and ARIA are decided mechanically; values changed by script are invisible. |
| 4.1.3 | Status Messages | AA | 2.1+ |  |  |  | not | Status messages are announced at runtime; markup alone cannot show that a message appears. |

Implemented best-practice rules, which check no criterion: accesskeys, aria-allowed-role, aria-dialog-name, aria-text, aria-treeitem-name, empty-heading, empty-table-header, focus-order-semantics, heading-order, hidden-content, image-redundant-alt, label-title-only, landmark-banner-is-top-level, landmark-complementary-is-top-level, landmark-contentinfo-is-top-level, landmark-main-is-top-level, landmark-no-duplicate-banner, landmark-no-duplicate-contentinfo, landmark-no-duplicate-main, landmark-one-main, landmark-unique, meta-viewport-large, page-has-heading-one, presentation-role-conflict, region, scope-attr-valid, skip-link, tabindex, table-duplicate-name.


<!-- https://recursiveai.org/onehtml/docs/anglesharp-differential/ -->

# AngleSharp tree differential

How our trees compare with AngleSharp's on a corpus of real pages, and why each remaining difference is ours being right. AngleSharp is used as a black box (its output only), in the `tools/OneHtml.Differential` harness and never in the library. Every cause below is tied to the text of the WHATWG HTML Standard (parsing, §13.2), the Encoding Standard or the DOM Standard, and has a hand-written test of our side in `tests/OneHtml.Tests/AngleSharpDivergenceTests.cs`.

## Method

Both parsers get the same decoded text (the text our sniffer chose), so the tree comparison is not muddied by encoding; the two sniffed encodings are compared as a field of their own. Trees are compared in document order: node kind, namespace, local name, attributes (paired by namespace and local name, then qualified name, value, order), text, comments, doctype fields, template contents, child counts and quirks mode. Below a structural difference the trees no longer line up by position, so that subtree is not compared further. Each difference is traced to a cause: from the field and node types, or, for structural ones, from a minimized reproducer. A difference with no known cause is reported as `unexplained`.

## Result on corpus 2026-10a (13,857 pages)

12,469 pages (89.98%) have identical trees. Every difference in the other 1,388 pages falls into one of the causes below; none is unexplained. Rates are pages with at least one difference:

| field | pages | rate | cause |
|---|---:|---:|---|
| `attr.prefix` | 1,248 | 9.0% | `xlink-prefix` |
| `text` | 74 | 0.53% | `raw-text-end-tag-case`, `character-reference-bare-ampersand` |
| `attr.name` | 62 | 0.45% | `xlink-attributes` |
| `childCount` | 53 | 0.38% | `declarative-shadow-root`, `select-content`, `menuitem-element`, `search-element`, `cell-end-tag`, `nesting-depth-cap`, `adoption-agency-time-element`, `form-end-tag-in-template` |
| `encoding` | 33 | 0.24% | `encoding-gbk-name`, `encoding-xml-declaration`, `encoding-charset-parameter-case` |
| `localName` | 32 | 0.23% | `svg-tag-names` |
| `kind` | 30 | 0.22% | `processing-instruction` and the structural causes |
| `attr.value` | 10 | 0.07% | `character-reference-bare-ampersand` |
| `quirks`, `namespace`, `attr.namespace`, `attr.order`, `comment`, `doctype.*`, `template` | 0 | 0% | |

A page may show several causes; the page counts per cause are in the cause sections. A further 50 pages differ only in the last-resort encoding (below) and count as identical.

## Causes

Each section gives the input, the standard's text, what each parser does, and the pages affected on the corpus.

### `xlink-prefix`, `xlink-attributes` (1,231 and 58 pages)

`<svg><use xlink:href="#a">`. HTML 13.2.6.5 "adjust foreign attributes" maps `xlink:href` to the attribute with prefix `xlink`, local name `href`, in the XLink namespace. We keep the prefix; AngleSharp reports the attribute as plain `href` (it keeps the namespace but drops the prefix). When an element has both `href` and `xlink:href`, which the DOM Standard allows since they differ in namespace, AngleSharp keeps one (`xlink-attributes`).

### `processing-instruction` (21 pages)

`<?p q?>`. The parsing section of the standard we implement (the current text, with the "processing instruction open", "target", "after target", "data" and "questionable" states, 13.2.5.72–76) tokenizes `<?` followed by a valid target as a processing instruction and inserts a ProcessingInstruction node; only an invalid target becomes a bogus comment. AngleSharp implements the older rule: every `<?` is a bogus comment. Browsers have not all adopted the new text; a consumer that wants comments instead should treat our `ProcessingInstruction` nodes as comments.

### `svg-tag-names` (3 pages)

`<svg><feDropShadow>`. The "adjust SVG tag names" table in 13.2.6.5 includes `feDropShadow` (`fedropshadow` → `feDropShadow`). AngleSharp's table lacks it and leaves the name lowercase.

### `raw-text-end-tag-case` (45 pages)

`<style></C` at the end of the input. In 13.2.5.14 "RAWTEXT end tag name state", an ASCII upper alpha appends its lowercase form to the tag name and the character as typed to the temporary buffer; when the end tag is not appropriate or the input ends, the buffer's characters (not the tag name) are emitted as text, so the text is `</C`. AngleSharp emits `</c`. The same states exist for RCDATA, script data and escaped script data.

### `character-reference-bare-ampersand` (8 pages)

`a&;b` and `<p title="&;">`. 13.2.5.77 "character reference state": a `&` followed by something other than an alphanumeric or `#` flushes the code points consumed so far as text (or attribute value) and reconsumes the next character in the return state, so the `;` stays: `a&;b`. AngleSharp drops the `;`.

### `encoding-gbk-name` (23 pages)

A page labelled `gb2312` or `gbk`. The Encoding Standard's label table maps these labels to the encoding named `GBK`; `gb18030` is a separate encoding (the GBK decoder is the gb18030 decoder). AngleSharp reports `gb18030`. The decoded text is the same.

### `encoding-xml-declaration` (5 pages)

`<?xml version="1.0" encoding="Shift_JIS"?>` at the start of a page served without a charset. 13.2.3.2's prescan step "looking for syntax resembling an XML declaration, even in text/html" takes the declared encoding when no BOM, transport charset or `<meta>` decides first. AngleSharp ignores the declaration and uses UTF-8.

### `encoding-charset-parameter-case` (5 pages)

`Content-Type: text/html; Charset=utf-8` with a `<meta>` declaring another encoding. Parameter names of a MIME type are matched ASCII case-insensitively (MIME Sniffing, "parse a MIME type", which lowercases them), so the transport layer says UTF-8 and wins over the `<meta>`. AngleSharp ignores a `Charset` parameter spelled with a capital.

### The last-resort encoding (50 pages, not counted)

With no BOM, header, `<meta>` or XML declaration, 13.2.3.2 leaves the encoding "implementation-defined or user-specified", and recommends a locale-dependent default: windows-1252 for most locales. Ours is windows-1252 and is not changed; AngleSharp's is UTF-8. A page where only this default differs is listed in the summary but is not a mismatch.

### `declarative-shadow-root` (24 pages)

`<div><template shadowrootmode=open><b></b></template></div>`. In the "in body" and "in head" template start-tag steps the `shadowrootmode` attribute attaches a shadow root only when the parser's "allow declarative shadow roots" flag is true; it is initially false (13.2.4.5) and is set only by the parseHTMLUnsafe family of APIs. A document parsed from bytes therefore keeps the `template` element and its content fragment, which is what we produce. AngleSharp always attaches a shadow root, so the host has no child.

### `select-content` (9 pages)

`<select><option><n></select>`. The current standard has no "in select" insertion mode: a `select`'s content is parsed as in body, and elements other than `option` and `optgroup` stay inside it. We follow that; AngleSharp implements the older mode and drops or relocates such elements.

### `menuitem-element` (8 pages)

`<div><menuitem><`. `menuitem` no longer appears in the parsing algorithm, so it is an ordinary element that stays open. AngleSharp closes it like a void element.

### `search-element` (3 pages)

`<div><search><div></search>x`. `search` is in the lists of 13.2.6.4.7 "in body" that close a `p` element in button scope and whose end tag pops to the element (and in the "special" category). AngleSharp does not know `search`, so `</search>` is an "any other end tag" that stops at the special `div` and is ignored.

### `cell-end-tag` (5 pages)

`<table><tr><th></td>x`. In 13.2.6.4.15 "in cell" an end tag `td` or `th` is acted on only if an element with that tag name is in table scope; otherwise it is a parse error and ignored. A `</td>` does not close a `th`. AngleSharp closes the cell.

### `adoption-agency-time-element` (1 page)

`<ul><li><a><time></a>x`. In the adoption agency algorithm (13.2.6.4.7), the furthest block is the topmost *special* element below the formatting element; `time` is not special, so there is none, and the algorithm pops the stack up to and including the formatting element and removes it from the list of active formatting elements. `time` ends up inside the `a`, and the text after `</a>` is outside. AngleSharp treats `time` like a block and clones the `a` inside it.

### `form-end-tag-in-template` (1 page)

`<form><div><template><o></form>x</template>y</div>z</form>w`. In "in body", a `</form>` end tag with a `template` on the stack of open elements is ignored unless a `form` element is in scope, and `template` is a scope boundary; later, with no template open, `</form>` removes the form element the form element pointer names. So `z` stays in the form and `w` is outside it. AngleSharp keeps `w` inside the form.

### `nesting-depth-cap` (3 pages)

Three non-HTML bodies (PDFs served as `text/html`) whose binary content makes thousands of unclosed unknown elements. The standard sets no nesting limit. We nest up to `ParseLimits.MaxOpenElements` (4096, a hostile-input guard that fails cleanly with `HtmlLimitExceededException`); AngleSharp stops nesting at 512 and appends later elements as siblings.

## Reproducers

Reproducers are minimized from the crawled pages for the harness's own use and are never committed (they are derived from third-party pages). The inputs above were written by hand.


<!-- https://recursiveai.org/onehtml/docs/chrome-ax-differential/ -->

# The Chrome accessibility-tree differential

`OneHtml.Differential ax` compares our accessibility tree with the one Chrome returns from `Accessibility.getFullAXTree`, node by node, for pages captured by `tools/capture`. Chrome is a black box here: only its protocol output is read. The command is in `tools/OneHtml.Differential`; nothing in `src/` depends on it.

```
OneHtml.Differential ax <capture-dir> [--corpus <dir>] [--out <dir>] [--jobs n] [--limit n] [--timeout s] [--top n] [--facts on|off|both] [--dump]
```

| Argument | Meaning |
|---|---|
| `<capture-dir>` | The capture tool's output directory (or its `captures/` directory). Every `…/<sha256>/<WxH>/` directory with a `meta.json` (or an `errors.json`) is one capture. |
| `--corpus` | Where stylesheets come from: a corpus version directory (`manifest.jsonl`, stylesheet bodies by URL) or a directory of loose `.css` files, matched by the end of the URL path. Chrome was served the same bytes. Without it, linked and imported sheets are missing and the cascade runs on what the page itself holds. |
| `--out` | Output directory, default `./out`. |
| `--jobs`, `--limit`, `--timeout`, `--top` | As for the other commands: parallel captures (default 2), the first n captures in sha256 order, seconds per capture (default 30), classes shown in `summary.md` (default 20). |
| `--facts` | `on`, `off` or `both` (default). See "Rendered facts". |
| `--dump` | Also writes `dump/<sha12>-<viewport>.txt`: one line per Chrome node with its counterpart, then our unpaired nodes. For finding out why a class exists. A Chrome node with no counterpart also shows where it sits (`under` its nearest paired ancestor), and one of ours shows its parent's path. |

Exit status is 0 whatever the rates are; the numbers are the result.

## What is compared

For each capture the tool reads `dom.json`, `snapshot.json`, `ax.json` and `meta.json`:

1. Chrome's serialized DOM (doctype plus `outerHTML`) is parsed with OneHtml. The cascade gets the capture's viewport (`width`, `height`, `deviceScaleFactor`) as media features, the page URL as base URL, and the stylesheet resolver above. Scripts never ran; that is how the capture was taken.
2. The snapshot is mapped onto the document (`DomSnapshotAdapter.Map`). A snapshot of a different DOM is **refused**; the capture is counted as `refused` with the refusal reason and not compared, because nodes cannot be matched without the mapping.
3. Our tree is built (`AccessibilityTree.Build`, with `AccessibilityOptions.BaseUrl` the capture's final URL) and written in the Chrome-shaped export (`onehtml-ax/1`). Chrome's main-frame nodes and the export are read by the same code into a common shape, so both sides pass through the same normalization.
4. Nodes are matched, then compared.

Only the main frame's nodes are compared; frames of other documents, and the child ids that point into them, are ignored.

### Matching

1. The root web area pairs with our document node.
2. A Chrome node with a `backendDOMNodeId` pairs with our node for the same DOM node. The id is translated through the snapshot's `backendNodeId` and the mapping's node accounting (`NodeFacts.BackendNodeId`).
3. **Anonymous nodes.** A Chrome node that has no OneHtml node (no backend id, or one the mapping does not carry: generated text, layout boxes, user-agent shadow content) pairs with the first still unpaired child of the counterpart of its nearest paired ancestor that is of the same kind (text or not), has the same role and the same ignored flag, and has the same name. Anything else stays unpaired. The number paired this way is in the summary.
4. Chrome's `InlineTextBox` nodes are skipped on read. They are layout boxes of a `StaticText` and carry no information the static text does not.
5. Unpaired nodes are counted per side. An unpaired node that is ignored is counted separately (`chromeOnlyIgnored`, `oursOnlyIgnored`): an ignored node is not part of what assistive technology walks, so it does not change the exposed tree. Chrome omits `visibility: hidden` and `aria-hidden` elements and `noscript`; we keep them as ignored nodes.

### Fields

Each paired node is compared on the fields below. A field is compared when it applies; `compared` in the report is the number of times it was.

| Field | Compared | Notes |
|---|---|---|
| `ignored` | every pair | Chrome's `ignored` against ours. If the flags differ, no other content field of that pair is compared. |
| `hidden` | every pair | Whether the ignored reasons include `notRendered`, `ariaHiddenElement`, `ariaHiddenSubtree`, `inertElement` or `inertSubtree`. |
| `ignoredReasons` | both ignored | The remaining reasons (`uninteresting`, `presentationalRole`, `labelFor`, …) as a sorted set. |
| `role` | both not ignored | Chrome's role value (including its internal roles) against ours (`InternalRole` or the Core-AAM name). |
| `name` | both not ignored | After the normalization below. |
| `nameSource` | names equal and not empty | The step that produced the name, in these categories: `aria-labelledby`, `aria-label`, `native-element` (label, legend, caption, figcaption, SVG or document `title` element), `native-attribute` (`alt`, `value`, …), `title` (the attribute), `placeholder`, `contents`, `text` (static text). For Chrome it is the first entry of `name.sources` that is not superseded and has a non-empty value. |
| `description` | both not ignored | After the normalization below. |
| `value` | either has one | The widget value. |
| `prop.<name>` | either has it | `focusable`, `focused` (not the root: the page's own focus), `disabled`, `checked`, `expanded`, `selected`, `pressed`, `required`, `invalid`, `level`, `live`, `modal`, `hasPopup`, `multiselectable`, `readonly`, `valuemin`, `valuemax`, `valuetext`, `orientation`, `multiline`, `editable`, `url` (not the root: the document's URL is not in the DOM), `posinset`, `setsize`, `autocomplete`, `busy`, `atomic`, `relevant`, `roledescription`, `keyshortcuts`. |
| `rel.<name>` | either has it | `activedescendant`, `controls`, `describedby`, `details`, `errormessage`, `flowto`, `labelledby`, `owns`: the related nodes in order, as OneHtml node indexes. |
| `parent` | every pair | Parent in the unpruned tree (ignored nodes included): the pair of Chrome's parent against ours. |
| `exposedParent` | every pair | Nearest ancestor that is not ignored. |
| `childOrder` | not-ignored pairs with at least two common exposed children | The order of the exposed children that both sides have. A child present on one side only is reported once, as `chromeOnly` or `oursOnly`. |
| `chromeOnly`, `oursOnly` | every not-ignored node of that side | Present on one side only. |
| `chromeOnlyIgnored`, `oursOnlyIgnored` | every ignored node of that side | As above, for ignored nodes. |

### Normalization

Everything that makes the two sides spelled differently without a difference in meaning is in `AxNormalizer` (`tools/OneHtml.Differential/AxModel.cs`), nowhere else. It is:

- **White space.** Runs of ASCII white space (space, tab, line feed, form feed, carriage return) in names, descriptions and `valuetext` collapse to one space and the ends are trimmed. A no-break space stays.
- **Flags.** `false` and absent are the same for `focusable`, `focused`, `disabled`, `required`, `readonly`, `modal`, `multiselectable`, `multiline` and `busy`; `invalid=false` is absent; an empty `valuetext`, `roledescription`, `keyshortcuts`, `autocomplete` or `relevant` is absent. Chrome reports these flags as `false` where the role supports them and we leave them out. `expanded`, `selected`, `checked` and `pressed` are not touched: absent means the role does not have the state, `false` means it is off.
- **Numbers.** Property numbers are compared in their shortest round-trip spelling (`1` and `1.0`). The `value` of a `meter`, `progressbar`, `slider`, `spinbutton` or `scrollbar` is compared as a 32-bit float, because Chrome stores these as single-precision floats and reports them widened (`0.6` arrives as `0.6000000238418579`). Other values compare as written.
- **Value and flags added by the last round.** An empty `value` is absent; `atomic=false` is absent; `busy` as `1` is `true`.
- **Parents.** `parent` and `exposedParent` are compared through the nearest ancestor that has a counterpart on the other side, so an unpaired ignored node is not counted twice.
- **Role of ignored nodes.** Both sides call an ignored node `none`; its role is not compared.
- **Name source of static text** is `text` on both sides.
- **Names and descriptions of ignored nodes** are not compared (neither side has them).

Nothing else is normalized: no role aliases, no case folding, no Unicode normalization.

### Rendered facts

`--facts` selects whether our tree is built with the capture's rendered facts (`AccessibilityOptions.Facts`). The facts are always used for the mapping in step 2, in both modes.

- `off`: one run without facts.
- `on`: one run with facts; the report is that run.
- `both` (default): each page is compared twice, with and without facts, over the same Chrome nodes. The per-field table and the classes are the run with facts; the section "With and without rendered facts" prints both rates side by side (with the number of mismatching nodes in brackets).

A capture whose snapshot does not map onto its DOM is refused in every mode.

## Output

Written to `--out`; nothing in it should be copied into the repository except reduced, hand-written cases.

| File | Content |
|---|---|
| `summary.md` | Counts, refused and failed captures with reasons, the per-field table, the with/without facts table, the top classes with up to three examples each. |
| `summary.json` | Schema `onehtml-ax-differential/1`: `reference` (Chrome product, revision and protocol version from the capture's `environment.json`), `facts`, `captures`, `compared`, `pages`, `refused`, `failed`, `chromeNodes`, `oursNodes`, `matched`, `matchedAnonymous`, `refusals` (`sha256`, `viewport`, `url`, `reason`), `fields` (`field`, `compared`, `occurrences`, `nodes`, `pages`, `pagesCompared`, `rate`), `topClasses`. |
| `classes.json` | Schema `onehtml-ax-differential/1/classes`: every class (`field`, `pattern`, `occurrences`, `nodes`, `pages`, `examples`). An example has `page` (sha256), `viewport`, `url`, `node` (our DOM path such as `html[1] > body[2] > div[6]`, or `chrome#<backend id> <role>` for a Chrome-only node), `chrome` and `ours` (values, clipped to 80 characters). Ordered by occurrences, then field and pattern. |
| `captures.jsonl` | One line per capture: `sha256`, `viewport`, `url`, `status` (`ok`, `refused`, `skipped`, `error`), `detail`, node counts and mismatch count. |
| `dump/` | With `--dump`, see above. |

**Rates.** `occurrences` counts mismatching (capture, node) pairs; `nodes` counts distinct (page, node) pairs, so a page captured at two viewports counts its nodes once; `pages` is the number of pages with at least one. `rate` is occurrences over `compared`. For properties and relations, `compared` counts the pairs where either side has the property, so a rare property that always disagrees reads 100%.

**Classes.** A class is a field plus a pattern: for `role`, the two roles (`LayoutTable -> table`); for `name`, `description` and `value`, the role and the shape of the difference (`chrome-empty`, `ours-empty`, `ours-prefix`, `chrome-prefix`, `case-only`, `differs`); for properties, the role and both values; for `ignored`, which side is ignored and the roles and reasons; for the structure fields, the roles of both parents; for the presence fields, the role and, when ignored, the reasons. Output is deterministic: captures are processed in sha256 and viewport order whatever `--jobs` is.

## Worker run

The command takes the worker's shared-job lock like the other corpus commands and exits with status 3 at once if it is held:

```
bash tools/OneHtml.Differential/run-worker.sh ax ~/onehtml/capture-out/<version> ~/onehtml/out/ax --corpus ~/onehtml/corpus/<version> --facts both --jobs 8
```

`--limit N` takes the first N captures by hash and `--pages <sha256 prefix,...>` selects pages; `--dump` writes a per-node listing of the selected pages.

## Results with and without rendered facts

Chrome for Testing 156.0.8078.47 (protocol 1.3), headless, 1280x800, page script off; .NET 10 on the AMD Ryzen 9 7950X3D worker (32 threads), `--facts both --jobs 2 --limit 2100`, about 125 seconds. The sample is the first 2,100 captures by hash: 2,095 compared (1,840,086 Chrome nodes, 1,973,233 of ours, 1,779,203 matched, 284,249 of them by the anonymous-node rule) and 5 refused (a custom element whose shadow root the snapshot omits, and two whose text differs in line breaks). Rates are mismatching nodes over the times the field was compared, with the number of nodes in brackets. "Before" is the same pages with the tree as it stood at the start of this round (facts on). Fields that never differ are left out; the run's `summary.md` has all of them.

| field | before (facts) | without facts | with facts |
|---|---:|---:|---:|
| ignored | 0.291% (5114) | 13.279% (199263) | 0.173% (3086) |
| hidden | 0.06% (1053) | 0.088% (1323) | 0.06% (1072) |
| ignoredReasons | 0.124% (491) | 1.68% (1380) | 0.118% (475) |
| role | 0.089% (1216) | 0.485% (5914) | 0.089% (1217) |
| name | 0.591% (8027) | 0.561% (6845) | 0.498% (6845) |
| nameSource | 0.012% (102) | 0.014% (102) | 0.012% (102) |
| description | 0.135% (1836) | 0.148% (1810) | 0.132% (1810) |
| parent | 0.307% (5398) | 0.422% (6332) | 0.303% (5397) |
| exposedParent | 0.389% (6851) | 23.639% (354741) | 0.245% (4362) |
| chromeOnly | 1.979% (27510) | 11.866% (164933) | 0.913% (12687) |
| oursOnly | 0.347% (4733) | 8.231% (126706) | 0.378% (5222) |
| chromeOnlyIgnored | 11.737% (52827) | 38.774% (174511) | 10.708% (48196) |
| oursOnlyIgnored | 32.173% (189519) | 79.531% (341912) | 31.864% (188808) |
| prop.checked | 0.039% (2) | 0.039% (2) | 0.039% (2) |
| prop.disabled | 6.931% (21) | 6.623% (20) | 6.931% (21) |
| prop.editable | 0.028% (1) | 0.028% (1) | 0.877% (61) |
| prop.expanded | 0.097% (5) | 0.096% (5) | 0.097% (5) |
| prop.focusable | 0.02% (58) | 0.02% (58) | 0.02% (58) |
| prop.hasPopup | 0.635% (19) | 0.635% (19) | 0.635% (19) |
| prop.invalid | 32.836% (22) | 32.836% (22) | 32.836% (22) |
| prop.level | 0.011% (22) | 0.011% (21) | 0.011% (22) |
| prop.posinset | 100% (28) | 100% (28) | 100% (28) |
| prop.readonly | 17.949% (7) | 17.949% (7) | 17.949% (7) |
| prop.roledescription | 5.069% (11) | 5.069% (11) | 5.069% (11) |
| prop.selected | 0.377% (58) | 0.377% (58) | 0.377% (58) |
| prop.setsize | 100% (28) | 100% (28) | 100% (28) |
| prop.url | 1.061% (2832) | 1.061% (2832) | 1.061% (2832) |
| prop.valuemax | 2.572% (8) | 2.572% (8) | 2.572% (8) |
| prop.valuemin | 1.929% (6) | 1.929% (6) | 1.929% (6) |
| prop.valuetext | 9.565% (11) | 9.565% (11) | 9.565% (11) |

Without facts the tree cannot know what Chrome did not draw, so `ignored`, `exposedParent`, `chromeOnly` and `oursOnly` are high; with facts they are the figures above. No field is worse with facts than without by more than a few nodes, except `prop.editable` (1 node without facts, 61 with: the inner editors of text fields, see the classes). The probe pages (`testdata/rendered/pages/*probe*.html`, with Chrome's captures beside them) pin the rules that came out of this round: `ChromeProbeTests` compares the exposed structure of the generated-content probe, the inner nodes of text fields and the name of each of 170 links with Chrome's.

### Classes

A class is a field plus a pattern (see "Output"). Dispositions of every class above 0.1% of its field's compared count (for the small property fields, above one node). **Fixed** means the class shrank to the figures given, with a hand-written test and a profile entry; **open** means it was not traced to a rule and is not documented as a deliberate difference.

| Class | Count | Disposition |
|---|---:|---|
| `oursOnlyIgnored` (`none` with `notVisible`, `notRendered`, `ariaHiddenSubtree`, `ariaHiddenElement`, `uninteresting`, `emptyAlt`, `presentationalRole`) | about 189,000 | **Representation, deliberate.** Our tree keeps every DOM node with its hidden and ignored reasons so that edits and diffs map back to the markup. Chrome omits nodes it has no use for. An ignored node is never part of the exposed tree. Not fixed. |
| `chromeOnlyIgnored` | about 48,000 | **Representation.** Chrome creates ignored nodes (children of `display: none` and `aria-hidden` subtrees, `uninteresting` wrappers around layout objects) that have no DOM node of ours. Ignored, so not exposed. The wrappers of `::before` and `::after` boxes are now ours too (profile entry `generated-content-node`). |
| `ignored`: Chrome `generic`, ours ignored `uninteresting` | 2,026 -> 1,014 | **Fixed in part, open.** The residue was traced: a generic with drawn `::before` or `::after` text is kept (fixed, 1,000 of them), an inline-block `span` is kept (fixed; the earlier rule ignored every span), and what is left are spans and divs of the same shape that Chrome ignores (inline-block spans with and without generated content split about 60 to 40, `div` and `span` flex items with a text child), where nothing in the capture's styles separates the two. Probe pages show Chrome ignoring a block-level empty `::before` box in a block host and keeping it in an inline host. |
| `ignored`: Chrome ignored `uninteresting`, ours `generic` | 716 -> 290 | **Open, small.** Mostly an inline-block span whose Chrome node is ignored. |
| `ignored`: Chrome `LabelText`, ours ignored `labelFor` (and the text children) | 485 -> 395 on 15 pages | **Fixed in part.** A probe of 50 label forms settled the rule (profile entry `label-for`): a label with only text that labels a checkbox or a radio button is `labelFor` whether it wraps the control or uses `for`, before or after it; a label with an element child, or of any other control, is `LabelText`. The 395 left are on 15 pages and were not traced. |
| `ignored`: Chrome `image`, ours ignored `emptyAlt` | 362 | **Deviation.** An `img` with `alt=""` and a `title` is an `image` in Chrome 156 (47 of 47 in 400 pages); HTML-AAM and WPT `html-aam/roles-contextual.html` (`el-img-empty-alt-title`) give it no role. Kept at the specification's answer. |
| `hidden` (1,072 nodes, 0.06%) | 1,072 | **Below the threshold.** The `ariaHiddenSubtree` against `ariaHiddenElement` split is Chrome's choice for nested `aria-hidden` that the profile entry `ignored-reasons` handles for the element's own attribute; the rest are `notRendered` subtrees of `display: none` ancestors that Chrome lists. |
| `ignoredReasons` (475 nodes, 0.118%) | 475 | **Open, near the threshold.** `uninteresting` against no reason on SVG graphics elements (Chrome gives `notRendered` to `title`, `desc`, `stop` and some `path` elements depending on layout objects we do not model) and `uninteresting` against `presentationalRole` in `role=presentation` tables. |
| `parent`, `exposedParent` | 5,400 and 6,851 -> 4,362 | **Follows from the other classes.** `exposedParent` fell from 0.39% to 0.245% with the generated-content and label fixes; the rest is the generic differences above and `LayoutTableCell` against `LayoutTable`. |
| `chromeOnly`: `StaticText` (4,082), `generic` (2,572) | 27,510 -> 12,687 | **Fixed in part.** `::before`/`::after` text and boxes, the text of input buttons and the inner editors of text fields are now nodes (profile entries `generated-content-node` and `control-text-node`); the part that is left is the shadow content of date, time, file, range and select controls, the pseudo boxes of display table, flex, grid and list-item (Chrome nests them differently), image-input parts, a `StaticText` that Chrome gives to whitespace Chrome draws between inline elements that are not both `display: inline`, and the `ListMarker` and `listitem` of `::before` boxes with `display: list-item`. **Open.** |
| `oursOnly`: `StaticText` (3,184), `generic` (1,688) | 4,733 -> 5,222 | **Open.** Whitespace text nodes Chrome merges with a neighbour, and generics of ours that Chrome has no node for at all: an `a` without `href` is now left out like a span (fixed), but inline-block spans and block `a`/`div` wrappers remain. The `oursOnly` rate rose from 0.35% to 0.38% while `chromeOnly` fell from 1.98% to 0.91%: more nodes are created, some of them not Chrome's. |
| `name`: `link differs` | 7,800 -> 4,392 | **Fixed in part.** Flex and grid items and `display: contents` elements are blocks for the spaces in a name (profile entry `positioned-blockification`, 150 of 150 probe links agree), SVG `style` text is not name content (176 links), the rest is `title` and `aria-label` of hidden children Chrome includes, `alt` of images Chrome leaves out (a link with a lazy-load placeholder image), the spaces Chrome puts in a long text that wraps inside a word (a URL as link text) and spaces of icon-font spans. **Open.** |
| `name`: `term` (929), `time`, `figure`, `heading` | 929 + 114 + 392 + 186 | `dt` named from its contents and `time` unnamed (profile entry `name-from-contents-roles`, fixed). A `figure` whose name we take from a `title` or `figcaption` that Chrome leaves empty (392 on 78 pages) and a `heading` inside a button whose name we leave empty (186 on 34 pages) are **open**. |
| `name`: `option` `case-only` | 147 on 7 pages | **Deviation, open.** Chrome does not apply the select's `text-transform` to an option's name; we do. |
| `role` (1,217 nodes, 0.089%) | 1,217 | **Below the threshold.** `cell`, `row`, `table` against `LayoutTableCell`, `LayoutTableRow`, `LayoutTable` (profile entry `layout-table`), and `image` against `SvgRoot`. |
| `description`, `nameSource` | 1,810 and 102 | **Open, small.** `description` is 0.132%; the remainder is the `name` classes (a link's `title` as description when Chrome uses it as the name). |
| `prop.url`: `image` and `srcset` | 2,832 | **Deviation.** Chrome reports the image chosen from `srcset` and `picture` for its viewport and density; we state the `src`, because choosing needs the layout width. |
| `prop.editable` | see below | **Second pass** ("Property fields, second pass"): traced and fixed, or documented per class. |
| `prop.disabled`, `invalid`, `hasPopup`, `readonly`, `selected`, `posinset`, `setsize`, `valuemin`, `valuemax`, `valuetext`, `roledescription` | see below | **Second pass** ("Property fields, second pass"): traced and fixed, or documented per class. |
| `value` | see below | **Second pass** ("Property fields, second pass"): traced and fixed, or documented per class. |
| `rel.labelledby`, `rel.controls` | 298 and 14 | **Open.** Chrome lists the label for a radio, checkbox and textbox where our name came from another source; navigation landmarks whose label target is not in Chrome's tree. |

The open classes above are not traced to a rule. The largest are `name` `link differs` (0.3% of the field's compared nodes), the generic and `StaticText` differences in `chromeOnly` and `oursOnly`, and the three small `ignored` residues.

## Property fields, second pass

The first run of the full corpus (12,788 captures, facts both) left these property fields above 1%: `posinset` and `setsize` 100%, `invalid` 27.3%, `readonly` 21.5%, `disabled` 15.8%, `valuetext` 7.9%, `value` 4.9%, `roledescription` 2.3%, `selected` 1.7%, `valuemax` 1.2%, `autocomplete` 2.8%, `hasPopup` 1.0%, `editable` 1.1%, `keyshortcuts` 1.0%, and `chromeOnly` 1.126%. Each had one or two systematic causes. They were found by writing a probe page for each suspected behaviour (`testdata/rendered/pages/axprops.html`, `axprops2.html`, `axprops3.html`), capturing it in the pinned Chrome (captures beside it in `testdata/rendered/captures`), and fixing the tree or export to match; the rule is a profile entry of the name given. `ChromePropertyTests` has one case per cause; `ChromePropertyProbeTests` compares every element with an `id` on the first two probe pages property by property and lists the three differences left; `ChromeProbeTests` compares the inner-node structure of the third.

### Causes

| Field | Cause | Profile entry |
|---|---|---|
| `posinset`, `setsize` | Chrome never states either (214 of 214 mismatches had Chrome absent), whether the author gave them or not; we stated the given ones. | `export-set-position` |
| `invalid` | Chrome reports constraint failures of more control kinds than we did (radio groups, required file, date and time fields, list boxes, email and url syntax, pattern, step, date range) and none for a disabled or readonly control or after an explicit `aria-invalid=false`. | `constraint-invalid` |
| `readonly` | Chrome states it on text boxes and grids only, and not when disabled. | `readonly-exposure` |
| `disabled` | A disabled ancestor reaches only the focusable descendants, a disabled fieldset or optgroup is not itself disabled, an option of a disabled select is. | `disabled-inheritance` |
| `valuetext`, `valuemin`, `valuemax`, `value` of ranges | Chrome never states `aria-valuetext`, reports bounds as single-precision numbers, lets the author's `aria-valuemin`/`max`/`now` win over native attributes, and gives a spin button 0, 0 and 0 and a progress bar with a bad `aria-valuenow` the value 0. | `range-values` |
| `value` of text-like controls | "No file chosen", password bullets, the text of a custom combobox or text box, the first enabled option of a select (not the first), lower-cased colours, no value for an invalid date, no line breaks in a text value, the select's `text-transform`. | `input-password-file`, `option-selectedness`, `text-values` |
| `selected` | Chrome omits `selected=false` on an option, tab or tree item when another item of the list says anything about `aria-selected`; it states none on a disabled option; a tree item is `false` by default. | `selected-states` |
| `role` (a by-product) | An `option` role with no listbox around it (a `button`, `a` or `li` carrying `role=option` in a popup) is the element's own role in Chrome. This removed about 7 in 8 of the `role` mismatches on the 171-page subset. | `option-needs-listbox` |
| `roledescription` | Not stated on a generic element; non-ASCII text arrives as Latin-1 bytes of its UTF-8 form. | `roledescription-roles` |
| `autocomplete`, `hasPopup` | `hasPopup` on any element, listbox by default for every combobox, `aria-haspopup=1` and `false` are not popups; `autocomplete` on text fields only, and for `input list`. | `autocomplete-popup`, `autocomplete-text-fields` |
| `keyshortcuts` | The `accesskey` attribute as written, after `Alt+`. | `accesskey-shortcut` |
| `editable` | Editable text inherits down from a `contenteditable` host; the inner editor of a disabled or read-only field is not editable. | `editable-inherited` |
| `expanded`, `level`, `multiline`, `required` (found by the probe comparison) | An ARIA combobox has no `expanded` of its own, tree items have levels, a `contenteditable` text box is multiline, a list box select is required. | `combobox-expanded`, `treeitem-level`, `readonly-exposure`, `text-values` |
| `chromeOnly` `generic` (a search field with a placeholder) | The placeholder leaf comes before the ignored node that holds the inner editor of a search or number field, and a combobox input has that node too. | `placeholder-leaf` |

### Before and after

Same machine and run as above (Chrome for Testing 156.0.8078.47, `--facts both --jobs 2`, one process; AMD Ryzen 9 7950X3D, 32 threads, load average 4 to 5 from other work during the runs, so these are counts, not timings). Counts are mismatching nodes with facts. The subset is the 171 captures whose first mismatch examples were in the classes above (every class had at least one page); the sample is 399 captures from the middle of the corpus order (`--skip 3000 --limit 400`, one refused), as a check that no other field gets worse.

| field | subset before | subset after | sample before | sample after |
|---|---:|---:|---:|---:|
| ignored | 127 | 127 | 730 | 730 |
| hidden | 738 | 738 | 219 | 219 |
| ignoredReasons | 273 | 273 | 222 | 222 |
| role | 571 | 82 | 228 | 228 |
| name | 586 | 586 | 3,932 | 3,932 |
| nameSource | 23 | 23 | 59 | 59 |
| description | 452 | 452 | 498 | 498 |
| parent | 627 | 627 | 609 | 609 |
| exposedParent | 235 | 235 | 988 | 988 |
| chromeOnly | 874 | 799 | 2,380 | 2,267 |
| oursOnly | 737 | 693 | 925 | 820 |
| prop.posinset, prop.setsize | 151 each | 0 | 0 | 0 |
| prop.invalid | 45 | 0 | 1 | 0 |
| prop.readonly | 36 | 0 | 1 | 0 |
| prop.disabled | 79 | 13 | 1 | 0 |
| prop.valuetext | 83 | 0 | 3 | 0 |
| prop.valuemin, prop.valuemax | 9, 21 | 0, 0 | 0 | 0 |
| prop.roledescription | 19 | 0 | 11 | 0 |
| prop.selected | 571 | 18 | 18 | 10 |
| prop.autocomplete | 6 | 0 | 0 | 0 |
| prop.hasPopup | 61 | 0 | 6 | 0 |
| prop.editable | 73 | 4 | 3 | 0 |
| prop.expanded | 10 | 0 | 2 | 0 |
| prop.level | 29 | 1 | 4 | 4 |
| prop.keyshortcuts | 9 | 0 | 0 | 0 |
| prop.required, prop.multiline | 2, 1 | 0, 0 | 0 | 0 |
| prop.url, prop.focusable, rel.* | unchanged | unchanged | unchanged | unchanged |
| value | 86 | 40 | 2 | 2 |

The final code was run on both sets. Every field not named is equal; none rose. The final rates come from the next full-corpus run.

### What is left, per field

| Field | Left | Why |
|---|---|---|
| `disabled` | 13 on the subset | An `a` inside an `object` (the plug-in fallback content) is disabled in Chrome, with no ancestor that says so. Not traced further. |
| `selected` | 18 on the subset | A tab in a tab list of `aria-multiselectable` accordion panels states nothing in Chrome although no tab says anything; we state `false`. A row with `aria-selected=false`. The rule behind the first is not clear from the probes. |
| `value` | 40 on the subset | A button with the combobox role whose content has an `svg` with a title: Chrome's value includes the title ("1 downwardArrowQuantity"), ours the text only (30). A select with a trailing direction mark (`\u200e`) that Chrome trims (2). A custom combobox whose hidden part Chrome leaves out of the value (1). A text field with `contenteditable=false` and `role=textbox`, whose text Chrome joins with its line breaks (3). Other select cases (3). An input with `role=status` (1). |
| `autocomplete`, `hasPopup`, `keyshortcuts`, `invalid`, `readonly`, `roledescription`, `valuetext`, `valuemin`, `valuemax`, `posinset`, `setsize` | 0 on the subset | Fixed. |
| `editable` | 4 on the subset | Static text inside an editing host that our tree does not mark; not traced. |
| `prop.url` | about 0.9% | `srcset` choice, see above; not in this unit's list. |
| `chromeOnly` | 830 on the subset (0.6%) | Not reduced to one cause. The largest single class found by tracing is a harness artefact: pages that link their stylesheets with `crossorigin` from another host (a CDN, with a subresource-integrity hash) load in our cascade but are rejected by Chrome in the capture, because the stored response has no CORS headers. A Bootstrap `.modal { display: none }` hides the dialog for us and not for Chrome, so Chrome's whole dialog subtree is `chromeOnly` (traced on one page; whether the same cause is behind the 80-page `listitem` and `list` classes was not checked). Fixing it means serving the stored sheets with `Access-Control-Allow-Origin` in the capture tool, which needs a re-capture; it is not a library difference. The rest is the generic, `StaticText` and `ListMarker` classes above. |

### Behaviour not copied

- The Chrome value of an editing host with block content (`x\n\nbs` for a `div` holding a `p`, a button and a span) depends on layout line breaks; ours has none (`ChromePropertyProbeTests`).
- `aria-selected=false` on a `row`: Chrome states nothing, we state `false` (as for the grid cell and option, which state it).
- Step mismatch counts only from a `min` (the step base is the `min`, else the `value` itself).

## Findings on the fixture pages

The fixture pages (`testdata/rendered/pages`) were captured with Chrome 156 (headless, script off, 1280×800). After the fixes listed in the profile, what is left is below, each with a verdict. "Chrome" means Chrome's choice where the specifications leave room or are silent; "ours" means we do not yet do what Chrome does and no specification says otherwise. Evidence is Chrome's output on the page named.

| Class | Verdict |
|---|---|
| `chromeOnly`: `ListMarker`, generated `StaticText` (`::before`/`::after` content), `LineBreak`, `MenuListPopup`, the shadow content of date, number, textarea and select controls, the `StaticText` of a submit button's value | **Needs rendering; partly done.** Chrome creates these from layout objects and user-agent shadow trees. They have no DOM node in the document. With facts the list marker is a node of ours (profile entry `list-marker-node`) and the select popup too (`layout-select-popup`); generated `::before` and `::after` boxes and text (`generated-content-node`), the text of input buttons and the inner editor of text fields (`control-text-node`) are nodes too; the shadow content of date, file, range and select controls is not. HTML-AAM and CSS Content give generated content a place in names (done in the name computation) but not in the tree. |
| `role`: `LayoutTable`, `LayoutTableRow`, `LayoutTableCell` against `table`, `row`, `cell`, `generic` | **Chrome.** Chrome gives the internal layout-table roles to tables it judges to be for layout (a one-cell table, `display: table` boxes) and keeps `table`, `row` and `cell` for data tables. HTML-AAM maps `table` to `table`. Without facts the heuristic is not reproduced. With facts it is (profile entry `layout-table`), fitted on 171 tables of the corpus sample. |
| `ignored`/`ignoredReasons`: a `label` whose control is a checkbox or radio button is ignored with `labelFor`, and its text is `presentationalRole` | **Chrome**, observed on three labels, all of them checkbox or radio labels with the control first. `label` elements around text fields (control after the text) are `LabelText`. Which of "checkbox or radio" and "control first" decides is not determined by the fixtures. A capture of `<label>text <input type=checkbox></label>` and `<label><input type=text> text</label>` would settle it. |
| `ignored`, `ignoredReasons`, `role`: cells and rows of a table with `role=presentation` | **Chrome** differs from the inherited-presentational rule we follow (WAI-ARIA 1.2 section 5.2.7): its `tbody` and `tr` are ignored as `uninteresting` and its `td` are `generic` and exposed. We make them all `presentationalRole`. Observed on one table. |
| `ignored`: `template` | **Chrome**, unexplained: a `template` directly in the body is `generic`, a `template` in a `ul` is ignored. We ignore both (a template has no rendering). |
| `prop.focusable` on `iframe` | **Chrome** does not report an iframe as focusable. HTML section 6.6.3 lists navigable containers as focusable areas, so we do. |
| `value`: `No file chosen` on a file input | **Reproduced** since the second pass (profile entry `input-password-file`). |
| `name`: `mi` text `𝑥` against `x` | **Chrome** applies `text-transform: math-auto` from the MathML Core user-agent style to a single-character `mi`; our cascade does not implement that value. |
| `parent`: children of `b`, `i` and `visibility: hidden` elements | **Representation.** We keep these as ignored nodes (the unpruned `parent` therefore names them); Chrome has no node. `exposedParent` agrees. |
| `parent`, `exposedParent`: `option` and `optgroup` under `MenuListPopup` | **Chrome** puts the options of a drop-down select in a popup node that exists only while laid out; ours are children of the combobox. |
| `oursOnlyIgnored`: `noscript`, `visibility: hidden`, `aria-hidden` | **Representation**, see "Matching". |

Profile entries added or confirmed from this run are in `accessibility-chromium-profile.md` (evidence "observed in Chrome output"). Unobserved and worth a capture: an empty `div` and `span`; `u`, `s`, `small` and other inline formatting elements; a nested list; `<label>` with each control type and position; the other date and time input types; nested tables and `role=presentation` tables with `th`.


<!-- https://recursiveai.org/onehtml/docs/axe-differential/ -->

# The axe-core differential

`OneHtml.Differential axe` compares what the checker (`RecursiveAI.OneHtml.Accessibility.Validation`) concludes about a page with
what axe-core 4.14.0 concluded about the same page in Chrome for Testing 156.0.8078.47. axe-core is a black box here: it is
injected into the page, run, and only its results are read (`tools/capture`). Nothing in this comparison reads its code.

The comparison is per rule and per element. For each rule it publishes the pages where the rule applies, how many elements
both sides judge the same way, and every kind of disagreement with examples. A disagreement is either fixed in the rule or
described under "Differences" below and in the rule's page in `docs/rules/`. Where ACT and axe disagree, ACT wins.

## Running it

```
OneHtml.Differential axe <capture-dir> [--corpus <corpus-or-stylesheet-dir>] [--out <dir>] [--facts on|off|both] [--jobs n]
                         [--limit n] [--timeout s] [--max-seconds n] [--fresh]
```

- `<capture-dir>` is the output of `tools/capture` (`captures/<sha>/<viewport>/{meta,dom,axe,snapshot}.json.gz`).
- `--corpus` supplies the stylesheets the pages link (a corpus version or a directory of `.css` files), exactly as for `ax`.
- `--facts both` (default) checks every page twice, once without rendered facts and once with the facts from the same capture's
  `DOMSnapshot`. A snapshot the adapter refuses is counted and that page is compared without facts only.
- **Resumable and chunkable.** Each finished capture leaves `<out>/parts/<sha>-<viewport>.json`; running the same command again
  skips them. `--max-seconds n` stops starting captures after n seconds and prints `REMAINING=<count>`. `--fresh` throws the
  parts away (do this after changing a rule). The summary is rebuilt from all parts each time.
- A capture whose comparison throws, hangs or times out is recorded as an error part and does not stop the run.
- `ONEHTML_AXE_DUMP_RULE=<rule> ONEHTML_AXE_DUMP_DIR=<dir>` writes, for that rule, a node listing per page (ours and axe's, side by
  side) to investigate a class.

Output in `<out>`: `summary.md` (per-rule table and the biggest classes), `summary.json` (the same, per mode, with the rules axe
ran that we do not implement and the rules of ours with no axe counterpart), `classes.json` (every class with up to five examples)
and `parts/`. Format `onehtml-axe-differential/1`.

Worker run, as for `ax` (the corpus and its captures are on the worker):

```
bash tools/OneHtml.Differential/run-worker.sh axe ~/onehtml/capture-out/<version> ~/onehtml/out/axe --corpus ~/onehtml/corpus/<version> --jobs 8
```

A 1,000-page sample takes about 3 minutes of checking at two jobs, both modes.

## What is compared

Our side is the checker run on **Chrome's serialized DOM** (`dom.json` of the capture), with the page's stylesheets in the cascade
and, in `on` mode, the rendered facts of the same capture. axe ran on the live DOM of that same page, so the two see the same
tree. The results are taken from the `CheckReport` (`ToAxeJson` maps them into the groups below, and the comparison uses the same
mapping), not parsed back from JSON:

| Ours | axe group |
|---|---|
| failed | `violations` |
| passed | `passes` |
| needs-review, needs-render | `incomplete` |
| inapplicable | the rule appears in `inapplicable` (no nodes) |

### Matching

1. **Rule.** Our rule id is axe's id (the catalogue uses axe's ids); a rule naming another axe source is mapped to it.
2. **Element.** axe's node is found in our parse of the same serialized DOM by its **XPath** (axe is asked for `xpath: true`;
   the subset it emits is absolute `name[n]` paths, an optional leading `//name[@id='x']`, and `*[name()='x']`). The unique
   **selector** is the second opinion: if the two name different elements the XPath wins and the node is counted as
   *disagreeing*; if only the selector resolves it is used; if neither does, or the target crosses a frame or shadow root, the
   node is *unresolved* and counted apart. A selector our selector parser rejects is counted too (`unresolved|selector-error`,
   2 nodes in the sample: an attribute name with a non-ASCII character).
3. **Outcome.** A result is compared as a group (violation, pass, incomplete). Needs-review and needs-render both correspond to
   `incomplete`; the report shows how many of the agreeing incompletes were each.

### Normalizations

Each of these is applied before counting, and each is stated in `summary.md`.

- **One verdict per (rule, element).** Several results of one rule on one element, from either side, collapse to the most severe
  (fail, then incomplete, then pass).
- **Text-node targets** count for their parent element; axe only reports elements.
- **Pass-only differences are not disagreements.** axe reports a pass for every candidate it examined; some of our rules report
  passes only where they have a per-element verdict. A pass reported by one side with no result at all on the other
  (`pass|none`, `none|pass`) is counted in its own column and left out of the agreement rate.
- **Container and contents.** axe reports a `table` where we report its cells (`td-has-header`, `td-headers-attr`,
  `table-fake-caption`, `th-has-data-cells`) and the like. An unmatched finding of ours and an unmatched axe finding of the same
  group on an ancestor or descendant element count as one agreement (*contained*). Passes are not paired this way.
- **Groups reported once.** For `duplicate-id`, `duplicate-id-active`, `duplicate-id-aria`, `accesskeys`, `landmark-unique`,
  `landmark-no-duplicate-banner`, `-contentinfo`, `-main` and `identical-links-same-purpose`, axe puts the finding on the first
  member of the group (measured: two banners give one violation) and we put it on every member (ACT 3ea0c8 for ids). An
  unmatched failure or review of ours counts as *collapsed* when axe reported any violation or incomplete of that rule on the
  page. With no axe finding it stays a mismatch.
- **Needs-render is not compared.** Where we cannot decide without rendered facts (`render|…` classes), the node is counted in its own
  column and left out of the agreement rate, whatever axe says. With facts the column is small; without them it is most of the contrast and
  target-size nodes.
- **`region` is compared once per page.** axe reports the wrappers it happens to reach (on Divi-style pages a wrapper passes while its
  children violate, with no rule we could find); we report the topmost element. The page verdict is the strongest non-pass outcome each
  side reports for the rule, and agrees or not as one finding.
- **Enhanced contrast is subsumed by the AA failure.** Where axe reports a `color-contrast` violation it reports `color-contrast-enhanced`
  for the same element as a pass (with the same ratio); our enhanced failure there is the same finding and counts as collapsed. ACT 09o5cg
  fails any text below 7:1, so we keep reporting it.
- **Rules only one side has** are listed, not scored: axe rules we do not implement, and our rules with no axe counterpart.
- **Agreement rate** = (agree + contained + collapsed) / (that + mismatches); unresolved nodes and pass-only differences are outside it.

Mismatch classes are named `ours|axe`, with our precise outcome (`fail`, `pass`, `review`, `render`) and axe's group
(`violation`, `pass`, `incomplete`) or `none` when that side had no result for the element.

## What axe does, from its output

Learned by writing pages and reading the results (`testdata/axe/probes/`, captured in Chrome 156 with axe 4.14.0). The expected
outcomes of the element-id'd cases are in `testdata/axe/expectations.tsv` and are checked by `AxeExpectationsTests` on every build.

- **meta-refresh** (`content="600"`): violation for delays up to 72000 s; **meta-refresh-no-exceptions** violates only delays above
  72000 s, and passes 600 s. Each `meta` is judged separately.
- **meta-viewport**: violation for `user-scalable=no`/`0` and `maximum-scale` below 2 (1.5, 1); pass for 2 and 5. **meta-viewport-large**:
  violation only for `maximum-scale` from 2 up to 5 (2 fails, 5 passes); `user-scalable=no` passes it.
- **bypass**: no node on a page with no links; incomplete ("No valid skip link found") on pages with a link and no heading, no
  landmark and no skip link; pass when any in-page link exists, also one to a missing or hidden target. **skip-link**: inapplicable
  for `href="#missing"`.
- **aria-valid-attr-value**: `aria-labelledby`, `aria-describedby` and `aria-errormessage` (with `aria-invalid="true"`) naming no id:
  incomplete; `aria-controls`, `aria-owns`, `aria-flowto`, `aria-activedescendant`, `aria-details`: violation; `aria-controls` with
  `aria-expanded="false"` passes, and with `aria-haspopup` it is incomplete; a list with one existing id passes; an empty value passes.
- **region**: violation on the topmost element holding content with no landmark inside it; the elements inside it pass. Not content:
  `button` (and its text), `iframe`, inline `svg`, empty elements. Content: text, `img`, `input`, `select`, links. An unnamed `form` and an
  unnamed `section` are not landmarks; `role="region"` is, named or not. Dialogs, alerts, `aria-live` and `header` are. A skip-link
  target is not exempt; the skip link is.
- **table-fake-caption** and **td-has-header** apply to tables with a `th`, a `caption`, or a `scope`/`headers` attribute; not to a grid of
  `td` cells (24 probe tables). `table-fake-caption` fires on a first row of one spanning `td` or `th` even when the table has a caption;
  `td-has-header` counts an empty `th` as no header (the 3 by 3 minimum is ours: every smaller probe table was a plain grid, so the size is not measured), and `td-headers-attr` fires when `headers` names a `td`.
- **aria-braille-equivalent**: incomplete (not a violation) for a braille label without accessible text and for
  `aria-brailleroledescription` without `aria-roledescription`; text content counts as accessible text.
- **aria-prohibited-attr**: `aria-braillelabel` on a generic `div` and `aria-label` on `role="text"` pass; `aria-label` on a `presentation`
  table, a `generic` or `paragraph` role and a `span` with a conflicting role list is incomplete.
- **definition-list**: a `dl` with at least one `dt` and one `dd` passes even with an unpaired `dt`.
- **p-as-heading** (`p-heading.html`): a paragraph styled bold alone, italic alone, or with `strong`/`b` passes. Bold together with a size
  well above the next paragraph's (24 px against 16 px) is a violation, also when the next paragraph is bold; a size 1.5 times the next
  paragraph's alone is incomplete; 1.33 times with bold passes. A long paragraph passes. Our rule fails two signs together (bold, italic, size
  at least 1.4 times the next paragraph's), reviews a size alone, and passes the rest.
- **identical-links-same-purpose**: one incomplete per group, on its first link. Relative and absolute targets are compared after resolving
  against the page address.
- **hidden-content** (`hidden-content.html`): every element is a pass except an element whose own computed `display` is none (the `hidden`
  attribute included), or whose `visibility` is hidden, and that holds text or an image, frame, media or object below it: incomplete. A child
  of such an element whose own display is not none passes (a `li` inside a hidden `ul`), but a child that sets `display: none` itself is
  incomplete again. An empty hidden element, one with only a comment or white space (`&nbsp;` counts), `aria-hidden`, `<details>` content, `content-visibility`,
  `template`, `script` and an image inside a hidden parent are passes. Frames, images and media that are hidden themselves are incomplete without text.
- **image-redundant-alt** (`img-redundant.html`): the image's `alt` equals, ignoring case and runs of white space, all the text of its link,
  button, `p` or `li` besides the image: violation (text before or after, text in nested `p`/`div` inside the link). Text that merely contains
  the alt (`alt="Send Flowers"` beside "Send Flowers Hand delivered") passes, as do a `div` or `span` parent, an `aria-label` that
  duplicates an image-only link, and two images in one link.
- **landmark-one-main** (`no-main.html` and probes in `misc-probes`): a rendered element with `role="dialog"` (or a `dialog` element) makes the
  rule pass on a page with no main, also with `aria-hidden="true"` and when empty; `role="alertdialog"`, `display: none` and the `hidden`
  attribute do not. No other cause was found for the 6 sample pages without a dialog.
- **color-contrast-enhanced**: reported as a pass wherever the same element violates `color-contrast` (see Normalizations).
- **color-contrast** text colour of form controls: black (`ButtonText`/`FieldText`) unless the author sets `color` on the control; not the
  parent's colour.

## Results

Sample: the first 1,000 captures of corpus 2026-10a in sha256 order (the full-corpus run follows),
one viewport, stylesheets served from the corpus, compared with `--jobs 2 --timeout 120 --corpus <the corpus>`. Checker and tree as in this repository
at the commit that holds this file; Chrome for Testing 156.0.8078.47, axe-core 4.14.0, SDK 10.0.402, run on a 7950X3D worker (16 cores, 32 threads,
load 2 to 17 from other work while it ran). Ratios are over nodes, as defined above. Pages that carry a corpus stylesheet served with a
non-CSS content type do not get that stylesheet: Chrome ignored it in the capture (the crawl had stored an HTML error page under a `.css` URL).

| | Without facts | With facts |
|---|---:|---:|
| Pages compared | 1,000 | 996 (4 snapshots refused) |
| Agreeing nodes (agree + contained + collapsed) | 830,558 | 964,964 |
| Mismatching nodes | 25,334 | 34,831 |
| Agreement | 97.04 % | 96.52 % |

Before this work the same pages agreed on 95.48 % (without facts) and 95.17 % (with: 962,485 agreeing, 48,816 mismatching nodes). With facts there
are more mismatches than without because the rules that need layout (`target-size`, `link-in-text-block`, contrast) produce verdicts only there; the
rate is over compared nodes, and needs-render nodes are not compared. With facts 5,656 `color-contrast` nodes are needs-render and not compared; without facts nearly all contrast and target-size nodes are.

### Full corpus

All 12,821 captures of corpus 2026-10a (one viewport; 10 axe errors and 4 failed captures skipped; 29 snapshots refused for the
facts mode), `--jobs 8 --timeout 300`, same pins and checker, on the same worker at load 1 to 2. Agreement is over nodes as above,
summed from each rule's Agree %.

| | Without facts | With facts |
|---|---:|---:|
| Pages compared | 12,807 | 12,778 |
| Agreeing nodes (agree + contained + collapsed) | 10,130,665 | 11,789,751 |
| Mismatching nodes | about 259,000 | about 400,000 |
| Agreement | 97.51 % | 96.72 % |

Lowest rules with facts: `aria-required-parent` 89.2 %, `hidden-content` 89.7 %, `label-content-name-mismatch` 91.2 %,
`link-in-text-block` 91.7 %, `color-contrast` 93.4 %, `color-contrast-enhanced` 93.8 %, `target-size` 95.5 %, `aria-allowed-role`
96.0 %; their classes are the ones described under "Differences" and in the rule pages. The largest classes on the full corpus are the
kept ones: contrast `pass|incomplete` and `none|incomplete` (axe stops where we have the stacking or the text is symbols only) and
`target-size` `pass|violation` for user-agent controls (WCAG 2.5.8 exempts them).

Two axe rules have no counterpart here, on purpose:

- `aria-roledescription` is in axe's deprecated group.
- `frame-tested` reports whether axe itself could run inside each frame. A checker that reads a document has no frames to run in;
  a frame's own document is checked by checking that document.

### Per rule

All rules with nodes on the sample, largest number of mismatches with facts first. Agree is (agree + contained + collapsed) over that plus the
mismatches; pass-only differences and needs-render nodes are outside it. The largest classes are `ours|axe` as defined above, with facts.

| Rule | Nodes axe / ours (with facts) | Agree without facts | Agree with facts | Mismatch without → with | Largest classes with facts |
|---|---|---|---|---|---|
| color-contrast | 177896 / 178062 | 93.1 % | 92.4 % | 9811 → 12932 | pass\|incomplete 9849, none\|incomplete 1871, fail\|incomplete 850 |
| color-contrast-enhanced | 177896 / 178062 | 93.3 % | 92.5 % | 9567 → 12672 | pass\|incomplete 9328, fail\|incomplete 1362, none\|incomplete 1197 |
| target-size | 103294 / 116466 | 91.1 % | 96.2 % | 138 → 3541 | pass\|violation (user agent control) 1739, pass\|violation 738, review\|none 376 |
| hidden-content | 932209 / 13705 | 93.5 % | 93.6 % | 947 → 933 | none\|incomplete 773, review\|pass 156, unresolved\|selector-error 4 |
| css-orientation-lock | 996 / 0 | 0.0 % | 0.0 % | 646 → 644 | none\|incomplete 644 |
| duplicate-id-aria | 7895 / 8388 | 95.2 % | 95.2 % | 407 → 405 | fail\|incomplete 405 |
| skip-link | 275 / 1622 | 43.7 % | 44.0 % | 354 → 348 | fail\|none 346, fail\|pass 1, fail\|incomplete 1 |
| identical-links-same-purpose | 76974 / 49339 | 98.9 % | 98.9 % | 334 → 330 | review\|pass 128, none\|incomplete 122, review\|none 63 |
| aria-hidden-focus | 13619 / 14730 | 97.7 % | 97.6 % | 328 → 328 | fail\|incomplete 178, fail\|none 150 |
| aria-prohibited-attr | 16332 / 16257 | 98.0 % | 98.0 % | 326 → 319 | fail\|incomplete 224, fail\|pass 72, pass\|violation 11 |
| label-content-name-mismatch | 3106 / 3206 | 92.2 % | 91.1 % | 237 → 278 | none\|incomplete 89, fail\|none 60, pass\|violation 58 |
| aria-valid-attr-value | 16332 / 39523 | 98.3 % | 98.4 % | 275 → 265 | pass\|incomplete 168, review\|none 51, fail\|none 27 |
| link-in-text-block | 2766 / 3027 | 89.9 % | 90.6 % | 271 → 250 | fail\|incomplete 79, fail\|pass 66, fail\|none 60 |
| aria-required-parent | 963 / 850 | 84.0 % | 83.9 % | 137 → 137 | pass\|violation 137 |
| duplicate-id | 62620 / 64350 | 99.7 % | 99.8 % | 166 → 137 | fail\|none 71, none\|violation 66 |
| aria-allowed-role | 13912 / 6478 | 98.0 % | 98.0 % | 134 → 132 | none\|incomplete 67, fail\|pass 28, pass\|violation 24 |
| focus-order-semantics | 560 / 743 | 81.4 % | 81.4 % | 127 → 126 | fail\|none 118, fail\|pass 6, pass\|violation 1 |
| p-as-heading | 4149 / 4726 | 96.1 % | 96.1 % | 119 → 119 | pass\|violation 38, review\|violation 28, review\|pass 16 |
| link-name | 115339 / 113760 | 99.9 % | 99.9 % | 106 → 105 | pass\|violation 64, none\|violation 34, fail\|pass 7 |
| landmark-complementary-is-top-level | 690 / 574 | 85.1 % | 85.1 % | 100 → 100 | none\|violation 99, fail\|pass 1 |
| presentation-role-conflict | 3750 / 7004 | 98.3 % | 98.3 % | 64 → 64 | fail\|none 62, unresolved\|selector-error 1, pass\|violation 1 |
| aria-allowed-attr | 16332 / 16257 | 99.7 % | 99.7 % | 47 → 47 | fail\|pass 40, pass\|violation 7 |
| form-field-multiple-labels | 5235 / 4057 | 98.9 % | 98.9 % | 47 → 47 | none\|incomplete 44, review\|pass 3 |
| bypass | 969 / 996 | 95.4 % | 95.4 % | 46 → 46 | fail\|none 24, fail\|incomplete 15, fail\|pass 7 |
| landmark-one-main | 996 / 996 | 95.7 % | 95.7 % | 43 → 43 | fail\|pass 43 |
| landmark-unique | 4665 / 5850 | 99.3 % | 99.3 % | 42 → 42 | fail\|pass 18, fail\|none 18, none\|violation 6 |
| aria-command-name | 593 / 1750 | 93.8 % | 93.7 % | 40 → 40 | fail\|none 38, pass\|violation 2 |
| aria-required-children | 315 / 278 | 86.0 % | 86.6 % | 39 → 37 | pass\|violation 27, fail\|incomplete 8, fail\|pass 2 |
| td-has-header | 71 / 1340 | 41.4 % | 42.1 % | 34 → 33 | none\|violation 28, fail\|none 5 |
| region | 579724 / 2893 | 95.2 % | 95.2 % | 30 → 30 | fail\|none 16, none\|violation 12, unresolved\|selector-error 2 |
| label | 4996 / 4996 | 99.5 % | 99.5 % | 25 → 25 | fail\|pass 21, pass\|violation 3, pass\|incomplete 1 |
| scope-attr-valid | 96 / 210 | 80.7 % | 80.7 % | 23 → 23 | fail\|none 23 |
| aria-dialog-name | 118 / 86 | 81.1 % | 81.1 % | 20 → 20 | none\|violation 20 |
| th-has-data-cells | 162 / 439 | 0.0 % | 0.0 % | 20 → 20 | fail\|none 15, none\|incomplete 5 |
| duplicate-id-active | 4506 / 6843 | 98.6 % | 99.6 % | 77 → 19 | fail\|none 18, none\|violation 1 |
| page-has-heading-one | 996 / 996 | 98.1 % | 98.1 % | 19 → 19 | fail\|pass 19 |
| aria-required-attr | 6564 / 5477 | 99.6 % | 99.7 % | 23 → 17 | fail\|pass 15, pass\|violation 2 |
| empty-table-header | 446 / 439 | 96.1 % | 96.1 % | 17 → 17 | review\|violation 17 |
| image-alt | 14389 / 14384 | 99.9 % | 99.9 % | 17 → 16 | fail\|pass 12, unresolved\|selector-error 2, pass\|violation 2 |
| table-fake-caption | 162 / 105 | 85.5 % | 85.5 % | 16 → 16 | pass\|violation 11, none\|violation 5 |
| button-name | 5450 / 5279 | 99.7 % | 99.7 % | 15 → 15 | pass\|violation 13, fail\|none 2 |
| input-button-name | 342 / 344 | 96.2 % | 96.2 % | 13 → 13 | pass\|violation 13 |
| label-title-only | 5235 / 4745 | 99.7 % | 99.7 % | 12 → 12 | fail\|pass 7, pass\|violation 5 |
| nested-interactive | 29891 / 42945 | 100.0 % | 100.0 % | 12 → 12 | none\|violation 6, fail\|none 4, unresolved\|selector-error 1 |
| landmark-no-duplicate-banner | 792 / 843 | 98.8 % | 98.8 % | 10 → 10 | fail\|pass 5, fail\|none 5 |
| list | 16760 / 17138 | 100.0 % | 100.0 % | 7 → 7 | fail\|pass 6, fail\|none 1 |
| select-name | 239 / 239 | 97.2 % | 97.1 % | 7 → 7 | fail\|pass 7 |
| landmark-no-duplicate-contentinfo | 796 / 830 | 99.4 % | 99.4 % | 5 → 5 | none\|violation 5 |
| frame-title-unique | 70 / 12 | 66.7 % | 66.7 % | 4 → 4 | pass\|incomplete 4 |
| video-caption | 26 / 28 | 68.6 % | 85.7 % | 11 → 4 | review\|pass 2, review\|none 2 |
| aria-valid-attr | 16332 / 39602 | 100.0 % | 100.0 % | 3 → 3 | fail\|none 3 |
| definition-list | 326 / 326 | 99.1 % | 99.1 % | 3 → 3 | fail\|pass 3 |
| image-redundant-alt | 14389 / 7219 | 100.0 % | 100.0 % | 3 → 3 | unresolved\|selector-error 2, none\|violation 1 |
| aria-input-field-name | 11 / 41 | 89.5 % | 84.6 % | 2 → 2 | fail\|none 2 |
| audio-caption | 3 / 1 | 66.7 % | 33.3 % | 1 → 2 | none\|incomplete 2 |
| heading-order | 12489 / 12451 | 100.0 % | 100.0 % | 2 → 2 | pass\|violation 1, fail\|none 1 |
| landmark-no-duplicate-main | 641 / 657 | 99.7 % | 99.7 % | 2 → 2 | fail\|pass 1, fail\|none 1 |
| empty-heading | 12489 / 12451 | 100.0 % | 100.0 % | 1 → 1 | pass\|violation 1 |
| meta-refresh-no-exceptions | 1 / 1 | 0.0 % | 0.0 % | 1 → 1 | fail\|pass 1 |
| object-alt | 1 / 2 | 50.0 % | 50.0 % | 1 → 1 | fail\|none 1 |
| accesskeys | 73 / 82 | 100.0 % | 100.0 % | 0 → 0 | - |
| area-alt | 26 / 26 | 100.0 % | 100.0 % | 0 → 0 | - |
| aria-conditional-attr | 16332 / 2 | 100.0 % | 100.0 % | 0 → 0 | - |
| aria-deprecated-role | 6564 / 6515 | 100.0 % | 100.0 % | 0 → 0 | - |
| aria-hidden-body | 996 / 996 | 100.0 % | 100.0 % | 0 → 0 | - |
| aria-progressbar-name | 12 / 12 | 100.0 % | 100.0 % | 0 → 0 | - |
| aria-roles | 6564 / 6532 | 100.0 % | 100.0 % | 0 → 0 | - |
| aria-tab-name | 38 / 213 | 100.0 % | 100.0 % | 0 → 0 | - |
| aria-toggle-field-name | 26 / 45 | 100.0 % | 100.0 % | 0 → 0 | - |
| aria-tooltip-name | 10 / 10 | 100.0 % | 100.0 % | 0 → 0 | - |
| autocomplete-valid | 399 / 151 | 100.0 % | 100.0 % | 0 → 0 | - |
| avoid-inline-spacing | 10350 / 698 | 100.0 % | 100.0 % | 0 → 0 | - |
| dlitem | 1138 / 1138 | 100.0 % | 100.0 % | 0 → 0 | - |
| document-title | 996 / 996 | 100.0 % | 100.0 % | 0 → 0 | - |
| frame-title | 137 / 137 | 100.0 % | 100.0 % | 0 → 0 | - |
| html-has-lang | 996 / 996 | 100.0 % | 100.0 % | 0 → 0 | - |
| html-lang-valid | 938 / 937 | 100.0 % | 100.0 % | 0 → 0 | - |
| html-xml-lang-mismatch | 24 / 24 | 100.0 % | 100.0 % | 0 → 0 | - |
| input-image-alt | 11 / 11 | 100.0 % | 100.0 % | 0 → 0 | - |
| landmark-banner-is-top-level | 842 / 843 | 100.0 % | 100.0 % | 0 → 0 | - |
| landmark-contentinfo-is-top-level | 830 / 830 | 100.0 % | 100.0 % | 0 → 0 | - |
| landmark-main-is-top-level | 656 / 657 | 100.0 % | 100.0 % | 0 → 0 | - |
| listitem | 75186 / 74771 | 100.0 % | 100.0 % | 0 → 0 | - |
| marquee | 5 / 5 | 100.0 % | 100.0 % | 0 → 0 | - |
| meta-refresh | 1 / 1 | 100.0 % | 100.0 % | 0 → 0 | - |
| meta-viewport | 988 / 159 | 100.0 % | 100.0 % | 0 → 0 | - |
| meta-viewport-large | 988 / 159 | 100.0 % | 100.0 % | 0 → 0 | - |
| role-img-alt | 158 / 158 | 100.0 % | 100.0 % | 0 → 0 | - |
| scrollable-region-focusable | 80 / 45 | 100.0 % | 100.0 % | 0 → 0 | - |
| summary-name | 132 / 132 | 100.0 % | 100.0 % | 0 → 0 | - |
| svg-img-alt | 360 / 360 | 100.0 % | 100.0 % | 0 → 0 | - |
| tabindex | 2743 / 93 | 100.0 % | 100.0 % | 0 → 0 | - |
| table-duplicate-name | 491 / 1 | 100.0 % | 100.0 % | 0 → 0 | - |
| valid-lang | 501 / 327 | 100.0 % | 100.0 % | 0 → 0 | - |

Before this work, with facts (mismatching nodes): `target-size` 7,751 (92.2 % agree), `link-in-text-block` 10,663 (18.4 %), `listitem` 581,
`color-contrast` 13,812 (91.9 %), `color-contrast-enhanced` 10,431 (93.6 %); the last grew to 12,672 because symbol-only text is now counted
(the kept `pass|incomplete` class below), not because anything got worse. `aria-required-parent` and `empty-heading` had grown after the tree
changes (29 to 166 and 1 to 68); they are back to 137 (one page, kept) and 1.

### Checker time

Per page, the whole rule set (`checkMs` of each page), 1,000 pages; "before" is the checker at the start of this work with the same harness.

| | Median | p95 | Max | Sum |
|---|---:|---:|---:|---:|
| Without facts, before | 38 ms | 1,768 ms | 24,489 ms | 415.6 s |
| Without facts, after | 5 ms | 275 ms | 8,825 ms | 57.4 s |
| With facts, before | 38 ms | 1,754 ms | 24,166 ms | 412.1 s |
| With facts, after | 9 ms | 259 ms | 7,973 ms | 58.0 s |

The saving is the focus overlays: `focus-visible-indicator` restyles only what a focus reaches instead of the whole page per focusable. The slowest
page (06e2ed1a8276, 8 s) had a `.x:has(:focus-visible)` rule, which made every focus overlay match every element; focus read inside
`:has()` is now bounded to the focused element's ancestors (see `cascade.md`). On the same 1,000 pages the check then takes a median of
6 ms, p95 169 ms and a maximum of 982 ms without facts (9 ms, 174 ms, 1,006 ms with), with native result JSON byte-identical to before. The
slowest pages now spend most of the time in `css-orientation-lock`, which styles the page in two viewports. Numbers are from one run each and the worker was shared.

### Pages written for the differential

`testdata/axe/pages` and `testdata/axe/probes` are pages written for this repository, one question each; `expectations.tsv` records
axe's outcome for the elements with an id. A fifth column marks the six rows where our verdict deliberately differs (listed below).

| Page | Settles |
|---|---|
| `fallback-roles`, `role-text`, `braille`, `checkbox-aria-checked`, `broken-refs`, `duplicate-ids` | the open questions of the ARIA and id rules (below) |
| `table-headers`, `table-probes` | `td-has-header`, `table-fake-caption` and the other table rules (the two rules were written from one-line descriptions) |
| `idrefs`, `dup-aria` | every ID-reference attribute with a dangling id; duplicated ids referenced by ARIA |
| `meta-refresh`, `viewport`, `bypass-*`, `region-*`, `links-same`, `misc-probes` | the axe behaviours in "What axe does" |
| `axe-misc`, `labels`, `date-inputs`, `empty-and-inline`, `nested-lists`, `nested-tables`, `template-list`, `no-lang` | broad coverage, and the Chrome accessibility-tree pages (below) |

The golden page `tests/OneHtml.Accessibility.Validation.Tests/Golden/aria-page.html` was captured as well.

## Differences

Each mismatch class of the 1,000-page sample and of the written pages is fixed, kept on purpose, or open. Dispositions are also in the rule pages
(`docs/rules/*.md`, "Measured against axe-core 4.14.0").

**Fixed because of the differential** (earlier work, then this round):

- Earlier: dangling ID references (`aria-valid-attr-value`); `aria-braille-equivalent`; native radio in `aria-conditional-attr`; the data-table gate of
  `td-has-header` and `table-fake-caption`; complementary inside `main`; `meta-viewport-large` range; `region` content definition;
  `hidden-content` (own computed display or visibility, embedded objects, `&nbsp;`); `image-redundant-alt` (equality of the container's other text);
  `p-as-heading` observed thresholds; `identical-links-same-purpose` (relative links resolve against the page address); the text colour of form controls.
- `link-in-text-block`: a block of text is the nearest block whose text outside links is longer than the text of its links; a link alone in
  its block is not applicable; a background image on the link is a cue. 10,663 mismatching nodes to 250.
- `target-size`: the target is the element's own border box; focusable widgets and `summary` are targets; the order of tests follows axe's (size,
  in-sentence, user-agent control, fully covered, spacing, then content overflow); `aria-hidden` controls are neighbours without verdict;
  completely covered targets (later in tree order, or later painted) are not targets. 7,751 to 3,541.
- `listitem`: an `li` hidden from assistive technology is not examined (581 `fail|none` to 0).
- `color-contrast`: push-button `input` labels are judged; native button and field fills apply unless the author sets a background; text over an
  image or positioned box that is not its ancestor is never judged against the page colour (needs-render, or background samples with facts); the
  `body link` attribute colours the document's links in the cascade.
- Tree: a heading (or any role) inside a button is named from its contents again (`empty-heading` 68 to 1; the name computer had stopped seeing
  the role); a plain container between a context role and its child is looked through by `aria-required-parent` and `aria-required-children`
  (`aria-required-parent` fail|pass 29 to 0). Chrome AX differential on the first 2,095 captures with facts, before and after: ignored 0.173 %
  and 0.173 %, role 0.089 % and 0.089 %, name 0.498 % and 0.484 %, description 0.132 % and 0.132 %, exposedParent 0.245 % and 0.245 %.
- The harness did not supply a stylesheet whose recorded content type is not `text/css` (Chrome ignores such a body; the crawl had stored an
  HTML error page under a `.css` URL, and its rules produced a `fail|pass` class that looked like a cascade bug). This affects `ax`, `axe` and `styles`.

**Kept on purpose** (the reason is the spec or ACT, so it is not a bug on our side; the larger classes first):

- `color-contrast` and `-enhanced` pass|incomplete (9,849 and 9,328): text of symbols only (icon fonts). axe is incomplete ("only non-text characters"); ACT
  afw4f7 does not apply to text without letters or digits.
- `color-contrast` none|incomplete (1,871), fail|incomplete (850): empty or hidden text, and elements axe thinks are overlapped, where our facts know the stacking.
- `color-contrast` pass|violation (34): axe checks text made of punctuation only; ACT exempts it.
- `target-size` pass|violation "user agent control" (1,739): WCAG 2.5.8 exempts a control whose size the browser sets; axe measures it.
- `target-size` review|none (376), fail|incomplete (15): negative `tabindex` and content overflow, which need a person.
- `link-in-text-block` fail|pass (66): a link whose colour equals the text colour is a failure of technique F73; axe passes it. fail|incomplete (79):
  axe stops at "element overlap".
- `landmark-one-main` fail|pass (43): axe passes a page with no `main` when a rendered `dialog` exists; a dialog is not the page's main content (the
  rule keeps the spec reading, and says so in `docs/rules/structure.md`).
- `p-as-heading` (119 nodes, 96.1 %): the thresholds are ours and the rule is a best practice with no ACT rule to settle them; the rule keeps them
  and says so in `docs/rules/structure.md`.
- `aria-required-parent` pass|violation (137), `aria-required-children` pass|violation (27): an `li` between `ul[role=menu]` and its `menuitem`; Chrome's
  own tree has `menu > menuitem` (page 122a2205c3f5 supplies 112 and 21 of them).
- `aria-prohibited-attr` fail|incomplete (224), fail|pass (72); `skip-link` fail|none (346); `aria-hidden-focus` fail|incomplete (178) and fail|none (150);
  `duplicate-id-aria` fail|incomplete (405); `bypass`: as in the earlier sample (role data prohibits naming where axe warns; a fragment link to a
  missing target fails; axe is incomplete while a modal is open or needs a link).
- `css-orientation-lock` none|incomplete (644): axe is incomplete on every page with an orientation media query it cannot evaluate.

**Open** (not explained; each has examples in `classes.json`):

- `target-size` pass|violation (738), fail|pass (287), none|violation (169), fail|none (69). Mostly axe's *partially obscured* measurement (it uses the
  part of the box that other elements leave open) and neighbours it counts differently; a subtraction over later-painted boxes made 123 more nodes
  wrong and was dropped. See `docs/rules/presentation.md`.
- `link-in-text-block` fail|none (60 nodes on 32 pages): links with large boxes (images, cards) that axe does not select.
- `color-contrast` fail|pass (20, enhanced 168 in the earlier numbers) and fail|none (294).
- `hidden-content` none|incomplete (773) and review|pass (156): hidden elements axe flags that hold only elements without text or media.
- `identical-links-same-purpose` review|pass (128), none|incomplete (122), review|none (63).
- `label-content-name-mismatch` (278), `aria-valid-attr-value` pass|incomplete (168), `aria-allowed-role` none|incomplete (67), `focus-order-semantics`
  fail|none (118), `landmark-complementary-is-top-level` none|violation (99), `presentation-role-conflict` fail|none (62), `duplicate-id` (137),
  `aria-command-name` fail|none (38), `td-has-header` none|violation (28).


## Contrast, spacing and target size

The fixture pages (ACT `78fd32`, the four image-background pages of ACT `afw4f7` and `09o5cg`, and `testdata/rendered/pages/target-size.html` with its
capture) agree as before: `avoid-inline-spacing` agrees on all seven cases with facts; the image pages are needs-render on our side and incomplete on
axe's (both decline to guess); `target-size` on the fixture agrees on all 14 targets axe reports with facts. The class analysis on the sample is in the
rule pages: `docs/rules/contrast.md` (contrast, link-in-text-block) and `docs/rules/presentation.md` (target-size).

Measured axe behaviour, learned from probe pages and the sample (all black-box output):

- **target-size**: the target is the element's own border box; tests run in the order size, in-sentence, user-agent control, fully covered, spacing,
  content overflow (incomplete only after both size and spacing fail); `summary` is a target; `aria-hidden` controls count as neighbours and get no verdict;
  links with the same `href` are one target except for `#` and `javascript:`; only `overflow: hidden|clip` clips, never on `html`/`body`.
- **link-in-text-block**: identical link and text colours pass; `<script>` text counts as text; a background image on the link counts as a cue.
- **listitem**: items hidden from assistive technology are not examined.
- **color-contrast**: `input` push-button labels are judged from their value; the native fill of buttons and fields applies unless the author sets a background.

## Chrome accessibility-tree pages

The wanted pages were captured and run through `ax` (`empty-and-inline`, `nested-lists`, `labels`, `date-inputs`, `nested-tables`, `template-list`
and the rest of `testdata/axe/pages`; 19 pages, 960 matched nodes). New classes, none fixed here (they belong to the tree computation):

- **Layout tables:** Chrome's `LayoutTable`/`LayoutTableRow`/`LayoutTableCell` against our `table`/`row`/`cell` for nested and presentational tables with
  `th` (44 nodes, 3 pages). Our data/layout decision differs from Chrome's for these shapes.
- **Presentational tables:** Chrome keeps a `generic` where we ignore the table as `presentationalRole` (7).
- **Labels:** a `label` whose control precedes it: Chrome ignores it (`labelFor`), we keep a `LabelText` (14 `exposedParent`, 7 `ignored`).
- **Date and time inputs:** Chrome's `DateTime` and inner `spinbutton`s (16 nodes) are not in our tree.
- **`dt` in a `template`-containing `dl`:** Chrome names the `term` from its text (4 nodes); ours is empty.
- **`<ol><span>`**: a `generic` we expose and Chrome does not (13).
- **`u`, `s`, `small`:** text inside is attached to a `paragraph` by Chrome and a `generic` by us (`exposedParent`, 3). `role=text` children of a link or button
  reparent differently (4).
- Smaller: `select` options' `selected` (4), `aria-haspopup` on `combobox` (2), `accesskey` as `keyshortcuts` (4), `iframe` focusable (7), listitem `level` (2).

## Not done

- Frames and shadow roots: nested targets are counted, not compared.
- Partial obscuring in `target-size`, and the open classes above.
- Re-running the full corpus after a rule change (see "Full corpus"; `--timeout 300`, resumable, `--facts on|off` for one mode):
  `bash tools/OneHtml.Differential/run-worker.sh axe <capture-dir> <out> --corpus <corpus> --jobs 8 --timeout 300`.


<!-- https://recursiveai.org/onehtml/docs/changelog/ -->

# Changelog

All notable changes are listed here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and versions follow [Semantic Versioning](https://semver.org/).

## [Unreleased]

## [1.0.0] - 2026-10-26

First release. All three packages share one version.

### Added

- `RecursiveAI.OneHtml`: the WHATWG HTML parser (encoding sniffing, tokenizer, every insertion mode, foreign content, templates, fragment parsing), passing the html5lib tokenizer and tree-construction tests; the DOM as immutable arena snapshots with a byte-level source map; Selectors Level 4 and unique locator generation; CSS Syntax Level 3 parsing of `<style>`, `style=""` and caller-supplied stylesheets; the cascade for every known property, with typed computed values for the accessibility-relevant set, under a `StyleContext` (viewport, media features, focus, hover, target, active) with incremental restyle; lossless editing of HTML, inline styles, `<style>` and linked stylesheets, where untouched bytes stay identical and every result is re-parsed and verified; and a versioned JSON edit format with replay that resolves, goes stale or reports ambiguity, but never picks the wrong element. See `docs/edit-format.md`.
- `RecursiveAI.OneHtml.Accessibility`: the accessibility tree (WAI-ARIA 1.2, HTML-AAM, AccName 1.2, Core-AAM, SVG-AAM) with each role, name and hidden state traced to its source, Chromium's choices listed in `docs/accessibility-chromium-profile.md`, incremental recompute after edits, a reading view, navigation lists, tree and reading-view diffs, an export in Chrome's AX-tree shape, and `RenderedFacts` from a Chrome `DOMSnapshot` supplied by the caller.
- `RecursiveAI.OneHtml.Accessibility.Validation`: one rule catalogue covering axe-core's WCAG and best-practice rules (the two with no counterpart are explained in `docs/axe-differential.md`) and every W3C-approved ACT rule, labelled by WCAG version, level and criterion; profiles for WCAG 2.0 AA, 2.1 AA, 2.2 AA and everything; contrast that never guesses a background; incremental re-check after an edit; suggested edits for the rules that have exactly one correct fix; native JSON, axe-compatible JSON and SARIF 2.1.0 output. Coverage per criterion is in `docs/coverage.md`.

[1.0.0]: https://github.com/recursive-ai-oss/onehtml-csharp/releases/tag/v1.0.0


<!-- https://recursiveai.org/onehtml/cookbook/accessibility-tree/ -->

# The accessibility tree of a page

Compute the tree a browser exposes to screen readers, with roles, accessible names, levels and hidden state, from HTML and CSS alone, and get the landmark and heading lists a screen-reader user navigates by.

`AccessibilityTree.Build` takes a document and its cascade. It applies WAI-ARIA 1.2, HTML-AAM, AccName 1.2, Core-AAM and SVG-AAM, and uses Chromium’s choices where the specifications leave room. Each of those choices is listed in [Chromium profile](https://recursiveai.org/onehtml/docs/accessibility-chromium-profile/).

```csharp
using RecursiveAI.OneHtml;
using RecursiveAI.OneHtml.Css;
using RecursiveAI.OneHtml.Accessibility;

Document doc = Document.Parse(File.ReadAllBytes("events.html"));
AccessibilityTree tree = AccessibilityTree.Build(doc, DocumentStyles.Create(doc));

// The tree as an outline: role, name, and the states that are set
void Print(AxNode node, int depth)
{
    if (!node.IsIgnored)
    {
        string name = node.Name.IsEmpty ? "" : $" \"{node.Name.Value}\"";
        string level = node.States.Level is int l ? $" level={l}" : "";
        Console.WriteLine($"{new string(' ', depth * 2)}{node.Role}{name}{level}");
        depth++;
    }
    foreach (AxNode child in node.Children)
    {
        Print(child, depth);
    }
}
Print(tree.Root, 0);

// Why an element is named the way it is, and why one is missing from the tree
Node logo = doc.Root.QuerySelector("a.logo");
AxText logoName = tree.ComputeName(logo);
Console.WriteLine($"Logo link name \"{logoName.Value}\" comes from {logoName.Source}");

Node icon = doc.Root.QuerySelector("button svg");
AxNode? iconNode = tree.Find(icon);
Console.WriteLine($"Icon ignored: {iconNode?.IsIgnored}, hidden: {tree.GetHidden(icon).Reasons}");

// The lists a screen reader offers for jumping around
NavigationLists lists = tree.CreateNavigationLists();
foreach (LandmarkEntry landmark in lists.Landmarks)
{
    Console.WriteLine($"{new string(' ', landmark.Depth * 2)}{landmark.Role} {landmark.Name}".TrimEnd());
}
foreach (HeadingEntry heading in lists.Headings)
{
    Console.WriteLine($"{new string(' ', (heading.Level - 1) * 2)}h{heading.Level} {heading.Name}");
}

// The same tree in Chrome's AX-tree JSON shape
File.WriteAllText("events.ax.json", tree.ToChromeJson());
```

```text
RootWebArea "Events | Harbor Street Library"
  banner
    link "Harbor Street Library"
      image "Harbor Street Library"
    navigation "Main"
      list
        listitem level=1
          link "Books"
            StaticText "Books"
        listitem level=1
          link "Events"
            StaticText "Events"
        listitem level=1
          link "Visit"
            StaticText "Visit"
  main
    heading "Upcoming events" level=1
      StaticText "Upcoming events"
    article
      heading "Story time for ages 3–5" level=2
        StaticText "Story time for ages 3–5"
      paragraph
        StaticText "Saturdays at 10:30 in the children’s room. "
        link "Details"
          StaticText "Details"
      image
    article
      heading "Repair café" level=2
        StaticText "Repair café"
      paragraph
        StaticText "Bring a lamp, a toaster or a torn jacket. Volunteers fix what they can. "
        link "Partner site"
          StaticText "Partner site"
      image "Volunteers at a workbench fixing a lamp"
    form
      textbox "Your email"
      button
  contentinfo
    paragraph
      StaticText "© 2026 Harbor Street Library · "
      link "hello@example.org"
        StaticText "hello@example.org"
  button "Back to top"
    StaticText "Back to top"
Logo link name "Harbor Street Library" comes from Contents
Icon ignored: True, hidden: AriaHidden
banner
  navigation Main
main
  form
contentinfo
h1 Upcoming events
  h2 Story time for ages 3–5
  h2 Repair café
```

What the output shows:

- **Ignored nodes are left out of the outline.** The code skips them but still visits their children, which carry their own status. `IgnoredReasons` on each node says why it was ignored.
- **Names are traced.** `ComputeName` returns the name with its `Source` (`Contents`, `NativeAttribute`, `Placeholder` and others) and the elements it came from (`RelatedElements`). The logo link is named from the `alt` of the image inside it.
- **Hidden content says why.** The submit button’s icon is `aria-hidden`, so it is ignored and the button has no name. That is the `button-name` failure in [Run WCAG checks in CI](https://recursiveai.org/onehtml/cookbook/wcag-checks-ci-sarif/).
- **Landmarks and headings** come from `CreateNavigationLists()`, which also lists links, form fields and tables, each mapped back to its node.

Each `AxNode` also has `States` (checked, expanded, level, required and more), `Relations`, `Focus` and `Diagnostics` (invalid roles, broken ID references, missing required parents). `DomNode` and `SourceBytes` lead back to the markup. `tree.FocusOrder` is the Tab order.

**Without a browser, there is no layout.** Hiding that depends on layout, such as zero size, clipping or off-screen positioning, isn’t known. With a Chrome `DOMSnapshot` you capture yourself and pass as `RenderedFacts`, the tree adds the choices Chromium makes once layout is known (see [Rendered facts](https://recursiveai.org/onehtml/docs/rendered-facts/)).

`ToChromeJson()` writes the tree in the shape of Chrome’s accessibility tree, for comparing with a real browser. How closely it matches is measured in [Chrome AX differential](https://recursiveai.org/onehtml/docs/chrome-ax-differential/). After an edit, `tree.Update(edit, restyle)` recomputes only what the edit reached, and the result equals a full rebuild. For the page as a sequence of announcements, see [Extract visible text](https://recursiveai.org/onehtml/cookbook/extract-visible-text/).

DOM vs accessibility tree, compared with Chrome’s: [The accessibility tree](https://recursiveai.org/onehtml/articles/accessibility-tree/).


<!-- https://recursiveai.org/onehtml/cookbook/apply-suggested-fixes/ -->

# Apply suggested accessibility fixes

Take the edits the checker suggests for rules with exactly one correct fix, apply the ones you accept as lossless edits, and re-check only what changed.

Most accessibility failures need a person: only the author knows what an image shows or what a button does. A few have one fix that needs no judgment. For those, the checker attaches a suggested edit. In 1.0.0 these are `aria-conditional-attr`, `aria-deprecated-role`, `aria-hidden-body`, `aria-valid-attr`, `avoid-inline-spacing`, `scope-attr-valid` and `tabindex`. The library never applies a suggestion by itself.

The input is a staff page with six failures that have a suggested fix, and two `listitem` failures that don’t:

```html
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Staff directory | Harbor Street Library</title>
</head>
<body>
<main>
  <h1>Staff directory</h1>
  <ul role="directory">
    <li>Ana Ruiz, branch manager</li>
    <li>Sam Okafor, children's librarian</li>
  </ul>
  <table>
    <tr><th scope="column">Desk</th><th scope="column">Hours</th></tr>
    <tr><td>Reference</td><td>9 to 6</td></tr>
  </table>
  <p style="letter-spacing: 0.1em !important" aria-describedy="note">Call ahead for appointments.</p>
  <a href="/contact/" tabindex="3">Contact us</a>
</main>
</body>
</html>
```

```csharp
using System.Text;
using RecursiveAI.OneHtml;
using RecursiveAI.OneHtml.Css;
using RecursiveAI.OneHtml.Editing;
using RecursiveAI.OneHtml.Accessibility;
using RecursiveAI.OneHtml.Accessibility.Validation;
using RecursiveAI.OneHtml.Accessibility.Validation.Catalogue;

byte[] input = File.ReadAllBytes("staff.html");
Document doc = Document.Parse(input);
DocumentStyles styles = DocumentStyles.Create(doc);
AccessibilityTree tree = AccessibilityTree.Build(doc, styles);

var checker = new Checker();
var options = new CheckOptions { Profile = ValidationProfile.All };
CheckReport report = checker.Check(tree, options);

foreach (RuleResult result in report.WithOutcome(Outcome.Failed))
{
    string fix = result.SuggestedEdits.Count > 0 ? result.SuggestedEdits[0].Description : "no suggested edit";
    Console.WriteLine($"{result.RuleId}: {fix}");
}

// The library never applies a suggestion; you decide which ones to take
IReadOnlyList<Edit> suggestions = report.SuggestedEditList();
EditResult edit = doc.Apply(suggestions);
Console.WriteLine($"Applied {suggestions.Count} edits: {edit.Succeeded}");

// Re-check only what the edits reached
RestyleResult restyle = styles.Restyle(edit);
AccessibilityTree updated = tree.Update(edit, restyle);
CheckReport next = checker.Recheck(report, edit, restyle, updated);
Console.WriteLine($"Failed before: {report.Count(Outcome.Failed)}, after: {next.Count(Outcome.Failed)}");
Console.WriteLine($"Incremental: {next.Recheck!.Incremental}, rules carried over: {next.Recheck.RulesCarried}, " +
                  $"re-run in part: {next.Recheck.RulesRerunPartly}, in full: {next.Recheck.RulesRerunInFull}");

foreach (EditedRange range in edit.Changes!.Ranges)
{
    string before = Encoding.UTF8.GetString(input, range.OldByteRange.Start, range.OldByteRange.Length);
    Console.WriteLine($"[{before}] -> [{range.NewText}]");
}
File.WriteAllBytes("staff.fixed.html", edit.Document!.ToLosslessBytes());
```

```text
aria-deprecated-role: Use the role list instead of directory.
aria-valid-attr: Remove the aria-describedy attribute.
avoid-inline-spacing: Declare letter-spacing in the style attribute without !important.
listitem: no suggested edit
listitem: no suggested edit
scope-attr-valid: Remove the scope attribute.
scope-attr-valid: Remove the scope attribute.
tabindex: Set tabindex to 0; the focus order does not change.
Applied 6 edits: True
Failed before: 8, after: 0
Incremental: True, rules carried over: 7, re-run in part: 50, in full: 73
[directory] -> [list]
[ scope="column"] -> []
[ scope="column"] -> []
[ !important] -> []
[ aria-describedy="note"] -> []
[3] -> [0]
```

What happened:

- `Profile = ValidationProfile.All` includes best-practice rules such as `scope-attr-valid`. With `Wcag22AA` alone, those wouldn’t run.
- The two `listitem` failures have no suggestion, because the right fix depends on what the author meant. They went away anyway, because replacing the deprecated `role="directory"` with `list` put the items back inside a list.
- `SuggestedEditList()` returns the suggestions as ordinary `Edit` objects without duplicates, so `doc.Apply` runs them with the usual lossless splicing and verification. Six one-range changes, and the rest of the file is byte-identical. To be selective, read `result.SuggestedEdits` per result and apply only the ones you accept.
- `Recheck` gives the same report a full `Check` of the new tree would give, but it re-runs only what the edits reached. `report.Recheck` says how much was carried over.

To review suggestions before applying them, `report.SuggestedEdits()` returns them as one JSON edit envelope you can store, show in a review tool and replay later (see [Save edits as JSON and replay them](https://recursiveai.org/onehtml/cookbook/save-and-replay-edits/)). Each edit’s `meta` carries the rule id, the criteria and `"suggested": true`. The rules and their fixes are documented in [The checker](https://recursiveai.org/onehtml/docs/checker/).


<!-- https://recursiveai.org/onehtml/cookbook/computed-style-csharp/ -->

# Compute CSS styles for an element

Get the computed value of any CSS property for an element, find the rule it came from, and recompute styles for a focused element or a narrow viewport, including stylesheets the page links to.

`DocumentStyles.Create` gathers a page’s style sources and runs the cascade. That includes the HTML user-agent stylesheet, presentational attributes, `<style>`, `style=""` and linked sheets, with layers, `!important`, `var()`, shorthands and `@media`/`@supports`. The library never fetches anything, so a `<link rel=stylesheet>` gets its bytes from a resolver you supply, keyed by absolute URL.

The page in this example links `/css/site.css`:

```css
body { font-family: Georgia, serif; color: #222 }
.card h2 { font-size: 1.5rem }
nav ul { display: flex; gap: 1rem }
@media (max-width: 600px) {
  nav ul { display: block }
}
```

```csharp
using System.Text;
using RecursiveAI.OneHtml;
using RecursiveAI.OneHtml.Css;

Document doc = Document.Parse(File.ReadAllBytes("events.html"));

// The page links /css/site.css. The library never fetches it: you hand it the bytes.
var options = new StyleSourceOptions
{
    BaseUrl = "https://library.example/events/",
    Resolver = url => url == "https://library.example/css/site.css"
        ? new StylesheetResource(File.ReadAllBytes("site.css"))
        : null,
};
DocumentStyles styles = DocumentStyles.Create(doc, StyleContext.Default, options);

Node heading = doc.Root.QuerySelector(".card h2");
ComputedStyle style = styles.GetStyle(heading);
Console.WriteLine($"color: {style.GetPropertyValue("color")}, computed: {style.GetComputedValue("color")}");
Console.WriteLine($"font-size: {style.FontSizePx}px, display: {style.GetPropertyValue("display")}");

// Where a value came from
DeclarationSource? source = style.GetSource("color");
Console.WriteLine($"color set by \"{source?.SelectorText}\" in {source?.SheetUrl ?? "an inline <style>"}");
DeclarationSource? font = style.GetSource("font-family");
Console.WriteLine($"font-family: {style.GetPropertyValue("font-family")} from \"{font?.SelectorText}\" in {font?.SheetUrl}");

// The same element under another context: a focused link, a narrow viewport
Node link = doc.Root.QuerySelector("main a");
DocumentStyles focused = styles.WithContext(StyleContext.Default.WithFocus(link));
Console.WriteLine($"outline normally: {styles.GetStyle(link).GetPropertyValue("outline-style")}, " +
                  $"focused: {focused.GetStyle(link).GetPropertyValue("outline-style")}");

DocumentStyles phone = styles.WithContext(StyleContext.Default.WithMedia(new MediaFeatures { Width = 390, Height = 844 }));
Node nav = doc.Root.QuerySelector("nav ul");
Console.WriteLine($"nav at {MediaFeatures.Default.Width}px: {styles.GetStyle(nav).GetPropertyValue("display")}, " +
                  $"at 390px: {phone.GetStyle(nav).GetPropertyValue("display")}");

foreach (StyleDiagnostic diagnostic in styles.Diagnostics)
{
    Console.WriteLine(diagnostic);
}
```

```text
color: #1a4d7a, computed: rgb(26, 77, 122)
font-size: 24px, display: block
color set by ".card h2" in an inline <style>
font-family: Georgia, serif from "body" in https://library.example/css/site.css
outline normally: none, focused: solid
nav at 1280px: flex, at 390px: block
```

How to read it:

- `GetPropertyValue` returns the value as text. `GetComputedValue` returns the `getComputedStyle` serialization for the typed properties, such as colors as `rgb()`. Typed accessors such as `Color`, `FontSizePx`, `Display`, `Visibility` and `Opacity` give values you can compute with: `1.5rem` became `24px`.
- `GetSource` names the declaration that won: its selector, sheet URL (null for an inline `<style>`), origin, layer and importance. For an inherited property it is the ancestor’s declaration, here `body` in `site.css`.
- `StyleContext` is the environment: the viewport and media features, plus at most one focused, hovered, active or target element. `WithContext` returns a view that recomputes only what the new context can reach. The default viewport is 1280 px wide.
- `Diagnostics` reports what couldn’t be used, such as a linked sheet your resolver returned null for (`MissingStylesheet`), an import cycle or an unsupported rule. This page has none.

There is no layout. Values that depend on layout, like percentages resolved against a containing block or the used width of an element, stay unresolved. [Cascade](https://recursiveai.org/onehtml/docs/cascade/) lists what is implemented and what isn’t, and [CSS values](https://recursiveai.org/onehtml/docs/css-values/) lists the typed properties.


<!-- https://recursiveai.org/onehtml/cookbook/css-selectors/ -->

# Query HTML with CSS selectors

Find elements with QuerySelector, QuerySelectorAll, Matches and Closest using Selectors Level 4, including :has(), :is(), :not() with selector lists, and form-state pseudo-classes.

The query members are on `Node`, so you can query the whole document (`doc.Root`) or any element. They follow the DOM standard: `QuerySelector` returns the first match in document order, and `QuerySelectorAll` returns every match. When nothing matches, `QuerySelector` returns the null node. Check `IsNull` rather than comparing to `null`, because `Node` is a struct.

```csharp
using RecursiveAI.OneHtml;
using RecursiveAI.OneHtml.Selectors;

Document doc = Document.Parse(File.ReadAllBytes("events.html"));
Node root = doc.Root;

// First match, or the null node
Node current = root.QuerySelector("nav a[aria-current=page]");
Console.WriteLine($"Current page: {current.TextContent}");

Node none = root.QuerySelector("aside");
Console.WriteLine($"Has an aside: {!none.IsNull}");

// All matches, in document order; Selectors Level 4 is supported
foreach (Node card in root.QuerySelectorAll("article:has(img:not([alt]))"))
{
    Console.WriteLine($"Card without alt text: {card.GetAttribute("data-event-id")}");
}

foreach (Node link in root.QuerySelectorAll(":is(header, footer) a[href]"))
{
    Console.WriteLine($"{link.LocalName} -> {link.GetAttribute("href")}");
}

// Matches and Closest test an element you already have
Node details = root.QuerySelector("a[href$='/story-time/']");
Console.WriteLine($"Inside a card: {details.Matches(".card a")}, card: {details.Closest(".card").GetAttribute("data-event-id")}");

// Form state pseudo-classes are decided from attributes
Console.WriteLine($"Fields showing a placeholder: {root.QuerySelectorAll("input:placeholder-shown").Count}");

// Compile a selector once when you run it many times
SelectorList external = SelectorList.Parse("a[href^='http']:not([href*='harborstreet'])");
foreach (Node link in root.QuerySelectorAll(external))
{
    Console.WriteLine($"External: {link.GetAttribute("href")}");
}

// A bad selector throws SelectorSyntaxException
try
{
    root.QuerySelector("nav >");
}
catch (SelectorSyntaxException e)
{
    Console.WriteLine($"Rejected: {e.Message}");
}
```

```text
Current page: Events
Has an aside: False
Card without alt text: 114
a -> /
a -> /books/
a -> /events/
a -> /visit/
a -> mailto:hello@example.org
Inside a card: True, card: 114
Fields showing a placeholder: 1
External: https://example.org/repair-cafe
Rejected: Not a valid selector list.
```

What the matcher does, and doesn’t, decide:

- Type selectors and attribute names match HTML elements case-insensitively, and the HTML list of case-insensitive attribute values (`type`, `lang` and others) is honored. Add `i` for anything else, as in `[href^='javascript:' i]`.
- `:checked`, `:disabled`, `:required`, `:placeholder-shown`, `:in-range` and the other form pseudo-classes are decided from attributes. `:valid` and `:invalid` are decided where that is possible without script: `required`, `email`, `url`, `pattern`, `min`, `max` and `step`.
- No script runs, so `:defined` matches every element that isn’t a custom element. `:visited`, `:autofill`, `:popover-open` and `:modal` never match.
- `:hover`, `:focus`, `:focus-visible`, `:active` and `:target` match only when you give an interaction state in `SelectorMatchOptions`. Otherwise they match nothing. The cascade takes the same state through `StyleContext` (see [Compute CSS styles](https://recursiveai.org/onehtml/cookbook/computed-style-csharp/)).
- Pseudo-elements parse but never match an element.
- An unclosed `[` or `(` at the end of the input is closed for you, as CSS Syntax says, so `a[href` is valid. A selector that is really invalid throws `SelectorSyntaxException`.

`SelectorList.Parse` compiles a selector once. Matching against a compiled list allocates nothing, and `QuerySelectorAll` allocates only the result list.

There is no XPath API. The full rules, limits and the web-platform-tests results are in [Selectors](https://recursiveai.org/onehtml/docs/selectors/).

Sixteen selectors measured against AngleSharp, Fizzler and Chrome: [CSS selectors in C#](https://recursiveai.org/onehtml/articles/css-selectors-csharp/).


<!-- https://recursiveai.org/onehtml/cookbook/detect-encoding/ -->

# Detect the encoding of an HTML page

Decode HTML bytes the way a browser does, using the byte order mark, the HTTP Content-Type header, the meta charset prescan and the windows-1252 fallback, and override the fallback when you know better.

`Document.Parse(bytes)` implements the WHATWG Encoding Standard and the HTML encoding-sniffing algorithm. The input here is a French menu saved as windows-1252, which declares itself with `<meta charset="windows-1252">`:

```html
<!DOCTYPE html>
<html lang="fr">
<head>
<meta charset="windows-1252">
<title>Menu</title>
</head>
<body>
<h1>Café crème – 3,50 €</h1>
</body>
</html>
```

```csharp
using System.Text;
using RecursiveAI.OneHtml;
using RecursiveAI.OneHtml.Encodings;

// A windows-1252 page that declares its charset in a <meta>
byte[] declared = File.ReadAllBytes("menu-1252.html");
Document doc = Document.Parse(declared);
Console.WriteLine($"{doc.Source.Encoding.Name} ({doc.Source.Confidence}): {doc.Root.QuerySelector("h1").TextContent}");

// Sniff without parsing: BOM, then transport Content-Type, then the <meta> prescan
EncodingSniffResult sniffed = EncodingSniffer.Sniff(declared);
Console.WriteLine($"Sniffed: {sniffed.Encoding.Name}, {sniffed.Confidence}");

// The HTTP header wins over the <meta> when you pass it
Document fromHeader = Document.Parse(declared, new ParseOptions { ContentType = "text/html; charset=utf-8" });
Console.WriteLine($"With a UTF-8 header: {fromHeader.Source.Encoding.Name}, {fromHeader.Source.DecodeErrorCount} decode errors");

// A byte order mark beats everything
byte[] bom = [0xEF, 0xBB, 0xBF, .. Encoding.UTF8.GetBytes("<meta charset=windows-1252><p>café")];
Console.WriteLine($"With a BOM: {Document.Parse(bom).Source.Encoding.Name}");

// No BOM, no header, no <meta>: the last-resort default is windows-1252
byte[] bare = Encoding.UTF8.GetBytes("<p>café");
Document guessed = Document.Parse(bare);
Console.WriteLine($"Undeclared: {guessed.Source.Encoding.Name} ({guessed.Source.Confidence}): {guessed.Root.QuerySelector("p").TextContent}");

// Choose the fallback yourself when you know your sources
Document utf8 = Document.Parse(bare, new ParseOptions { DefaultEncoding = WhatwgEncoding.Utf8 });
Console.WriteLine($"Default set to UTF-8: {utf8.Root.QuerySelector("p").TextContent}");

// Labels resolve the way browsers resolve them
Console.WriteLine($"latin1 -> {WhatwgEncoding.ForLabel("latin1")}, gb2312 -> {WhatwgEncoding.ForLabel("gb2312")}");
```

```text
windows-1252 (Certain): Café crème – 3,50 €
Sniffed: windows-1252, Tentative
With a UTF-8 header: UTF-8, 4 decode errors
With a BOM: UTF-8
Undeclared: windows-1252 (Tentative): café
Default set to UTF-8: café
latin1 -> windows-1252, gb2312 -> GBK
```

The order of precedence:

1. **A byte order mark** (UTF-8, UTF-16LE, UTF-16BE) decides, whatever the page declares.
2. **The transport `Content-Type`**, which you pass as `ParseOptions.ContentType` because the library doesn’t make HTTP requests. Pass the header your HTTP client received. Here a wrong UTF-8 header produced 4 decode errors on the windows-1252 bytes, as it would in a browser.
3. **The prescan** of the first 1,024 bytes for a `<meta charset>`, a `<meta http-equiv="Content-Type">`, or an XML declaration. Change the length with `ParseOptions.PrescanLimit`.
4. **The fallback**, `ParseOptions.DefaultEncoding`, which is windows-1252 unless you set it. The HTML standard recommends windows-1252 for most locales. That is why undeclared UTF-8 bytes show up as `café`. If you know your sources are UTF-8, set `DefaultEncoding = WhatwgEncoding.Utf8`.

`ParseOptions.OverrideEncoding` forces an encoding, though a byte order mark still wins. `doc.Source` tells you what was used: `Encoding`, `Confidence` (`Tentative` for a guess or a prescan result, `Certain` once confirmed), `BomLength` and `DecodeErrorCount`. `EncodingSniffer.Sniff` runs the same steps without parsing.

Labels follow the Encoding Standard’s table, so `latin1` and `iso-8859-1` mean windows-1252, and `gb2312` means GBK. When you edit a page, the output is written back in the encoding it was decoded with (see [Edit HTML without reformatting it](https://recursiveai.org/onehtml/cookbook/edit-html-csharp-lossless/)).

More on loading real pages: [Parse HTML in C#](https://recursiveai.org/onehtml/articles/parse-html-csharp/).

Encoding in a full scraper: [Web scraping in C#](https://recursiveai.org/onehtml/articles/web-scraping-csharp/).


<!-- https://recursiveai.org/onehtml/cookbook/edit-html-csharp-lossless/ -->

# Edit HTML without reformatting it

Change attributes, text and inline styles in an HTML file so that only the edited bytes change: quoting, character references, comments, whitespace and the rest of the file stay exactly as they were.

Most HTML libraries edit a tree and then serialize the whole tree again, which rewrites quoting, entities and whitespace across the file. onehtml splices the original bytes instead. Each edit marks the smallest region it touches, such as one attribute value or one text node, and everything outside those regions is copied unchanged. The result is then re-parsed and compared with the expected tree before it’s returned, so an edit can’t silently change how the rest of the page parses.

```csharp
using System.Text;
using RecursiveAI.OneHtml;
using RecursiveAI.OneHtml.Editing;

byte[] input = File.ReadAllBytes("events.html");
Document doc = Document.Parse(input);

// With no edits, the output is the input, byte for byte
Console.WriteLine($"Round trip identical: {doc.ToLosslessBytes().AsSpan().SequenceEqual(input)}");

Node partner = doc.Root.QuerySelector("a[target=_blank]");
Node visit = doc.Root.QuerySelector("a[href='/visit/']");
Node heading = doc.Root.QuerySelector("[data-event-id='115'] h2");
Node signup = doc.Root.QuerySelector("form.signup");

EditResult result = doc.Apply(new[]
{
    Edit.SetAttribute(partner, "rel", "noopener"),
    Edit.SetAttribute(visit, "href", "/visit/hours/"),
    Edit.ReplaceText(heading, "Repair café & swap"),
    Edit.SetStyle(signup, "margin-top", "2rem"),
});

if (!result.Succeeded)
{
    foreach (EditOutcome outcome in result.Outcomes.Where(o => o.Status != EditStatus.Applied))
    {
        Console.WriteLine($"{outcome.Edit}: {outcome.Status} {outcome.Reason}");
    }
    return;
}

byte[] output = result.Document!.ToLosslessBytes();
foreach (EditedRange range in result.Changes!.Ranges)
{
    string before = Encoding.UTF8.GetString(input, range.OldByteRange.Start, range.OldByteRange.Length);
    Console.WriteLine($"[{before}] -> [{range.NewText}]");
}

// Rebuild the output from the input and the edited ranges alone
var rebuilt = new List<byte>();
int position = 0;
foreach (EditedRange range in result.Changes.Ranges.OrderBy(r => r.OldByteRange.Start))
{
    rebuilt.AddRange(input[position..range.OldByteRange.Start]);
    rebuilt.AddRange(range.NewBytes.ToArray());
    position = range.OldByteRange.End;
}
rebuilt.AddRange(input[position..]);
Console.WriteLine($"Everything outside the ranges is unchanged: {rebuilt.SequenceEqual(output)}");

// The old snapshot is untouched and its handles still work
Console.WriteLine($"Old heading: {heading.TextContent}");
Console.WriteLine($"New heading: {result.Changes.MapToNew(heading).TextContent}");

File.WriteAllBytes("events.edited.html", output);
```

```text
Round trip identical: True
[/visit/] -> [/visit/hours/]
[Repair caf&eacute;] -> [Repair café &amp; swap]
[] -> [ rel="noopener"]
[] -> [ style="margin-top: 2rem;"]
Everything outside the ranges is unchanged: True
Old heading: Repair café
New heading: Repair café & swap
```

The `diff` of the two files:

```text
21c21
<         <li><a href='/visit/'>Visit</a></li>
---
>         <li><a href='/visit/hours/'>Visit</a></li>
37c37
<       <h2>Repair caf&eacute;</h2>
---
>       <h2>Repair café &amp; swap</h2>
39c39
<          <a href="https://example.org/repair-cafe" target="_blank">Partner site</a></p>
---
>          <a href="https://example.org/repair-cafe" target="_blank" rel="noopener">Partner site</a></p>
43c43
<     <form action="/newsletter" method="post" class="signup">
---
>     <form action="/newsletter" method="post" class="signup" style="margin-top: 2rem;">
```

What to expect:

- **Only the edited range changes.** The single-quoted `href='/visit/'` stays single-quoted, because only its value was replaced. The `&ndash;` and `&rsquo;` references elsewhere are untouched. Text you write is escaped for its context, which is why `&` became `&amp;`. The replaced text’s own `&eacute;` is written as `é`, because the whole text node was replaced.
- **New markup follows the file’s style.** Inserted attributes and elements copy the quote character, tag and attribute case, void-element form, newline sequence and indentation the file already uses.
- **The encoding is kept.** Output is written in the document’s encoding. A character it can’t represent becomes a character reference in text and attribute values.
- **All or nothing.** If any edit can’t be applied, nothing is, and `Outcomes` says why for each edit: `Invalid`, `Failed` or `NotAttempted`.
- **Snapshots are immutable.** `doc` and every handle into it still describe the old page. `Changes.MapToNew` finds a node’s counterpart in the new snapshot, and `Changes.Added`, `Removed` and `Changed` list what moved.

When a splice can’t express the edit, for example an edit that would change how the surrounding markup parses, the engine widens the region to the nearest enclosing element and rewrites just that element. Such ranges are marked `IsFallback`. [Editing](https://recursiveai.org/onehtml/docs/editing/) has the full rules.

For several edits built up over time, `new DocumentEditor(doc)` collects them and `Apply()` runs them as one transaction. To store edits and apply them to another copy of the page later, see [Save edits as JSON and replay them](https://recursiveai.org/onehtml/cookbook/save-and-replay-edits/). Stylesheets are edited the same way: [Parse and edit CSS](https://recursiveai.org/onehtml/cookbook/parse-and-edit-css/).


<!-- https://recursiveai.org/onehtml/cookbook/extract-links-and-images/ -->

# Extract all links and images from a page

List every link and image on a page with its resolved URL, its attributes in source order, and the accessible name a screen reader announces for it.

```csharp
using RecursiveAI.OneHtml;
using RecursiveAI.OneHtml.Css;
using RecursiveAI.OneHtml.Accessibility;

Document doc = Document.Parse(File.ReadAllBytes("events.html"));
var pageUrl = new Uri("https://library.example/events/");

// Links: resolve each href against the page address with System.Uri
foreach (Node a in doc.Root.QuerySelectorAll("a[href], area[href]"))
{
    var url = new Uri(pageUrl, a.GetAttribute("href")!);
    Console.WriteLine($"{url,-45} {a.TextContent!.Trim()}");
}

// Images: GetAttribute returns null when the attribute is absent, "" when it is empty
foreach (Node img in doc.Root.QuerySelectorAll("img[src]"))
{
    string? alt = img.GetAttribute("alt");
    Console.WriteLine($"{img.GetAttribute("src"),-22} alt: {(alt is null ? "(missing)" : $"\"{alt}\"")}");
}

// Every attribute of one element, in source order
Node first = doc.Root.QuerySelector("main img");
foreach (Attr attr in first.Attributes)
{
    Console.WriteLine($"{attr.QualifiedName} = {attr.Value}");
}

// Links as a screen reader lists them: the accessible name, not just the text
var tree = AccessibilityTree.Build(doc, DocumentStyles.Create(doc));
foreach (LinkEntry link in tree.CreateNavigationLists().Links)
{
    Console.WriteLine($"\"{link.Name}\" -> {link.Target}");
}
```

```text
https://library.example/                      
https://library.example/books/                Books
https://library.example/events/               Events
https://library.example/visit/                Visit
https://library.example/events/story-time/    Details
https://example.org/repair-cafe               Partner site
mailto:hello@example.org                      hello@example.org
/img/logo.svg          alt: "Harbor Street Library"
/img/story-time.jpg    alt: (missing)
/img/repair.jpg        alt: "Volunteers at a workbench fixing a lamp"
src = /img/story-time.jpg
width = 640
height = 360
"Harbor Street Library" -> /
"Books" -> /books/
"Events" -> /events/
"Visit" -> /visit/
"Details" -> /events/story-time/
"Partner site" -> https://example.org/repair-cafe
"hello@example.org" -> mailto:hello@example.org
```

Notes:

- The library doesn’t resolve URLs for you here. `System.Uri` does it from the page address. If the page has a `<base href>`, read it first (`doc.Root.QuerySelector("base[href]")`) and resolve against that.
- `a[href], area[href]` matches the elements a browser treats as links. An `a` without `href` is not a link.
- `GetAttribute` returns the value with character references decoded. `Attributes` gives every attribute in source order, with `QualifiedName`, `LocalName`, `Namespace` and the source ranges of the name and value.
- The first link has no text, so `TextContent` is empty. Its accessible name, from the navigation lists, is “Harbor Street Library”, taken from the image inside it. To know what a person hears for a link, use the accessible name.
- For `srcset`, `<picture>` and `<source>`, query them the same way (`img[srcset]`, `picture source[srcset]`) and split the attribute yourself. The library doesn’t parse `srcset`.

More about the tree and the navigation lists: [The accessibility tree of a page](https://recursiveai.org/onehtml/cookbook/accessibility-tree/).

Following links across pages: [Web scraping in C#](https://recursiveai.org/onehtml/articles/web-scraping-csharp/).


<!-- https://recursiveai.org/onehtml/cookbook/extract-visible-text/ -->

# Extract visible text from HTML

Get the readable text of a page without its script and style contents, either with a short walk over the text nodes or with the cascade-aware reading view, which also drops content hidden by CSS, the hidden attribute or aria-hidden.

`TextContent` follows the DOM standard, which includes the text of `script` and `style` elements. That is correct, but it is rarely what you want for search indexing, previews or diffs. There are two ways to get the readable text.

```csharp
using System.Text;
using RecursiveAI.OneHtml;
using RecursiveAI.OneHtml.Css;
using RecursiveAI.OneHtml.Accessibility;

Document doc = Document.Parse(File.ReadAllBytes("events.html"));
Node body = doc.Root.QuerySelector("body");

// TextContent follows the DOM standard: script and style text is included
Console.WriteLine($"TextContent has the script: {body.TextContent!.Contains("addEventListener")}");

// Walk the text nodes yourself and skip the elements that never render text
var text = new StringBuilder();
foreach (Node node in body.Descendants)
{
    if (node.Kind == NodeKind.Text && node.ParentElement.Closest("script, style, template, noscript").IsNull)
    {
        text.Append(node.Data);
    }
}
string plain = string.Join(' ', text.ToString().Split((char[]?)null, StringSplitOptions.RemoveEmptyEntries));
Console.WriteLine(plain);

// Or let the cascade decide: the reading view drops display:none, hidden and aria-hidden content
Document page = Document.Parse("""
    <style>.promo { display: none }</style>
    <h1>Opening hours</h1>
    <p class="promo">Members save 10%</p>
    <p hidden>Draft: holiday hours</p>
    <p>Monday to Friday, 9 to 6. <span aria-hidden="true">★</span></p>
    <script>console.log("not text")</script>
    """);
var tree = AccessibilityTree.Build(page, DocumentStyles.Create(page));
Console.WriteLine(tree.CreateReadingView().ToText());
```

```text
TextContent has the script: True
Books Events Visit Upcoming events Story time for ages 3–5 Saturdays at 10:30 in the children’s room. Details Repair café Bring a lamp, a toaster or a torn jacket. Volunteers fix what they can. Partner site © 2026 Harbor Street Library · hello@example.org Back to top
heading level 1: Opening hours
Monday to Friday, 9 to 6.
```

**The text-node walk** is fast and needs only the parser. It skips `script`, `style`, `template` and `noscript`, so the inline script at the end of the events page is gone. It knows nothing about CSS: text inside `display: none` or `hidden` would still be there. Use `node.ParentElement.Closest(...)`, because `Closest` starts from an element and a text node isn’t one.

**The reading view** reads the page from its accessibility tree, which is built with the cascade. It leaves out text hidden by `display: none`, `visibility: hidden`, `content-visibility: hidden`, the `hidden` attribute, a closed `details`, `inert` and `aria-hidden`, and it doesn’t read script. Each line is a step: text runs, plus announced elements such as `heading level 1: Opening hours`. Headings and other announced elements come through as element items rather than `ReadingItemKind.Text` items, so keep their text too if you want every visible word; [Extract visible text from HTML in C#](https://recursiveai.org/onehtml/articles/extract-visible-text-from-html-csharp/) shows a complete version and compares HtmlAgilityPack and AngleSharp.

Limits of the reading view:

- It decides from markup and CSS alone. Hiding that depends on layout, such as zero size, clipping or off-screen positioning, isn’t known, so that text is still read. Chrome doesn’t hide such content from its accessibility tree either.
- The wording is generic English. It is an approximation, not what any particular screen reader says. [Reading view](https://recursiveai.org/onehtml/docs/reading-view/) has the rules.
- Script doesn’t run. For a page built by script, parse the browser’s serialized DOM instead of the HTML the server sent.


<!-- https://recursiveai.org/onehtml/cookbook/html-fragments/ -->

# Parse HTML fragments

Parse a snippet of HTML, such as table rows or list items, in the context of the element it belongs in, so you get the elements a browser would create and not a whole html and body document.

The HTML parser builds different trees for the same markup depending on where it sits. `<tr><td>` inside a `tbody` makes rows, while the same markup inside a `div` loses its table tags. `Document.ParseFragment` runs the fragment-parsing algorithm (the one behind `innerHTML`) with a context element you name.

```csharp
using RecursiveAI.OneHtml;
using RecursiveAI.OneHtml.Editing;

// A fragment is parsed as if it were the inner HTML of a context element
var tbody = new FragmentContext(ElementNamespace.Html, "tbody");
Document rows = Document.ParseFragment("<tr><td>Story time<td>Sat 10:30<tr><td>Repair café<td>Sun 14:00", tbody);
Console.WriteLine($"Fragment: {rows.IsFragment}, rows: {rows.Root.QuerySelectorAll("tr").Count}");
Console.WriteLine(rows.SerializeChildren(rows.Root));

// The same markup in a <div> context: table parts without a table are dropped
Document loose = Document.ParseFragment("<tr><td>Story time<td>Sat 10:30", new FragmentContext(ElementNamespace.Html, "div"));
Console.WriteLine(loose.SerializeChildren(loose.Root));

// Take the context from an element of a real page
Document page = Document.Parse(File.ReadAllBytes("events.html"));
Node list = page.Root.QuerySelector("nav ul");
Document items = Document.ParseFragment("<li><a href=/kids/>Kids</a>", FragmentContext.FromElement(list));
Console.WriteLine(items.Root.QuerySelector("a").GetAttribute("href"));

// Inserting markup into a page parses it in the target's context for you
EditResult result = page.Apply(new[] { Edit.Append(list, "<li><a href=\"/kids/\">Kids</a></li>") });
Node newList = result.Document!.Root.QuerySelector("nav ul");
string written = result.Document.Source.Text[newList.Source.Range.Start..newList.Source.EndTag.End];
Console.WriteLine(written);
```

```text
Fragment: True, rows: 2
<tr><td>Story time</td><td>Sat 10:30</td></tr><tr><td>Repair café</td><td>Sun 14:00</td></tr>
Story timeSat 10:30
/kids/
<ul>
        <li><a href="/books/">Books</a></li>
        <li><a href="/events/" aria-current="page">Events</a></li>
        <li><a href='/visit/'>Visit</a></li>
        <li><a href="/kids/">Kids</a></li>
      </ul>
```

Notes:

- `new FragmentContext(ElementNamespace.Html, "tbody")` names the context directly. `FragmentContext.FromElement(node)` takes it from an element of a parsed page, including whether it sits inside a `form` and the page’s quirks mode.
- The result is a `Document` with `IsFragment` set. Its `Root` holds the parsed nodes, so you can query them as usual. `SerializeChildren(Root)` writes them back out as HTML.
- You rarely need `ParseFragment` to insert markup. `Edit.Append`, `Prepend`, `InsertBefore`, `InsertAfter`, `Replace` and `Wrap` already parse the markup you pass in the target’s context. They also write it in the file’s own style: here the new `<li>` was put on its own line with the list’s indentation, and the single-quoted `href='/visit/'` next to it is unchanged.
- An element’s `<template>` content is a separate fragment, reached through `node.TemplateContent`.

More on how inserted markup is placed and written: [Editing](https://recursiveai.org/onehtml/docs/editing/).


<!-- https://recursiveai.org/onehtml/cookbook/migrate-from-anglesharp/ -->

# Coming from AngleSharp: where the trees differ

If you are moving HTML parsing from AngleSharp to onehtml, this is what changes in the trees you get. On a corpus of real pages the two agree exactly on about nine in ten pages, and every difference in the rest comes from one of a short list of documented causes.

onehtml’s query members follow the DOM standard: `QuerySelector`, `QuerySelectorAll`, `Matches`, `Closest`, `GetAttribute`, `TextContent`, and `Children` for element children. Code written against those DOM names maps directly. The onehtml repository compares the two parsers on 13,857 crawled pages. 12,469 (89.98%) give identical trees, and every difference in the rest is traced to the HTML, Encoding or DOM standard in [AngleSharp differential](https://recursiveai.org/onehtml/docs/anglesharp-differential/).

This program runs the documented inputs through onehtml:

```csharp
using System.Text;
using RecursiveAI.OneHtml;

void Show(string label, string html, string selector)
{
    Document doc = Document.Parse(html);
    Node node = doc.Root.QuerySelector(selector);
    Console.WriteLine($"{label,-26} {doc.SerializeNode(node)}");
}

// SVG keeps the xlink prefix on adjusted foreign attributes
Document svg = Document.Parse("<svg><use xlink:href=\"#icon\"></use></svg>");
foreach (Attr attr in svg.Root.QuerySelector("use").Attributes)
{
    Console.WriteLine($"{"xlink attribute",-26} qualified {attr.QualifiedName}, local {attr.LocalName}, namespace {attr.Namespace}");
}

// A bare & before ; is text, and the ; stays
Show("bare ampersand", "<p>a&;b</p>", "p");

// select content is parsed as in body: other elements stay inside the select
Show("select content", "<select><option>One<b>!</b></option></select>", "select");

// A parsed document keeps declarative shadow root templates as template elements
Show("shadowrootmode", "<div><template shadowrootmode=open><b>x</b></template></div>", "div");

// search closes an open p and its end tag pops to it
Show("search element", "<div><search><div></search>x</div>", "body");

// </td> does not close a th
Show("cell end tag", "<table><tr><th></td>x</table>", "tr");

// Encodings: gb2312 is GBK, and undeclared pages fall back to windows-1252
Console.WriteLine($"{"gb2312 label",-26} {Document.Parse(Encoding.ASCII.GetBytes("<meta charset=gb2312><p>x")).Source.Encoding.Name}");
Console.WriteLine($"{"no declaration",-26} {Document.Parse(Encoding.ASCII.GetBytes("<p>x")).Source.Encoding.Name}");
```

```text
xlink attribute            qualified xlink:href, local href, namespace XLink
bare ampersand             <p>a&amp;;b</p>
select content             <select><option>One<b>!</b></option></select>
shadowrootmode             <div><template shadowrootmode="open"><b>x</b></template></div>
search element             <body><div><search><div></div></search>x</div></body>
cell end tag               <tr><th>x</th></tr>
gb2312 label               GBK
no declaration             windows-1252
```

The same inputs in AngleSharp, as that document records them:

| Input | onehtml | AngleSharp |
|---|---|---|
| `<use xlink:href>` in SVG | prefix `xlink`, local name `href` in the XLink namespace | plain `href` (namespace kept, prefix dropped). With both `href` and `xlink:href`, keeps one |
| `a&;b` | text `a&;b` | drops the `;` |
| elements inside `<select>` | kept, as the current standard parses `select` content as in body | dropped or moved (the older “in select” mode) |
| `<template shadowrootmode>` in a parsed document | stays a `template` element with its content | attaches a shadow root, so the host has no child |
| `<search>` | closes an open `p` and its end tag pops to it | unknown element, so `</search>` is ignored |
| `</td>` while a `th` is open | ignored | closes the cell |
| `gb2312` / `gbk` labels | GBK | gb18030 (the decoded text is the same) |
| no BOM, header, `<meta>` or XML declaration | windows-1252, the standard’s recommended default | UTF-8 |
| `<?xml … encoding="Shift_JIS"?>` with no other declaration | Shift_JIS | UTF-8 |
| uppercase `</C` at the end of a `<style>` | text `</C` | text `</c` |
| thousands of unclosed elements | nests up to 4,096, then throws `HtmlLimitExceededException` | stops nesting at 512 and appends siblings |

Other differences to plan for:

- **Undeclared pages decode differently.** This is the change most likely to show up in your output. Where AngleSharp assumed UTF-8, onehtml uses windows-1252. If your sources are UTF-8 without a declaration, set `ParseOptions.DefaultEncoding = WhatwgEncoding.Utf8` (see [Detect the encoding](https://recursiveai.org/onehtml/cookbook/detect-encoding/)).
- **Nothing is fetched and no script runs.** onehtml never opens a URL or a file. Fetch the bytes yourself, pass the `Content-Type` header as `ParseOptions.ContentType`, and supply linked stylesheets through a resolver (see [Compute CSS styles](https://recursiveai.org/onehtml/cookbook/computed-style-csharp/)).
- **Documents are immutable.** You don’t change a node in place. You build edits and `Apply` them, which returns a new snapshot and leaves every untouched byte of the original as it was (see [Edit HTML without reformatting it](https://recursiveai.org/onehtml/cookbook/edit-html-csharp-lossless/)).
- **`Node` is a struct.** A missing result is the null node (`IsNull`), not `null`.
- **The target framework is `net10.0` only.**

For a measured comparison of the trees each parser builds: [HtmlAgilityPack vs AngleSharp](https://recursiveai.org/onehtml/articles/htmlagilitypack-vs-anglesharp/). Coming from HtmlAgilityPack instead: [Migrate from HtmlAgilityPack](https://recursiveai.org/onehtml/articles/migrate-from-htmlagilitypack/).


<!-- https://recursiveai.org/onehtml/cookbook/parse-and-edit-css/ -->

# Parse and edit CSS

Parse a stylesheet into rules and declarations with source ranges, walk nested @media rules, and change a declaration or add a rule without reformatting the rest of the file.

`Stylesheet.Parse` implements CSS Syntax Level 3. Malformed CSS never throws: invalid parts become `Invalid` nodes. Only the hostile-input size limits throw (`CssLimitExceededException`). Every node keeps its source range, so you can read the original text (`PreludeText`, `ValueText`, `Raw`) as well as the parsed component values. This example uses the same `site.css` as [Compute CSS styles](https://recursiveai.org/onehtml/cookbook/computed-style-csharp/):

```css
body { font-family: Georgia, serif; color: #222 }
.card h2 { font-size: 1.5rem }
nav ul { display: flex; gap: 1rem }
@media (max-width: 600px) {
  nav ul { display: block }
}
```

```csharp
using RecursiveAI.OneHtml.Css;
using RecursiveAI.OneHtml.Editing;

string css = File.ReadAllText("site.css");
Stylesheet sheet = Stylesheet.Parse(css, "https://library.example/css/site.css");

void Print(CssNode rule, string indent)
{
    if (rule.Kind == CssNodeKind.AtRule)
    {
        Console.WriteLine($"{indent}@{rule.Name} {rule.PreludeText.ToString().Trim()}");
        foreach (CssNode child in rule.Rules)
        {
            Print(child, indent + "  ");
        }
        return;
    }
    Console.WriteLine($"{indent}{rule.PreludeText.ToString().Trim()}");
    foreach (CssNode declaration in rule.Declarations)
    {
        Console.WriteLine($"{indent}  {declaration.Name}: {declaration.ValueText.ToString().Trim()}{(declaration.IsImportant ? " !important" : "")}");
    }
}

foreach (CssNode rule in sheet.Rules)
{
    Print(rule, "");
}

// Edit the stylesheet the same lossless way as HTML: only the touched declaration changes
CssNode cardHeading = sheet.Rules.First(r => r.PreludeText.ToString().Trim() == ".card h2");
BatchResult result = StylesheetEditing.Apply(sheet, new[]
{
    SheetEdit.SetDeclaration(sheet, cardHeading, "font-size", "1.75rem"),
    SheetEdit.AppendRule(sheet, ".card h2 a { text-decoration: none }"),
});
Console.WriteLine($"Succeeded: {result.Succeeded}");
Console.Write(result.Sheets.Single().NewSheet.ToSourceText());
```

```text
body
  font-family: Georgia, serif
  color: #222
.card h2
  font-size: 1.5rem
nav ul
  display: flex
  gap: 1rem
@media (max-width: 600px)
  nav ul
    display: block
Succeeded: True
body { font-family: Georgia, serif; color: #222 }
.card h2 { font-size: 1.75rem }
nav ul { display: flex; gap: 1rem }
@media (max-width: 600px) {
  nav ul { display: block }
}
.card h2 a { text-decoration: none }
```

Notes:

- `sheet.Rules` lists the top-level rules. A rule’s `Kind` is `QualifiedRule` (a style rule) or `AtRule`. For at-rules, `Name` is the at-keyword and `AtRuleKind` says which one (`Media`, `Supports`, `Layer`, `Import` and others). `Rules` and `Declarations` give the children.
- `ToSourceText()` returns the sheet’s text with its original formatting. `Serialize()` writes the CSSOM serialization instead.
- `StylesheetEditing.Apply` edits the way HTML edits do. It splices only the touched declaration or rule, copies the file’s spacing and indentation for new rules, and parses the result again to verify it. The other operations are `RemoveDeclaration`, `InsertRuleBefore`, `InsertRuleAfter`, `ReplaceRule` and `RemoveRule`.
- To edit a `<style>` element or a linked sheet together with the page, `InlineStylesheets.Of(doc)` returns the page’s `<style>` sheets, `LinkedStylesheet.Create(url, bytes)` wraps a linked one, and `new EditBatch(doc, edits, sheetEdits, linkedSheets).Apply()` runs HTML and CSS edits as one transaction.
- Inline `style=""` attributes are edited with `Edit.SetStyle` and `Edit.RemoveStyle` on the element (see [Edit HTML without reformatting it](https://recursiveai.org/onehtml/cookbook/edit-html-csharp-lossless/)).

Parsing details are in [CSS syntax](https://recursiveai.org/onehtml/docs/css-syntax/), and how stylesheet edits are written and verified is at the end of [Editing](https://recursiveai.org/onehtml/docs/editing/).


<!-- https://recursiveai.org/onehtml/cookbook/parse-html/ -->

# Parse HTML from a string, file or stream

Load HTML into a document from a string, a file or a stream, let the parser pick the encoding from the bytes, and see the tokenizer’s parse errors when you need them.

`Document.Parse` has three overloads: bytes (`ReadOnlyMemory<byte>`), a `string`, and an already decoded `SourceText`. There is no `Stream` or file-path overload, because the library never reads files or the network. You read the input and pass the bytes.

Prefer bytes whenever you have them. With bytes, the parser applies the WHATWG encoding rules: byte order mark, then the transport `Content-Type` (`ParseOptions.ContentType`), then the `<meta>` prescan. A string is used as it is.

```csharp
using System.Text;
using RecursiveAI.OneHtml;

// From a string
Document fromString = Document.Parse("<p class=lead>Hello, <b>world</b>");
Console.WriteLine(fromString.Root.QuerySelector("p.lead").TextContent);
Console.WriteLine(fromString.SerializeNode(fromString.DocumentElement));

// From a file: read the bytes and let the parser sniff the encoding
Document fromFile = Document.Parse(File.ReadAllBytes("events.html"));
Console.WriteLine($"{fromFile.Source.Encoding.Name}: {fromFile.Root.QuerySelector("h1").TextContent}");

// From a stream: copy it into memory first; Parse takes bytes, not a Stream
using Stream stream = File.OpenRead("events.html");
using var buffer = new MemoryStream();
await stream.CopyToAsync(buffer);
Document fromStream = Document.Parse(buffer.GetBuffer().AsMemory(0, (int)buffer.Length));
Console.WriteLine($"{fromStream.NodeCount} nodes");

// Tokenizer errors are recorded only when asked for
var options = new ParseOptions { RecordErrors = true };
Document broken = Document.Parse("<p title=\"a\"b>Fish &chips</p>", options);
foreach (var error in broken.ParseErrors)
{
    Console.WriteLine($"{error.Error} at offset {error.Offset}");
}
Console.WriteLine(broken.SerializeNode(broken.Root.QuerySelector("p")));
```

```text
Hello, world
<html><head></head><body><p class="lead">Hello, <b>world</b></p></body></html>
UTF-8: Upcoming events
101 nodes
MissingWhitespaceBetweenAttributes at offset 12
<p title="a" b="">Fish &amp;chips</p>
```

Some things to know:

- A string input still gets the full document: `<html>`, `<head>` and `<body>` are created as a browser would create them. To parse a snippet without them, see [HTML fragments](https://recursiveai.org/onehtml/cookbook/html-fragments/).
- `buffer.GetBuffer().AsMemory(0, (int)buffer.Length)` hands over the stream’s bytes without a second copy. `buffer.ToArray()` works too.
- Parse errors never throw. They are recorded only when `ParseOptions.RecordErrors` is set, and only the tokenizer’s errors are recorded (not tree construction errors). Without it, `ParseErrors` is empty.
- Hostile-input limits (input size, nesting depth, attribute count) are checked before the work they guard. Going past one throws `HtmlLimitExceededException`. Set your own with `ParseOptions.Limits`.
- `SerializeNode` and `SerializeChildren` write the HTML serialization of the tree. To write the page back with its original bytes, use `ToLosslessBytes()` (see [Edit HTML without reformatting it](https://recursiveai.org/onehtml/cookbook/edit-html-csharp-lossless/)).

Encoding detection in detail: [Detect the encoding of an HTML page](https://recursiveai.org/onehtml/cookbook/detect-encoding/).

A longer guide with encoding detection and broken markup: [Parse HTML in C#](https://recursiveai.org/onehtml/articles/parse-html-csharp/).

Fetching, encodings, robots.txt and JavaScript-built pages: [Web scraping in C#](https://recursiveai.org/onehtml/articles/web-scraping-csharp/).


<!-- https://recursiveai.org/onehtml/cookbook/remove-scripts/ -->

# Remove scripts and event handlers

Strip script elements, inline event-handler attributes and javascript: links from a page with lossless edits, and know where this stops: onehtml has no HTML sanitizer.

```csharp
using System.Text;
using RecursiveAI.OneHtml;
using RecursiveAI.OneHtml.Editing;

byte[] input = File.ReadAllBytes("events.html");
Document doc = Document.Parse(input);

var edits = new List<Edit>();
foreach (Node script in doc.Root.QuerySelectorAll("script"))
{
    edits.Add(Edit.Remove(script));
}
foreach (Node element in doc.Root.DescendantElements)
{
    foreach (Attr attr in element.Attributes)
    {
        if (attr.LocalName.StartsWith("on", StringComparison.OrdinalIgnoreCase))
        {
            edits.Add(Edit.RemoveAttribute(element, attr.QualifiedName));
        }
    }
}
foreach (Node link in doc.Root.QuerySelectorAll("a[href^='javascript:' i]"))
{
    edits.Add(Edit.RemoveAttribute(link, "href"));
}

EditResult result = doc.Apply(edits);
Console.WriteLine($"{edits.Count} edits, succeeded: {result.Succeeded}");
foreach (EditedRange range in result.Changes!.Ranges)
{
    string removed = Encoding.UTF8.GetString(input, range.OldByteRange.Start, range.OldByteRange.Length);
    Console.WriteLine($"- {removed.Trim()}");
}
File.WriteAllBytes("events.noscript.html", result.Document!.ToLosslessBytes());
```

```text
3 edits, succeeded: True
- <script src="/js/analytics.js"></script>
- <script>
    document.querySelectorAll('.card').forEach(c => c.addEventListener('click', track));
  </script>
- onclick="window.scrollTo(0, 0)"
```

The edits run as one transaction. Each is aimed at a node of the same snapshot, and either all apply or none do. Everything else in the file keeps its bytes. A removed element leaves the indentation of its line behind, as this diff shows:

```text
12c12
<   <script src="/js/analytics.js"></script>
---
>   
52,55c52,53
<   <script>
<     document.querySelectorAll('.card').forEach(c => c.addEventListener('click', track));
<   </script>
<   <button onclick="window.scrollTo(0, 0)" class="to-top">Back to top</button>
---
>   
>   <button class="to-top">Back to top</button>
```

**This is not a sanitizer.** onehtml has no sanitizing API and no allow-list of safe markup. The code above removes exactly what it names: `script` elements, attributes starting with `on`, and `href` values starting with `javascript:`. HTML can run or load code in many other ways that this doesn’t touch, such as `iframe`, `object`, `embed`, SVG, `meta http-equiv="refresh"`, `base href`, form actions and CSS. Use it to clean up pages you control, such as before an archive or a diff. Don’t use it to make untrusted HTML safe to show to users. For that, use a dedicated allow-list sanitizer.

The parser itself is safe on hostile input: scripts are inert text, nothing is fetched, and input limits are checked before the work they guard. That protects your process, not the people who later open the HTML.

To remove other elements the same way, change the selector, for example `Edit.Remove` for every `iframe` or `noscript`. The edit operations are in [Editing](https://recursiveai.org/onehtml/docs/editing/).


<!-- https://recursiveai.org/onehtml/cookbook/save-and-replay-edits/ -->

# Save edits as JSON and replay them

Store edits in the versioned onehtml-edits JSON format and apply them to another copy of the page later. Replay finds each target again or reports why it can’t, and never edits the wrong element.

An `Edit` in memory points at a node of one snapshot. To keep edits across processes or page versions, `EditJson.Create` turns them into an envelope whose targets are durable. Each target has a locator (a CSS selector unique in the page), a fingerprint (tag, key attributes and hashes of the text and path), and an anchor (the byte range and a hash of its bytes).

```csharp
using RecursiveAI.OneHtml;
using RecursiveAI.OneHtml.Editing;

string html = File.ReadAllText("events.html");
Document original = Document.Parse(html);
Node img = original.Root.QuerySelector("main img:not([alt])");
Node partner = original.Root.QuerySelector("a[target=_blank]");

// Save edits as versioned JSON, with durable targets instead of in-memory handles
EditEnvelope envelope = EditJson.Create(original, new[]
{
    Edit.SetAttribute(img, "alt", "Children listening to a story")
        .WithMeta(new Dictionary<string, object> { ["ticket"] = "WEB-212" }),
    Edit.SetAttribute(partner, "rel", "noopener"),
});
File.WriteAllText("events.edits.json", EditJson.ToJson(envelope, indented: true));
Console.WriteLine($"First target: {envelope.Edits[0].Target!.Locator}");

void Replay(string label, string page)
{
    EditEnvelope saved = EditJson.Parse(File.ReadAllText("events.edits.json"));
    ReplayResult replay = EditReplay.Replay(saved, Document.Parse(page));
    Console.WriteLine($"{label}: succeeded {replay.Succeeded}");
    foreach (ReplayOutcome outcome in replay.Outcomes)
    {
        Console.WriteLine($"  edit {outcome.Index}: {outcome.Status} {outcome.Reason} {outcome.MetaJson}");
    }
}

// 1. Someone changed the text above the image: every byte offset after it moved
Replay("Text changed", html.Replace("Saturdays at 10:30", "Saturdays at 11:00, starting in May"));

// 2. A new card was inserted first: article:nth-of-type(1) is now a different element
Replay("Card inserted", html.Replace(
    "<!-- events are edited by hand",
    "<article class=\"card\"><h2>Book sale</h2><img src=\"/img/sale.jpg\" alt=\"\"></article>\n    <!-- events are edited by hand"));

// 3. The image is gone
Replay("Image removed", html.Replace("<img src=\"/img/story-time.jpg\" width=640 height=360>", ""));
```

```text
First target: #content > article:nth-of-type(1) > img
Text changed: succeeded True
  edit 0: Applied  {"ticket":"WEB-212"}
  edit 1: Applied  
Card inserted: succeeded False
  edit 0: Stale the element the locator finds has a different tag or key attributes than the target had {"ticket":"WEB-212"}
  edit 1: Stale the element the locator finds has a different tag or key attributes than the target had 
Image removed: succeeded False
  edit 0: Stale the locator matches nothing: #content > article:nth-of-type(1) > img {"ticket":"WEB-212"}
  edit 1: NotAttempted  
```

The saved first edit looks like this:

```json
{
  "op": "setAttribute",
  "target": {
    "locator": "#content > article:nth-of-type(1) > img",
    "fingerprint": {
      "tag": "img",
      "attrs": {
        "src": "/img/story-time.jpg"
      },
      "text": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "path": "sha256:e65c3a7e9beab0adae31be014068e912aae457e050b4d3adea04e09597f884de"
    },
    "anchor": {
      "start": 1035,
      "end": 1087,
      "bytes": "sha256:1a78698d2b635aade3ba3ba8c10bcae8d4452e3c395ca1826e08b66ebf3a34ec"
    }
  },
  "name": "alt",
  "value": "Children listening to a story",
  "meta": {"ticket":"WEB-212"}
}
```

How replay decided:

1. **Text changed.** Every byte offset after the edit moved, so the anchor no longer held. The locator still matched exactly one element, and its fingerprint matched, so both edits applied.
2. **Card inserted.** `article:nth-of-type(1)` now selects the new card. Its image has a different `src`, so the fingerprint didn’t match and the edit is `Stale`. A positional locator selects whatever sits at that position now, so a mismatch means stop, not guess. The second edit’s target moved the same way.
3. **Image removed.** The locator matches nothing, so the edit is `Stale`. The second edit resolved but is `NotAttempted`, because a transaction applies all of its edits or none.

Other outcomes are `Ambiguous` (several candidates), `Invalid` and `Failed`. `meta` is yours: the library stores it and hands it back as `MetaJson`, and never reads it. In memory it must be JSON-shaped: strings, numbers, booleans, `JsonElement`, string-keyed dictionaries or sequences of those. An anonymous object throws `ArgumentException`.

Writing is deterministic: the same edits give the same bytes on every platform. The full format and replay rules are in [Edit format](https://recursiveai.org/onehtml/docs/edit-format/), and how locators are chosen is in [Locators](https://recursiveai.org/onehtml/docs/locators/).


<!-- https://recursiveai.org/onehtml/cookbook/wcag-checks-ci-sarif/ -->

# Run WCAG checks in CI with SARIF output

Check every HTML file of a built site against WCAG 2.2 AA without a browser, write one SARIF 2.1.0 file per page for your code-scanning tool, and fail the build when a rule fails.

This is a small console app that you run after your site builds. It takes the output directory and a results directory, checks each `.html` file, and returns exit code 1 if anything failed.

```csharp
using RecursiveAI.OneHtml;
using RecursiveAI.OneHtml.Accessibility.Validation;
using RecursiveAI.OneHtml.Accessibility.Validation.Catalogue;

// Usage: dotnet run -- <site directory> <output directory>
string siteDir = args.Length > 0 ? args[0] : "site";
string outDir = args.Length > 1 ? args[1] : "a11y-results";
Directory.CreateDirectory(outDir);

var checker = new Checker();
var options = new CheckOptions { Profile = ValidationProfile.Wcag22AA };
int failures = 0;

foreach (string path in Directory.EnumerateFiles(siteDir, "*.html", SearchOption.AllDirectories).Order())
{
    string relative = Path.GetRelativePath(siteDir, path).Replace('\\', '/');
    CheckReport report = checker.Check(Document.Parse(File.ReadAllBytes(path)), options);

    string sarif = report.ToSarifJson(new ExportOptions { Url = relative, Indented = true });
    File.WriteAllText(Path.Combine(outDir, relative.Replace('/', '_') + ".sarif"), sarif);

    int failed = report.Count(Outcome.Failed);
    int review = report.Count(Outcome.NeedsReview) + report.Count(Outcome.NeedsRender);
    Console.WriteLine($"{relative}: {failed} failed, {review} to review");
    foreach (RuleResult result in report.WithOutcome(Outcome.Failed))
    {
        Console.WriteLine($"  {result.RuleId} at {result.Locator}: {result.Message}");
    }
    failures += failed;
}

return failures == 0 ? 0 : 1;
```

Run against a site with two pages:

```shell
dotnet run -- site a11y-results
```

```text
events/index.html: 2 failed, 28 to review
  button-name at form > button: The button has no accessible name.
  image-alt at #content > article:nth-of-type(1) > img: The image has no accessible name.
staff.html: 5 failed, 5 to review
  aria-deprecated-role at [role="directory"]: The role directory is deprecated.
  aria-valid-attr at p: The element has an aria- attribute that WAI-ARIA does not define.
  avoid-inline-spacing at p: Spacing set with !important in the style attribute stops a reader's style sheet from widening it.
  listitem at [role="directory"] > li:nth-of-type(1): The li is not inside a ul, an ol or a list.
  listitem at [role="directory"] > li:nth-of-type(2): The li is not inside a ul, an ol or a list.
```

The exit code is 1, so the CI step fails.

**Profiles.** `ValidationProfile.Wcag22AA` runs the rules that check a WCAG 2.2 A or AA criterion. `Wcag21AA` and `Wcag20AA` are there for older targets. `All` adds best-practice rules that no criterion requires. To narrow further, use `CheckOptions.Criteria` (criterion numbers such as `"1.1.1"`), `Tags` or `RuleIds`. A profile selects rules. It is not a statement about legal compliance.

**What gets reported.** Failures become SARIF results with `kind: "fail"` and a `level` from the rule’s impact: `error` for critical and serious, `warning` for moderate, `note` for minor. `NeedsReview` and `NeedsRender` results are written with `kind: "review"` and `level: "none"`, as SARIF requires for anything that isn’t a failure. A tool that filters on level alone won’t show them. Passed and inapplicable results are left out unless you set `IncludePassed` or `IncludeInapplicable` in `ExportOptions`.

Each result has a region with line, column, byte offset and a snippet of the start tag, plus a locator (a CSS selector unique in the page). Each rule lists the WCAG criteria it checks, with help text and, where the rule comes from an ACT rule or an axe-core rule, a link to that rule’s page. Where a rule has exactly one correct fix, the result carries a SARIF `fix` whose byte replacements come from running the edit:

```json
[{"description": {"text": "Use the role list instead of directory."}, "artifactChanges": [{"artifactLocation": {"uri": "staff.html", "index": 0}, "replacements": [{"deletedRegion": {"startLine": 10, "startColumn": 13, "endLine": 10, "endColumn": 22, "byteOffset": 179, "byteLength": 9}, "insertedContent": {"text": "list"}}]}]}]
```

**Things to know before you gate on it:**

- `ExportOptions.Url` becomes the artifact’s `uri`, so pass the path your code-scanning tool expects for the file. Without it, the artifact is named `urn:onehtml:document:sha256:` plus a hash of the bytes.
- The checker sees the HTML you give it. Pages built by script should be checked from the browser’s serialized DOM, and rules that need layout (contrast over images, target size) report `NeedsRender` unless you supply `RenderedFacts` from Chrome.
- Script-driven state is invisible. Results under a focus or hover context are marked “CSS only”.
- Gate on failures, and treat review results as a worklist. The checker doesn’t replace human review.

Report formats: [SARIF export](https://recursiveai.org/onehtml/docs/sarif/) and [Results](https://recursiveai.org/onehtml/docs/results/), which also covers the native and axe-compatible JSON from `ToNativeJson()` and `ToAxeJson()`. Which criteria are covered, and how: [Coverage](https://recursiveai.org/onehtml/docs/coverage/). To fix what the checker can fix for you: [Apply suggested fixes](https://recursiveai.org/onehtml/cookbook/apply-suggested-fixes/).

To combine these checks with browser tests: [Playwright accessibility testing in C#](https://recursiveai.org/onehtml/articles/playwright-accessibility-testing-csharp/).

WCAG checks in xUnit and WebApplicationFactory, compared with axe: [Automated accessibility testing in .NET](https://recursiveai.org/onehtml/articles/automated-accessibility-testing-dotnet/).