Add spec compliance tracking for CSS and HTML

.github/workflows/build.yml

@@ -82,6 +82,18 @@ jobs:
       env:
         PDF_OUTPUT_DIRECTORY: ${{ github.workspace }}/pdf-artifacts/${{ matrix.platform.name }}-${{ matrix.dotnet.name }}
 
+    - name: Spec compliance report
+      if: ${{ !cancelled() && runner.os == 'Windows' && matrix.dotnet.name == '.NET 8' }}
+      run: dotnet run --project Source/Tools/HtmlRenderer.SpecCompliance --configuration Release --no-build -- report --output spec-compliance.md --summary $env:GITHUB_STEP_SUMMARY
+
+    - name: Upload spec compliance report
+      if: ${{ !cancelled() && runner.os == 'Windows' && matrix.dotnet.name == '.NET 8' }}
+      uses: actions/upload-artifact@v7
+      with:
+        name: Spec compliance report
+        path: spec-compliance.md
+        if-no-files-found: ignore
+
     - name: Create HtmlRenderer.Core NuGet package
       run: dotnet pack Source/HtmlRenderer/HtmlRenderer.csproj --configuration Release --include-symbols -p:SymbolPackageFormat=snupkg --no-build --verbosity normal --output ${{ env.NuGetDirectory }}
 

Source/HtmlRenderer.CrossPlatform.slnf

@@ -11,7 +11,8 @@
       "HtmlRenderer.WPF\\HtmlRenderer.WPF.csproj",
       "Test\\HtmlRenderer.IntegrationTest\\HtmlRenderer.IntegrationTest.csproj",
       "Test\\HtmlRenderer.PdfSharp.Test\\HtmlRenderer.PdfSharp.Test.csproj",
-      "Test\\HtmlRenderer.Test\\HtmlRenderer.Test.csproj"
+      "Test\\HtmlRenderer.Test\\HtmlRenderer.Test.csproj",
+      "Tools\\HtmlRenderer.SpecCompliance\\HtmlRenderer.SpecCompliance.csproj"
     ]
   }
 }

Source/HtmlRenderer.PdfSharp/FontResolution/FontFamilyModel.cs

@@ -5,18 +5,11 @@
 namespace TheArtOfDev.HtmlRenderer.PdfSharp.FontResolution
 {
     /// <summary>
-    /// One registered face of a <see cref="FontFamilyModel"/>: its CSS Fonts Level 4 matching axes
-    /// (numeric weight, italic, stretch), the codepoint <see cref="CodepointRange"/>s it is restricted to
-    /// (from an <c>@font-face</c> <c>unicode-range</c> descriptor) or null when it has none - a face with
-    /// no explicit ranges is treated as covering everything (matching the same, deliberately simpler,
-    /// scope as the shared <c>Core.Handlers.FontsHandler</c> face registry - see its own doc comments for
-    /// why cmap-based coverage extraction isn't ported here: this codebase resolves one font per box, not
-    /// per glyph, so there is no per-glyph precision to exploit) - and the sniffed description
-    /// <see cref="FontResolver.ResolveTypeface(string,int,bool,int,int?)"/> hands back once this face is
-    /// chosen; <see cref="TtfFontDescription.FontNameInvariantCulture"/> doubles as this face's storage
-    /// key into <see cref="FontResolver.GetFont"/>.
+    /// One registered face of a <see cref="FontFamilyModel"/>: its CSS Fonts 4 matching axes, its
+    /// <c>unicode-range</c> or null when it has none (then it covers everything), and its description.
+    /// <see cref="TtfFontDescription.FontNameInvariantCulture"/> is the face's key into
+    /// <see cref="FontResolver.GetFont"/>.
     /// </summary>
-    /// <remarks>Ported from PeachPDF's <c>Fonts\FontFamilyModel.cs</c>.</remarks>
     internal sealed class FontFaceEntry
     {
         public FontFaceEntry(int weight, bool italic, int stretch, IReadOnlyList<CodepointRange> explicitRanges, TtfFontDescription description)
@@ -35,7 +28,7 @@ public FontFaceEntry(int weight, bool italic, int stretch, IReadOnlyList<Codepoi
         public TtfFontDescription Description { get; }
     }
 
-    /// <summary>One CSS font-family: its registered faces. Ported from PeachPDF's <c>Fonts\FontFamilyModel.cs</c>.</summary>
+    /// <summary>One CSS font-family: its registered faces.</summary>
     internal sealed class FontFamilyModel
     {
         public string Name { get; set; }

Source/HtmlRenderer.PdfSharp/FontResolution/FontResolver.cs

@@ -14,32 +14,14 @@
 namespace TheArtOfDev.HtmlRenderer.PdfSharp.FontResolution
 {
     /// <summary>
-    /// PDFsharp <see cref="IFontResolver"/> implementation backing the PdfSharp backend's font handling -
-    /// OS font discovery plus CSS Fonts Level 4 §5 nearest-match (slant→stretch→weight) face selection,
-    /// ported from PeachPDF's <c>Fonts\FontResolver.cs</c>. Unlike WinForms/WPF (which register an
-    /// <c>@font-face</c> face as an opaque platform font-family handle and let the OS/UI framework do
-    /// matching), PDFsharp's <see cref="IFontResolver"/> contract needs raw font bytes at PDF-generation
-    /// time for embedding, so this type does its own matching entirely and is called directly by
-    /// <c>Adapters.PdfSharpAdapter</c>'s <c>AddFontFace</c>/<c>GetFont</c> overrides, bypassing the shared
-    /// <c>Core.Handlers.FontsHandler</c> registry other backends use.
+    /// PDFsharp <see cref="IFontResolver"/> of the PdfSharp backend: system font discovery and
+    /// CSS Fonts 4 §5 face matching (slant, stretch, weight). PDFsharp needs the font bytes for embedding,
+    /// so this does its own matching instead of going through <c>Core.Handlers.FontsHandler</c>.
     /// </summary>
     /// <remarks>
-    /// Two deliberate scope departures from PeachPDF's own resolver, both already established for this
-    /// port's shared <c>Core.Handlers.FontsHandler</c> (see its own doc comments):
-    /// <list type="bullet">
-    /// <item>No cmap-coverage extraction fallback for <c>unicode-range</c>-less faces - a face with no
-    /// explicit <c>unicode-range</c> is simply treated as covering everything. This codebase resolves one
-    /// font per box (not per glyph/run), so there's no per-glyph precision for cmap coverage to buy.</item>
-    /// <item>No per-<c>FontResolver</c>-instance glyph-typeface/descriptor caching. PeachPDF supports many
-    /// concurrent <c>PdfGenerator</c>s each with their own <c>FontResolver</c>, so it isolates their custom
-    /// font caches from each other. This backend's <c>PdfSharpAdapter</c> (and this resolver with it) is a
-    /// single process-wide singleton via <see cref="Register"/>, matching this project's pre-existing
-    /// architecture - there's only ever one instance, so nothing to isolate.</item>
-    /// </list>
-    /// System font discovery itself is also adapted, not verbatim: no Android/iOS branches (this project's
-    /// <c>netstandard2.0;net8.0</c> target framework list has no mobile leg to run them on), and Linux
-    /// discovery shells out to the <c>fc-list</c> CLI rather than P/Invoking <c>libfontconfig.so.1</c>
-    /// directly (see <see cref="LinuxSystemFontResolver"/>'s own doc comment for why).
+    /// A face without <c>unicode-range</c> is assumed to cover everything, its glyphs aren't checked,
+    /// there's one font per box anyway. The resolver is a process-wide singleton (<see cref="Register"/>).
+    /// On Linux, fonts are found with the <c>fc-list</c> CLI, see <see cref="LinuxSystemFontResolver"/>.
     /// </remarks>
     public sealed class FontResolver : IFontResolver
     {

Source/HtmlRenderer.PdfSharp/PdfGenerator.cs

@@ -197,12 +197,7 @@ public static async Task AddPdfPages(PdfDocument document, string html, PdfGener
                         container.PerformLayout(measure);
                     }
 
-                    // One PDF page per fragmentainer the fragment tree actually materialized - a
-                    // content-empty page slot (CSS Paged Media 3 3.2, e.g. a huge margin that would
-                    // otherwise paginate through blank vertical space - see the margin-truncation
-                    // correction in BlockFragmentation) is simply never in this list, which is what
-                    // gives blank-page skipping for free here instead of the old ceil(height/pageHeight)
-                    // loop's naive page count.
+                    // One PDF page per fragmentainer, pages without content have none.
                     var tree = container.FragmentTree;
                     foreach (var fragmentainer in tree?.Fragmentainers ?? (IReadOnlyList<FragmentainerFragment>)Array.Empty<FragmentainerFragment>())
                     {
@@ -237,10 +232,7 @@ private static void HandleLinks(PdfDocument document, HtmlContainer container, X
             if (tree == null || tree.Fragmentainers.Count == 0)
                 return;
 
-            // Pagination slot -> PDF page index. Not a bare multiply/divide by page height any more:
-            // a content-empty slot is never materialized as a fragmentainer at all (blank-page
-            // skipping), so slot indices are not contiguous across tree.Fragmentainers the way a
-            // fixed-size page grid's would be.
+            // Pagination slot -> PDF page index, a content-empty slot gets no page (css-page-3 §3.2).
             var slotToPage = new Dictionary<int, int>();
             for (var pageIndex = 0; pageIndex < tree.Fragmentainers.Count; pageIndex++)
             {

Source/HtmlRenderer.WinForms/Adapters/WinFormsAdapter.cs

@@ -50,13 +50,10 @@ internal sealed class WinFormsAdapter : RAdapter
         /// </summary>
         private static readonly WinFormsAdapter _instance = new WinFormsAdapter();
 
-        // Adapter-level PrivateFontCollection for @font-face-loaded faces - one collection shared for the
-        // adapter's (process) lifetime, growing by one family per LoadFontFaceFontInt call.
+        // The @font-face faces, kept for the lifetime of the process.
         private readonly PrivateFontCollection _fontFaceCollection = new PrivateFontCollection();
 
-        // Backs LoadFontFaceFontInt's temp-file registration (see its own doc comment for why a temp file
-        // is used instead of PrivateFontCollection.AddMemoryFont) - one directory per process, cleaned up
-        // by the OS's normal temp-file housekeeping, not by this process.
+        // The font files of the @font-face faces, see LoadFontFaceFontInt. Left to the OS to clean up.
         private static readonly string _fontFaceTempDirectory = CreateFontFaceTempDirectory();
 
         private static string CreateFontFaceTempDirectory()
@@ -211,37 +208,13 @@ protected override RFont CreateFontInt(RFontFamily family, double size, RFontSty
         }
 
         /// <summary>
-        /// Loads one <c>@font-face</c> face's bytes into the adapter's <see cref="PrivateFontCollection"/>
-        /// via <see cref="PrivateFontCollection.AddFontFile"/> - through a temp file, matching this
-        /// adapter's own pre-existing <c>DemoForm.LoadCustomFonts</c> pattern (that path is untouched,
-        /// this is a new, separate mechanism specific to <c>@font-face</c>).
+        /// Adds the font to the <see cref="PrivateFontCollection"/> and returns its family, found by the
+        /// family name in the font file. <see cref="PrivateFontCollection.Families"/> groups the faces of
+        /// a family and isn't in insertion order.
         /// </summary>
         /// <remarks>
-        /// Deliberately NOT <see cref="PrivateFontCollection.AddMemoryFont"/>, despite it needing no temp
-        /// file: empirically (a throwaway repro project registering a dozen distinct families into one
-        /// <see cref="PrivateFontCollection"/>), <c>AddMemoryFont</c> is unreliable on this target
-        /// framework - <see cref="PrivateFontCollection.Families"/> permanently fails to reflect several of
-        /// the added families (not a timing race: polling for up to 300ms after the call never finds them
-        /// either), while the identical sequence of files through <c>AddFontFile</c> succeeds 100% of the
-        /// time across repeated runs. This is a known-flaky area of GDI+'s <c>AddMemoryFont</c> P/Invoke
-        /// path, not a bug in this port. The temp file is deliberately never deleted: GDI+ keeps it
-        /// memory-mapped for as long as this process-lifetime singleton's <see cref="PrivateFontCollection"/>
-        /// references it, and the OS's own temp-directory housekeeping reclaims it afterward - the same
-        /// "small, bounded, process-lifetime" rationale the removed <c>AddMemoryFont</c>/<c>AllocHGlobal</c>
-        /// approach relied on.
-        /// <para>
-        /// The returned <see cref="FontFamilyAdapter"/> is found by sniffing the font's own internal
-        /// family name via <see cref="TtfFontDescription"/> and matching it against
-        /// <see cref="PrivateFontCollection.Families"/> - not by comparing <c>Families.Length</c> before
-        /// and after, nor by taking the array's last entry. Two bugs made that approach unreliable: (1)
-        /// <c>Families</c> groups every face by family name (the whole point of
-        /// <see cref="PrivateFontCollection"/> - it lets <see cref="Font"/> pick the right face via
-        /// <see cref="FontStyle"/> automatically), so registering a second face of an *already-registered*
-        /// family (e.g. this face set's own Bold after its Regular) never changes the count at all; and
-        /// (2) even when the count does change, <c>Families</c> is returned in a GDI-defined (effectively
-        /// alphabetical) order, not insertion order, so "the last entry" is often a completely unrelated,
-        /// alphabetically-later family, not the one just added.
-        /// </para>
+        /// Goes through a temp file, <see cref="PrivateFontCollection.AddMemoryFont"/> doesn't reliably
+        /// list the added families. The file can't be deleted while the collection uses it.
         /// </remarks>
         protected override RFontFamily LoadFontFaceFontInt(byte[] fontBytes, string filePath)
         {

Source/HtmlRenderer.sln

@@ -31,6 +31,10 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "HtmlRenderer.IntegrationTes
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "HtmlRenderer.Test", "Test\HtmlRenderer.Test\HtmlRenderer.Test.csproj", "{7427E12F-1524-4405-AAD1-5AF8ACB3BBBC}"
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Tools", "Tools", "{07C2787E-EAC7-C090-1BA3-A61EC2A24D84}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "HtmlRenderer.SpecCompliance", "Tools\HtmlRenderer.SpecCompliance\HtmlRenderer.SpecCompliance.csproj", "{8E0BFCAC-F676-4EE1-B639-7D8F2F24656D}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -167,6 +171,18 @@ Global
 		{7427E12F-1524-4405-AAD1-5AF8ACB3BBBC}.Release|Mixed Platforms.Build.0 = Release|Any CPU
 		{7427E12F-1524-4405-AAD1-5AF8ACB3BBBC}.Release|x86.ActiveCfg = Release|Any CPU
 		{7427E12F-1524-4405-AAD1-5AF8ACB3BBBC}.Release|x86.Build.0 = Release|Any CPU
+		{8E0BFCAC-F676-4EE1-B639-7D8F2F24656D}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{8E0BFCAC-F676-4EE1-B639-7D8F2F24656D}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{8E0BFCAC-F676-4EE1-B639-7D8F2F24656D}.Debug|Mixed Platforms.ActiveCfg = Debug|Any CPU
+		{8E0BFCAC-F676-4EE1-B639-7D8F2F24656D}.Debug|Mixed Platforms.Build.0 = Debug|Any CPU
+		{8E0BFCAC-F676-4EE1-B639-7D8F2F24656D}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{8E0BFCAC-F676-4EE1-B639-7D8F2F24656D}.Debug|x86.Build.0 = Debug|Any CPU
+		{8E0BFCAC-F676-4EE1-B639-7D8F2F24656D}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{8E0BFCAC-F676-4EE1-B639-7D8F2F24656D}.Release|Any CPU.Build.0 = Release|Any CPU
+		{8E0BFCAC-F676-4EE1-B639-7D8F2F24656D}.Release|Mixed Platforms.ActiveCfg = Release|Any CPU
+		{8E0BFCAC-F676-4EE1-B639-7D8F2F24656D}.Release|Mixed Platforms.Build.0 = Release|Any CPU
+		{8E0BFCAC-F676-4EE1-B639-7D8F2F24656D}.Release|x86.ActiveCfg = Release|Any CPU
+		{8E0BFCAC-F676-4EE1-B639-7D8F2F24656D}.Release|x86.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -179,6 +195,7 @@ Global
 		{AF39851E-37B9-409E-A34D-CE091A098C86} = {E508FA78-D57E-492F-9BF7-23640001848A}
 		{A12F4432-337B-4030-B834-5D312A9FB16C} = {E508FA78-D57E-492F-9BF7-23640001848A}
 		{7427E12F-1524-4405-AAD1-5AF8ACB3BBBC} = {E508FA78-D57E-492F-9BF7-23640001848A}
+		{8E0BFCAC-F676-4EE1-B639-7D8F2F24656D} = {07C2787E-EAC7-C090-1BA3-A61EC2A24D84}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {902788D6-3165-491D-B860-DF2F74E66C1D}