Add a real, spec-compliant CSS3/4 engine (ported from ExCSS via PeachPDF)

[jhaygood86]

Summary

This replaces HTML-Renderer's ad-hoc CSS parsing/matching with a real CSS3/4 spec-compliant CSS engine — a proper cascade, a real selector engine (combinators, attribute selectors, structural pseudo-classes, :not()/:is()/:has(), ::before/::after), @media evaluation, and calc() — in place of the old simple class-name-keyed block lookup.

The engine is derived from ExCSS, sourced from the more up-to-date fork maintained in PeachPDF, and ported into Source/HtmlRenderer/Core/CssEngine. Two of HTML-Renderer's own non-standard CSS extensions — corner-radius and background-gradient — depended on the old parser and have been replaced with their spec-compliant equivalents (border-radius, linear-gradient()) so the demo app keeps working against the new engine.

Details

• CSS engine: Ported from ExCSS, but sourced from the more up-to-date version maintained by PeachPDF, rather than upstream ExCSS. The vendored tree tracks PeachPDF v0.9.6.
• Minimal CSS fixes: Applied only what was needed to keep existing functionality working — e.g. replacing the corner-radius and background-gradient extensions with spec-compliant versions (see below).
• Scope: This is a port of the engine plus the fixes needed to resolve the regressions it introduced, and to make the engine's capabilities actually reachable from the renderer. It is not a full CSS3/4 compliance pass — follow-up PRs will incrementally improve spec compliance on top of this engine.

What now works end-to-end

• Real cascade: origin-aware (user-agent vs. author), specificity- and document-order-ranked, with a correct !important tier and the CSS-wide keywords initial / inherit / unset / revert / revert-layer.
• Full selector engine: combinators (descendant, >, +, ~), comma-separated selector lists, attribute selectors ([attr], [attr=v], [attr~=v], [attr*=v], [attr^=v], [attr$=v], [attr|=v]), :not(), :is()/:matches(), :where() (zero specificity), :has() (descendant form), structural pseudo-classes :nth-child()/:nth-last-child()/:nth-of-type()/:nth-last-of-type() (including the CSS4 An+B of <selector> form) and :nth-column()/:nth-last-column(), :first-child/:last-child/:first-of-type/:last-of-type, :only-child/:only-of-type, :root, :link, and ::before/::after generated-content pseudo-elements.
• CSS Nesting: nested rules are resolved against their parent at parse time and participate in the cascade.
• @media evaluation: media type and features are evaluated against the platform, not assumed. Two new RAdapter properties describe the surface being rendered onto — DefaultMediaType (screen, or print for PdfSharp) and SystemColorScheme (light/dark, read from the Windows app theme by the WinForms and WPF adapters). Width/height, orientation, aspect-ratio, resolution, colour depth and the prefers-* features are all evaluated, and re-evaluated dynamically when the window is resized or the system theme changes.
• @layer: rules inside a layer apply (ordered by source position and specificity).
• @property and @font-palette-values parse into the CSS-OM.
• CSS Color 4/5: lab(), oklab(), lch(), oklch() and color-mix() resolve to real colours wherever a colour is parsed.
• CSS logical properties: margin-block/margin-inline, padding-block/padding-inline, inset* and border-block/border-inline* fully work — the engine resolves them to their physical equivalents (LTR / horizontal-tb), so the box model consumes them unchanged.
• calc(): parsed and evaluated for property values, agreeing exactly with non-calc() values for every absolute unit (1in = 96px, 1pt = 96/72px, 1pc = 16px).
• content:: supports attr() and the open/close quote keywords.
• Spec-compliant background-image: linear-gradient(...), replacing the old proprietary background-gradient extension.
• Spec-compliant border-radius, with independent per-corner horizontal/vertical elliptical radii, replacing the old proprietary corner-radius extension.
• Rule indexing: rules are bucketed by tag/class/id so cascade cost no longer scales as rules × boxes on large documents.

Behaviour changes worth reviewing

• @media screen and @media print blocks now apply. Previously the cascade ran against media type all and compared only the medium's type, so every typed @media block was dropped and @media all and (<feature>) matched unconditionally — applying rules guarded by a condition nothing had tested. Screen blocks now apply on WinForms/WPF and print blocks on PdfSharp, and each drops the other's.
• A media feature the matcher cannot evaluate drops its whole block, per Media Queries 4's "unknown feature is false", rather than letting untested rules through. A feature it does model but whose context is missing (a width query before the viewport is known) stays permissive.
• Absolute units resolve against 96dpi CSS pixels inside calc(). Previously the vendored engine resolved them against points while CssValueParser used 96dpi, so calc(1in) gave 72 where width: 1in gave 96.

Parsed but not yet rendered

These cascade correctly and are then ignored at the box boundary — nothing crashes, nothing misrenders:

• CSS Grid — the full property set parses and validates; there is no grid layout engine, so display: grid still lays out as a block.
• @layer ordering — rules inside layers apply, but layer precedence, !important layer reversal and revert-layer banding are not implemented.
• @property — the at-rule parses; syntax, initial-value and inherits are not honoured.
• @font-palette-values / font-palette / palette-mix() — no palette resolver, and the font backend has no CPAL concept.
• clip-path, box-shadow, aspect-ratio — no clip region, shadow draw handler or intrinsic-sizing hook.
• image-set() / cross-fade() / element(), radial-gradient() and conic gradients — parsed; only url() and linear-gradient() are painted.
• @import and <link> media conditions — @media blocks are evaluated, but an @import url(…) print; condition is ignored and <link media="…"> is not honoured. Both predate this PR.
• @supports / @container — conditions are not evaluated, so their contents do not apply.
• ::marker — not ported; list markers are still painted procedurally rather than as a generated box.
• content: — no counter() / counters() / string() / content().
• :has() — only the default descendant relative-selector form (no leading >, +, ~).
• :hover — matched and collected, but application remains commented out (pre-existing).

Verification

• Builds clean on both target frameworks (netstandard2.0 and net8.0); the warning count is unchanged from before the engine refresh, and the packed .nuspec dependency list is byte-identical.
• All 46 demo samples were rendered before and after the refresh and compared pixel by pixel. 14 differ, all by scattered ClearType sub-pixel fringe pixels on glyph edges (largest 482px of 1.12M, 0.04%); side-by-side crops are visually identical. No layout, colour or box-model differences.
• TestSamples/23.Media queries and color scheme.htm is a new demo sample covering the OS colour scheme, the media type, an unevaluable media feature, and a viewport-width probe. Toggling the Windows app theme, or resizing the window, updates the render live.

One deliberate divergence from the upstream engine is worth noting for future re-syncs: the vendor-prefixed -peachpdf-pdf-tag-type property has been removed, since nothing here consumes it. The vendored tree is therefore not a byte-for-byte mirror of upstream.

Related open issues

Confirmed by reading the relevant code paths (not just title-matching):

• corner-radius vs border-radius #152 — corner-radius vs border-radius: fixed directly (see above).
• CSS selector for wildcard classes does not work #169 — wildcard attribute class selectors ([class*="language-"]) don't match: fixed — the new engine has real attribute-selector support.
• css class names with periods don't work #168 — compound multi-class selectors (.token.property) don't match: fixed — the old engine's single-class-key lookup couldn't represent this; the new selector engine requires every class in a compound selector to match.
• ParseCssBlockProperties does not parse url attribute correctly #29 — url('data:...;base64,...') mis-parsed because of the semicolon inside the quoted string: fixed — the old ad-hoc parsing method is gone, replaced by a real, spec-correct tokenizer.
• ParseBorderProperty fails on default included CSS #28 — border: 1px inset; mis-parsed: fixed — the old ad-hoc border-shorthand parser is gone, replaced by a real, order-independent border shorthand implementation.
• Super slow performance when there are lots of "a" html tags #239 — severe slowdown with many <a> tags: likely resolved or significantly improved — the issue's own root cause (an O(rules × boxes) matching function with a hand-rolled <a>-tag special case) has been replaced by the new tag/class/id rule index. Not independently benchmarked.
• css background-color is not working #138 — background: shorthand set via a descendant selector not applying: likely fixed — both prerequisites (real descendant-combinator matching, real background shorthand parsing) are now in place, though the exact reported case wasn't directly reproduced.

Not addressed by this PR (layout/painting gaps, not parsing/cascade): #203 (position: absolute), #34 (float), #42 (table border-conflict resolution), #104/#103 (<tr> display/background-color).

[jhaygood86]

If this is merged after #243 , there's a small one line fix needed for this to swap out one use of the deprecated SubString class with just string.

[jhaygood86]

@eXpl0it3r I updated it to sync with PeachPDF 0.9.6, which had a decent CSS upgrade, and added some immediately beneficial features which I wired up into RAdapter