Repeat position:fixed content on every page, per css-position-3

Verified against the actual W3C spec text (css-position-3): "in paged
media, the page area of each page; fixed positioned boxes are thus
replicated on every page", and UAs "must not paginate the content of
fixed-positioned boxes". Scoped to top/left-anchored fixed content only
(a page header/watermark) - bottom/right are a separate, pre-existing gap:
neither property is parsed for absolute/fixed positioning at all, so a
bottom-anchored footer, the more common real print pattern, needs that
fixed first.

FragmentEmitter now collects every position:fixed box in the tree
(CollectFixedRoots, handling arbitrary nesting depth) and, for each
materialized page, builds a fresh fragment for it against a page-local band
(top=0) rather than the page's real band top - a fixed box's own Location is
already page-relative (CssBox.PerformLayoutImp's Position==Fixed branch
never routes it through normal absolute-Y-computing flow at all), so this
reuses the same geometry unchanged on every page. Excluded from the normal
per-page walk to avoid a duplicate/misplaced render on whichever page its
raw offset would otherwise land on. InlineFragmentation.ApplyLineBreaking
now also skips fixed boxes outright - their content must not paginate.

Confirming this through actual PDF output (not just the fragment tree)
surfaced a second, real, pre-existing bug: FragmentPainter.LiveTreeOffset/
LiveTreeExtraOffset unconditionally undid the current page's band top from
live-tree geometry, on the documented assumption that "band membership is
orthogonal to scroll-offset suppression" for fixed content. That assumption
was true when fixed content only ever appeared on one page (wherever its
raw offset landed) but breaks now that it's intentionally repeated: a fixed
box's live geometry is already page-relative, so subtracting a nonzero band
top pushes its containing-block visibility/overflow-clip check far outside
every page except the one whose band top happens to equal its own small
offset - confirmed via a real generated PDF, where the header only rendered
on page 0. Fixed by making both offsets skip the band-top term entirely for
fixed (or fixed-ancestor) content.

Author: jhaygood86

Source/HtmlRenderer/Core/Fragmentation/FragmentEmitter.cs

@@ -1,8 +1,10 @@
 using System;
 using System.Collections.Generic;
+using System.Linq;
 using TheArtOfDev.HtmlRenderer.Adapters.Entities;
 using TheArtOfDev.HtmlRenderer.Core.Dom;
 using TheArtOfDev.HtmlRenderer.Core.Fragments;
+using TheArtOfDev.HtmlRenderer.Core.Utils;
 
 namespace TheArtOfDev.HtmlRenderer.Core.Fragmentation
 {
@@ -55,6 +57,16 @@ internal FragmentTree Finish()
             var lastSlot = _container.PageIndexOf(Math.Max(0, root.ActualBottom - Epsilon));
             var fragmentainers = new List<FragmentainerFragment>();
 
+            // css-position-3, paged media: a fixed box's containing block is each page's own page area,
+            // and it "is thus replicated on every page". Collected once - each fixed box's own Location
+            // is already page-relative (CssBox never runs it through normal top-computing flow; see
+            // CssBox.PerformLayoutImp's own Position==Fixed branch), so building its fragment against a
+            // band starting at Y=0 (rather than this slot's real band top) localizes it to exactly that
+            // same relative position on every page, unchanged.
+            var fixedRoots = new List<CssBox>();
+            CollectFixedRoots(root, fixedRoots);
+            var fixedBand = new PageBand(0, _container.PageSize.Height);
+
             for (var slot = 0; slot <= lastSlot; slot++)
             {
                 var bandTop = _container.PageTopOf(slot);
@@ -63,11 +75,23 @@ internal FragmentTree Finish()
 
                 // CSS Paged Media 3 3.2: a page-slot no box has any content in is never materialized -
                 // this falls out of the walk rather than being special-cased, since a box only gets
-                // built into this fragmentainer at all when HasContentInBand finds something.
+                // built into this fragmentainer at all when HasContentInBand finds something. Fixed
+                // content deliberately does not itself justify materializing an otherwise content-empty
+                // slot - matches this port's existing blank-page-skipping scope.
                 if (!HasContentInBand(root, band))
                     continue;
 
                 var rootFragment = BuildBoxFragment(root, slot, band);
+                if (fixedRoots.Count > 0)
+                {
+                    var fixedFragments = fixedRoots
+                        .Where(fixedRoot => HasContentInBand(fixedRoot, fixedBand))
+                        .Select(fixedRoot => BuildBoxFragment(fixedRoot, slot, fixedBand))
+                        .ToList();
+                    if (fixedFragments.Count > 0)
+                        rootFragment = rootFragment with { Children = rootFragment.Children.Concat(fixedFragments).ToList() };
+                }
+
                 var rect = new RRect(0, 0, _container.PageSize.Width, band.Height);
                 var geometry = new PageBandGeometry(bandTop, band.Height, _container.MarginTop, _container.MarginRight, _container.MarginBottom, _container.MarginLeft);
                 fragmentainers.Add(new FragmentainerFragment(rect, slot, geometry, bandTop, rootFragment));
@@ -76,13 +100,29 @@ internal FragmentTree Finish()
             return new FragmentTree(fragmentainers);
         }
 
+        /// <summary>
+        /// Finds every <c>position:fixed</c> box in the tree, at any nesting depth - each one gets its
+        /// own independent repeat-per-page treatment in <see cref="Finish"/>, regardless of whether it's
+        /// nested inside another fixed box (rare, but each still resolves its own page-relative position
+        /// independently per css-position-3, so neither should be folded into the other's subtree).
+        /// </summary>
+        private static void CollectFixedRoots(CssBox box, List<CssBox> into)
+        {
+            foreach (var child in box.Boxes)
+            {
+                if (child.Position == CssConstants.Fixed)
+                    into.Add(child);
+                CollectFixedRoots(child, into);
+            }
+        }
+
         /// <summary>
         /// Whether <paramref name="box"/> or any descendant has some rectangle (its own decoration
         /// rects, a word, or a child's) overlapping <paramref name="band"/> - used both to decide
         /// whether a page-slot is content-empty (skip it) and whether a child belongs in this band's
         /// fragment at all.
         /// </summary>
-        private static bool HasContentInBand(CssBox box, PageBand band)
+        private bool HasContentInBand(CssBox box, PageBand band)
         {
             if (box.Rectangles.Count == 0)
             {
@@ -103,6 +143,13 @@ private static bool HasContentInBand(CssBox box, PageBand band)
 
             foreach (var child in box.Boxes)
             {
+                // A fixed box is handled separately when there's a real page grid (see
+                // CollectFixedRoots/Finish) - it repeats identically on every page rather than
+                // belonging to whichever band its own (page-relative, not absolute) coordinates would
+                // otherwise overlap. Without a real page grid (WinForms/WPF continuous-scroll, one
+                // fragmentainer for the whole document) it stays in the normal walk unchanged - "stays
+                // put" there is a paint-time scroll-offset suppression, not a repeat-per-page concern.
+                if (_container.HasRealPageGrid && child.Position == CssConstants.Fixed) continue;
                 if (HasContentInBand(child, band)) return true;
             }
 
@@ -156,6 +203,8 @@ private BoxFragment BuildBoxFragment(CssBox box, int fragmentainerIndex, PageBan
             var children = new List<BoxFragment>();
             foreach (var child in box.Boxes)
             {
+                // See the matching check/comment in HasContentInBand.
+                if (_container.HasRealPageGrid && child.Position == CssConstants.Fixed) continue;
                 if (HasContentInBand(child, band))
                     children.Add(BuildBoxFragment(child, fragmentainerIndex, band));
             }

Source/HtmlRenderer/Core/Fragmentation/InlineFragmentation.cs

@@ -1,6 +1,7 @@
 using System;
 using System.Collections.Generic;
 using TheArtOfDev.HtmlRenderer.Core.Dom;
+using TheArtOfDev.HtmlRenderer.Core.Utils;
 
 namespace TheArtOfDev.HtmlRenderer.Core.Fragmentation
 {
@@ -41,7 +42,12 @@ internal static class InlineFragmentation
         internal static void ApplyLineBreaking(CssBox blockBox)
         {
             var container = blockBox.HtmlContainer;
-            if (container == null || !container.HasRealPageGrid)
+            // A fixed box (css-position-3, paged media) is repeated identically on every page and its
+            // own coordinates are page-relative, not absolute document-Y (see FragmentEmitter's
+            // CollectFixedRoots) - unlike a float or an absolutely-positioned box, which stay in normal
+            // document flow and must still paginate like anything else, the UA "must not paginate the
+            // content of fixed-positioned boxes" (css-position-3), so this correction does not apply.
+            if (container == null || !container.HasRealPageGrid || blockBox.Position == CssConstants.Fixed)
                 return;
 
             var lines = blockBox.LineBoxes;

Source/HtmlRenderer/Core/Paint/Content/ReplacedFragmentPainter.cs

@@ -27,7 +27,7 @@ public void Paint(FragmentPainter painter, RGraphics g, BoxFragment fragment)
             var rect = fragment.PrimaryRect;
             rect.Offset(painter.FragmentLocalOffset(box.IsFixed));
 
-            var clipped = RenderUtils.ClipGraphicsByOverflow(g, box, painter.LiveTreeExtraOffset);
+            var clipped = RenderUtils.ClipGraphicsByOverflow(g, box, painter.LiveTreeExtraOffset(box.IsFixed));
 
             box.PaintBackground(g, rect, true, true);
             BordersDrawHandler.DrawBoxBorders(g, box, rect, true, true);

Source/HtmlRenderer/Core/Paint/FragmentPainter.cs

@@ -81,22 +81,41 @@ internal RPoint FragmentLocalOffset(bool isFixed)
         /// <summary>
         /// The offset to apply to a rect read straight off the live <see cref="CssBox"/> tree (still
         /// absolute document-Y, unlike fragment-tree geometry) to reach the same paint position
-        /// <see cref="FragmentLocalOffset"/> gives fragment-local geometry: additionally undoes
-        /// <see cref="_bandTop"/>, regardless of <paramref name="isFixed"/> (band membership is
-        /// orthogonal to scroll-offset suppression).
+        /// <see cref="FragmentLocalOffset"/> gives fragment-local geometry: undoes <see cref="_bandTop"/>
+        /// - except for a fixed (or fixed-ancestor) box, whose live geometry is already page-relative
+        /// (see the remark below), where undoing this painter's current band top would double-subtract
+        /// it, pushing the box far outside every page except the one whose band top happens to equal its
+        /// own small top offset.
         /// </summary>
+        /// <remarks>
+        /// A real bug found while confirming <see cref="FragmentEmitter"/>'s fixed-position repeat-per-page
+        /// support through actual PDF output: <c>CssBox.PerformLayoutImp</c> never routes a
+        /// <c>Position==Fixed</c> box through normal top-computing flow at all (its <c>Left</c>/<c>Top</c>
+        /// property setters assign <c>Location</c> directly, from <c>GetActualLocation</c>, resolved
+        /// against the page size) - so unlike ordinary content, whose live <c>Location</c> genuinely is an
+        /// absolute document-Y this painter's current band top needs undoing from, a fixed box's live
+        /// <c>Location</c> already IS the small, page-relative offset the fragment tree also uses. This
+        /// only affected the containing-block visibility/overflow-clip checks below (<see cref="PaintFragment"/>'s
+        /// own check, and <see cref="RenderUtils.ClipGraphicsByOverflow"/> via <see cref="LiveTreeExtraOffset"/>)
+        /// - the fragment tree's own already-correct geometry (<c>fragment.Lines</c>/<c>fragment.Words</c>,
+        /// via <see cref="FragmentLocalOffset"/> alone) was never affected, which is why the fixed content
+        /// was confirmed correctly PRESENT in the fragment tree on every page before this was found - it
+        /// was being computed correctly and then clipped away on every page except one.
+        /// </remarks>
         internal RPoint LiveTreeOffset(bool isFixed)
         {
             var offset = FragmentLocalOffset(isFixed);
-            return new RPoint(offset.X, offset.Y - _bandTop);
+            return isFixed ? offset : new RPoint(offset.X, offset.Y - _bandTop);
         }
 
         /// <summary>
         /// The portion of <see cref="LiveTreeOffset"/> that <see cref="RenderUtils.ClipGraphicsByOverflow"/>
-        /// doesn't already add itself (it applies <see cref="HtmlContainerInt.ScrollOffset"/>/<c>IsFixed</c>
-        /// gating internally) - pass as its <c>extraOffset</c> parameter.
+        /// doesn't already add itself (it applies <see cref="HtmlContainerInt.ScrollOffset"/> gating
+        /// internally) - pass as its <c>extraOffset</c> parameter. See <see cref="LiveTreeOffset"/>'s own
+        /// remark for why <paramref name="isFixed"/> must gate the band-top term here too.
         /// </summary>
-        internal RPoint LiveTreeExtraOffset => new RPoint(_pageOrigin.X, _pageOrigin.Y - _bandTop);
+        internal RPoint LiveTreeExtraOffset(bool isFixed) =>
+            isFixed ? new RPoint(_pageOrigin.X, _pageOrigin.Y) : new RPoint(_pageOrigin.X, _pageOrigin.Y - _bandTop);
 
         internal void Paint(RGraphics g, FragmentainerFragment fragmentainer)
         {
@@ -169,7 +188,7 @@ private void PaintFragmentContent(RGraphics g, BoxFragment fragment)
                 return;
             }
 
-            var clipped = RenderUtils.ClipGraphicsByOverflow(g, box, LiveTreeExtraOffset);
+            var clipped = RenderUtils.ClipGraphicsByOverflow(g, box, LiveTreeExtraOffset(box.IsFixed));
             var clip = g.GetClip();
             // fragment.Lines/fragment.Words are already fragment-local (FragmentEmitter subtracted the
             // band top at build time) - only FragmentLocalOffset (scroll + page-origin) applies to either.

Source/Test/HtmlRenderer.IntegrationTest/FixedPositionRepeatsPerPageTest.cs

@@ -0,0 +1,107 @@
+using System.Collections.Generic;
+using System.Drawing;
+using System.Linq;
+using System.Reflection;
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+using TheArtOfDev.HtmlRenderer.Core;
+using TheArtOfDev.HtmlRenderer.Core.Fragments;
+using TheArtOfDev.HtmlRenderer.WinForms;
+
+namespace TheArtOfDev.HtmlRenderer.IntegrationTest;
+
+/// <summary>
+/// Verifies a real, spec-confirmed missing feature found while auditing this port's fragmentation engine
+/// against PeachPDF a third time, then checking the actual W3C text directly
+/// (<see href="https://www.w3.org/TR/css-position-3/">css-position-3</see>): "in paged media, the page
+/// area of each page; fixed positioned boxes are thus replicated on every page", and user agents "must
+/// not paginate the content of fixed-positioned boxes". A <c>position:fixed</c> element (a print
+/// header/watermark - <c>bottom</c>/<c>right</c> anchoring is a separate, pre-existing gap: neither
+/// property is parsed for absolute/fixed positioning at all, so a bottom-anchored footer, the more common
+/// real print pattern, is out of scope here) previously rendered on exactly one page - wherever its
+/// <c>top</c>/<c>left</c> offset happened to be interpreted as an absolute document coordinate - instead
+/// of being replicated identically on every page.
+/// </summary>
+[TestClass]
+[DoNotParallelize]
+public sealed class FixedPositionRepeatsPerPageTest
+{
+    private static HtmlContainerInt GetInternal(HtmlContainer wrapper)
+    {
+        var prop = typeof(HtmlContainer).GetProperty("HtmlContainerInt", BindingFlags.NonPublic | BindingFlags.Instance)!;
+        return (HtmlContainerInt)prop.GetValue(wrapper)!;
+    }
+
+    private static IEnumerable<(string Text, double Top)> AllWords(BoxFragment f)
+    {
+        foreach (var w in f.Words)
+            if (!w.Word.IsLineBreak)
+                yield return (w.Word.Text, w.Rect.Top);
+        foreach (var c in f.Children)
+            foreach (var x in AllWords(c))
+                yield return x;
+    }
+
+    [TestMethod]
+    public async Task TopLeftFixedElement_RepeatsIdenticallyOnEveryPage()
+    {
+        using var wrapper = new HtmlContainer();
+        var filler = string.Concat(Enumerable.Repeat("<p style='margin:0;'>filler line of body text</p>", 60));
+        await wrapper.SetHtml(
+            $"""
+            <html><body>
+                <div style="position:fixed; top:5px; left:5px;">PageHeaderMarker</div>
+                {filler}
+            </body></html>
+            """);
+
+        var container = GetInternal(wrapper);
+        container.PageSize = new TheArtOfDev.HtmlRenderer.Adapters.Entities.RSize(300, 300);
+        container.MarginTop = 0;
+        wrapper.MaxSize = new SizeF(300, 0);
+
+        using var bitmap = new Bitmap(300, 20000);
+        using var g = Graphics.FromImage(bitmap);
+        wrapper.PerformLayout(g);
+
+        var tree = container.FragmentTree;
+        Assert.IsGreaterThan(1, tree.Fragmentainers.Count, "the filler content must genuinely span multiple pages for this test to be meaningful");
+
+        for (var i = 0; i < tree.Fragmentainers.Count; i++)
+        {
+            var markerHits = AllWords(tree.Fragmentainers[i].Root).Where(w => w.Text == "PageHeaderMarker").ToList();
+            Assert.AreEqual(1, markerHits.Count, $"page {i} should show the fixed marker exactly once - not zero (missing) and not more than one (duplicated by both the repeat mechanism and the normal walk)");
+            Assert.AreEqual(5.0, markerHits[0].Top, 0.5, $"page {i}'s marker must be at the same page-relative offset (top:5px) as every other page");
+        }
+    }
+
+    [TestMethod]
+    public async Task FixedElement_StillRendersOnce_WithoutARealPageGrid()
+    {
+        // WinForms/WPF's continuous-scroll convention (no PageSize set - HasRealPageGrid=false): the
+        // repeat-per-page mechanism must not apply here at all, since "stays put" for that viewport is a
+        // paint-time scroll-offset suppression (CssBox.IsFixed), not a per-page repeat concern - confirms
+        // the new exclusion in FragmentEmitter is correctly gated on HasRealPageGrid.
+        using var wrapper = new HtmlContainer();
+        var filler = string.Concat(Enumerable.Repeat("<p style='margin:0;'>filler line of body text</p>", 60));
+        await wrapper.SetHtml(
+            $"""
+            <html><body>
+                <div style="position:fixed; top:5px; left:5px;">PageHeaderMarker</div>
+                {filler}
+            </body></html>
+            """);
+
+        wrapper.MaxSize = new SizeF(300, 0);
+        using var bitmap = new Bitmap(300, 20000);
+        using var g = Graphics.FromImage(bitmap);
+        wrapper.PerformLayout(g);
+
+        var container = GetInternal(wrapper);
+        Assert.IsFalse(container.HasRealPageGrid);
+        var tree = container.FragmentTree;
+        Assert.AreEqual(1, tree.Fragmentainers.Count);
+
+        var markerHits = AllWords(tree.Fragmentainers[0].Root).Where(w => w.Text == "PageHeaderMarker").ToList();
+        Assert.AreEqual(1, markerHits.Count, "the fixed element must still render exactly once via the normal walk when there's no real page grid");
+    }
+}