feat: PDF/UA compliance for HTML tables, text decorations, and page-spanning content

Make tagged HTML output conform to PDF/UA-1 (ISO 14289-1) and PDF/UA-2, verified with veraPDF across the example suite.

Structure tagging:
- Serialize table cell ColSpan/RowSpan as PDF integers, not names
- Record colspan/rowspan and honor th scope (row/col) on cell elements
- Pass through explicit cell id/headers to the /ID and /Headers entries
- Keep empty table cells in the structure tree so rows keep their column count
- Emit <hr> and inline background/border decorations as Artifacts

Correctness:
- Suspend tagging during measurement and repeated-header replay so they no longer add phantom structure elements or desync the per-page MCID counter
- Tag text-decoration (underline/line-through) and link underlines inside the text run instead of leaving them as untagged content
- Map each marked-content MCID to the page it was emitted on, fixing orphaned MCIDs when an element's text wraps across a page break

Fonts:
- Add setHTMLMonospaceFont() and honor CSS font-family on <code>/<pre> so an embedded monospace font can replace the non-embedded standard-14 Courier

Examples E015/E016/E017 now validate as PDF/UA compliant; fix the E072 autoload path.
Add regression tests in test/HTMLTest.php.
Bump version to 8.65.0.

Author: nicolaasuni

VERSION

@@ -1 +1 @@
-8.64.1
+8.65.0

examples/E015_pdfua.php

@@ -37,6 +37,13 @@
 $pdf->setLanguage(code: 'en-US');
 
 $font = $pdf->font->insert($pdf->pon, 'dejavusans', '', 10);
+
+// PDF/UA requires every font to be embedded. <code>/<pre> default to the
+// non-embedded standard-14 Courier, so register an embedded monospace font and
+// select it for those elements.
+$pdf->font->insert($pdf->pon, 'dejavusansmono', '', 10);
+$pdf->setHTMLMonospaceFont('dejavusansmono');
+
 $pdf->addPage();
 $pdf->page->addContent($font['out']);
 

examples/E016_pdfua1.php

@@ -44,6 +44,13 @@
 $pdf->setLanguage(code: 'en-US');
 
 $font = $pdf->font->insert($pdf->pon, 'dejavusans', '', 10);
+
+// PDF/UA requires every font to be embedded. <code>/<pre> default to the
+// non-embedded standard-14 Courier, so register an embedded monospace font and
+// select it for those elements.
+$pdf->font->insert($pdf->pon, 'dejavusansmono', '', 10);
+$pdf->setHTMLMonospaceFont('dejavusansmono');
+
 $pdf->addPage();
 $pdf->page->addContent($font['out']);
 
@@ -117,7 +124,32 @@
     . ' <a href="https://github.com/tecnickcom/tc-lib-pdf" style="text-decoration:none;">hyperlink to the tc-lib-pdf repository</a>;'
     . ' the <code>a</code> element is tagged with the <strong>Link</strong> structure role'
     . ' automatically. PDF/UA-1 requires that link annotations have an accessible name,'
-    . ' which the library derives from the link text in the structure tree.</p>';
+    . ' which the library derives from the link text in the structure tree.</p>'
+    . '<h2>7 — Rules, Spans and Empty Cells</h2>'
+    . '<p>A horizontal rule carries no semantics, so it is emitted as an <strong>Artifact</strong>'
+    . ' rather than left as untagged content (PDF/UA-1 7.1):</p>'
+    . '<hr>'
+    . '<p>Cell <code>colspan</code>/<code>rowspan</code> are recorded on the cell structure'
+    . ' element as integer <strong>/ColSpan</strong> and <strong>/RowSpan</strong> attributes,'
+    . ' and an empty cell is kept in the tree so the row keeps its full column count (7.2):</p>'
+    . '<table border="1" cellspacing="0" cellpadding="3">'
+    . '<tr><th>Col A</th><th>Col B</th><th>Col C</th></tr>'
+    . '<tr><td colspan="2">Spans columns A and B</td><td>C</td></tr>'
+    . '<tr><td rowspan="2">Spans rows</td><td>B2</td><td>C2</td></tr>'
+    . '<tr><td>B3</td><td></td></tr>'
+    . '</table>';
+
+// A long table that breaks across pages: the repeated header on each continuation
+// page is an Artifact, while the single Table structure element keeps all its rows.
+$html .=
+    '<h2>8 — Page-Spanning Table</h2>'
+    . '<table border="1" cellspacing="0" cellpadding="2">'
+    . '<thead><tr><th>#</th><th>Description</th></tr></thead>';
+for ($row = 1; $row <= 60; ++$row) {
+    $html .= '<tr><td>' . $row . '</td><td>Continuation row ' . $row . '</td></tr>';
+}
+
+$html .= '</table>';
 
 $pdf->addHTMLCell(html: $html, posx: 15, posy: 20, width: 180);
 

examples/E017_pdfua2.php

@@ -42,6 +42,13 @@
 $pdf->setLanguage(code: 'en-US');
 
 $font = $pdf->font->insert($pdf->pon, 'dejavusans', '', 10);
+
+// PDF/UA requires every font to be embedded. <code>/<pre> default to the
+// non-embedded standard-14 Courier, so register an embedded monospace font and
+// select it for those elements.
+$pdf->font->insert($pdf->pon, 'dejavusansmono', '', 10);
+$pdf->setHTMLMonospaceFont('dejavusansmono');
+
 $pdf->addPage();
 $pdf->page->addContent($font['out']);
 

examples/E072_import_new_font.php

@@ -21,7 +21,7 @@
 
 // NOTE: run make deps fonts in the project root to generate the dependencies and example fonts.
 
-require '../vendor/autoload.php';
+require __DIR__ . '/../vendor/autoload.php';
 
 $defaultFontsDir = (string) \realpath(\dirname(__DIR__) . '/vendor/tecnickcom/tc-lib-pdf-font/target/fonts');
 $sourceFontsDir = \dirname(__DIR__) . '/target/fonts/source';

src/Base.php

@@ -126,6 +126,7 @@
  * @phpstan-type TPdfUaStructKid array{
  *    type: 'elem'|'mcid',
  *    id: int,
+ *    pid?: int,
  * }
  *
  * @phpstan-type TPdfUaStructElem array{
@@ -136,6 +137,7 @@
  *    alt?: string,
  *    annots?: int[],
  *    attr?: array<string, string>,
+ *    required?: bool,
  * }
  *
  * @phpstan-type TFileOptions array{
@@ -699,7 +701,7 @@ abstract class Base
     /**
      * TCPDF version.
      */
-    protected string $version = '8.64.1';
+    protected string $version = '8.65.0';
 
     /**
      * Encrypt object.

src/HTML.php

@@ -604,6 +604,16 @@ abstract class HTML extends \Com\Tecnick\Pdf\JavaScript
      */
     protected string $ullidot = '!';
 
+    /**
+     * Monospaced font applied to <pre>, <code> and <tt> elements when the author
+     * has not set an explicit font-family. Defaults to the standard-14 Courier;
+     * set an embedded font with setHTMLMonospaceFont() for PDF/UA output, which
+     * requires every font to be embedded.
+     *
+     * @var string
+     */
+    protected string $monospaceFontName = self::FONT_MONO;
+
     /**
      * Custom vertical spacing overrides for HTML block tags.
      * Structure: [ tagname => [ 0 => ['h' => float, 'n' => int], 1 => ['h' => float, 'n' => int] ] ]
@@ -6126,7 +6136,26 @@ protected function parseHTMLAttributesMonospace(array &$dom, int $key): void
         $node = &$dom[$key];
 
         if ($node['value'] === 'pre' || $node['value'] === 'tt' || $node['value'] === 'code') {
-            $node['fontname'] = self::FONT_MONO;
+            // Respect an explicit author font-family; otherwise apply the configured
+            // monospace font (Courier by default, or an embedded font for PDF/UA).
+            if (!isset($node['style']['font-family']) || $node['style']['font-family'] === '') {
+                $node['fontname'] = $this->monospaceFontName;
+            }
+        }
+    }
+
+    /**
+     * Set the monospaced font used for <pre>, <code> and <tt> elements.
+     *
+     * PDF/UA requires every font to be embedded. The default Courier is a
+     * non-embedded standard-14 font, so set an embedded monospace font (after
+     * inserting it with the font stack) when producing tagged or accessible PDFs.
+     */
+    public function setHTMLMonospaceFont(string $fontname): void
+    {
+        $fontname = \trim($fontname);
+        if ($fontname !== '') {
+            $this->monospaceFontName = $fontname;
         }
     }
 
@@ -7206,7 +7235,19 @@ protected function replayHTMLTableHead(
         }
 
         $theadh = $this->measureHTMLCellRenderedHeight($thead, $tpx, $tpy, $tpw, $tph);
-        $out = $this->getHTMLCell($thead, $tpx, $tpy, $tpw, $tph);
+
+        // The header is replayed visually at the top of each continuation page, but it
+        // is already represented once in the structure tree (on its first page). Suspend
+        // tagging during the replay so it does not open a second, nested Table subtree
+        // inside the still-open table, then emit the whole replayed header as an Artifact.
+        $savedPdfuaMode = $this->suspendPdfUaTagging();
+        try {
+            $rendered = $this->getHTMLCell($thead, $tpx, $tpy, $tpw, $tph);
+        } finally {
+            $this->resumePdfUaTagging($savedPdfuaMode);
+        }
+
+        $out = $this->tagPdfUaArtifactContent($rendered);
         if ($theadh > 0.0) {
             $tpy += $theadh;
             $this->resetHTMLLineCursor($hrc, $tpx, $tpw);
@@ -7359,9 +7400,17 @@ protected function measureHTMLCellRenderedHeight(
         $tph = $contenth;
 
         $this->initHTMLCellContext($hrc, $contentx, $contenty, $contentw, $contenth);
-        $this->renderHTMLCellFragments($hrc, $tpx, $tpy, $tpw, $tph, static function (string $fragment): void {
-            unset($fragment);
-        });
+        // Measurement renders into a discarded buffer, so suspend PDF/UA tagging:
+        // otherwise this pass appends phantom structure elements and advances the
+        // per-page MCID counter for content that is never written to a page stream.
+        $savedPdfuaMode = $this->suspendPdfUaTagging();
+        try {
+            $this->renderHTMLCellFragments($hrc, $tpx, $tpy, $tpw, $tph, static function (string $fragment): void {
+                unset($fragment);
+            });
+        } finally {
+            $this->resumePdfUaTagging($savedPdfuaMode);
+        }
 
         $this->clearHTMLCellContext($hrc);
         $this->restoreHTMLCallerFontState($callerfont);
@@ -11723,6 +11772,40 @@ protected function getHTMLStructRole(array $elm): string
         };
     }
 
+    /**
+     * Return a trimmed string HTML attribute from a DOM node, or '' when absent.
+     *
+     * @param array<string, mixed> $elm DOM element.
+     */
+    protected function getHTMLNodeStringAttr(array $elm, string $name): string
+    {
+        if (
+            !isset($elm['attribute'])
+            || !\is_array($elm['attribute'])
+            || !isset($elm['attribute'][$name])
+            || !\is_string($elm['attribute'][$name])
+        ) {
+            return '';
+        }
+
+        return \trim($elm['attribute'][$name]);
+    }
+
+    /**
+     * Map an HTML th/td scope attribute to a PDF table header Scope value.
+     * row/rowgroup map to Row; col/colgroup and any other value (including the
+     * absent default) map to Column.
+     *
+     * @param array<string, mixed> $elm DOM element.
+     */
+    protected function getHTMLCellScope(array $elm): string
+    {
+        return match (\strtolower($this->getHTMLNodeStringAttr($elm, 'scope'))) {
+            'row', 'rowgroup' => 'Row',
+            default => 'Column',
+        };
+    }
+
     /**
      * Return the PDF/UA ListNumbering value for a UL/OL element.
      *
@@ -17244,7 +17327,7 @@ protected function parseHTMLText(
             }
             $hrc['cellctx']['linewrapped'] = true;
 
-            return $background . $out . $inlineBorder;
+            return $this->tagPdfUaArtifactContent($background) . $out . $this->tagPdfUaArtifactContent($inlineBorder);
         }
 
         $tpx = $this->computeHTMLTextAdvanceX(
@@ -17269,7 +17352,7 @@ protected function parseHTMLText(
         }
         $hrc['cellctx']['linewrapped'] = false;
 
-        return $background . $out . $inlineBorder;
+        return $this->tagPdfUaArtifactContent($background) . $out . $this->tagPdfUaArtifactContent($inlineBorder);
     }
 
     // FUNCTIONS TO PROCESS HTML OPENING TAGS
@@ -17993,14 +18076,17 @@ protected function parseHTMLTagOPENhr(
         }
 
         $lineY = $tpy + ($this->getHTMLLineAdvance($hrc, $key) / 2);
-        $out .= $this->graph->getLine($tpx, $lineY, $tpx + $width, $lineY, [
+        // A horizontal rule carries no semantics, so in PDF/UA mode its stroke is wrapped
+        // as an Artifact (tagPdfUaArtifactContent is a no-op outside PDF/UA mode). Without
+        // this the rule would be untagged real content, violating PDF/UA-1 7.1.
+        $out .= $this->tagPdfUaArtifactContent($this->graph->getLine($tpx, $lineY, $tpx + $width, $lineY, [
             'lineWidth' => $strokeWidth,
             'lineCap' => 'butt',
             'lineJoin' => 'miter',
             'dashArray' => [],
             'dashPhase' => 0,
             'lineColor' => $elm['fgcolor'] === '' ? 'black' : $elm['fgcolor'],
-        ]);
+        ]));
         $this->moveHTMLToNextLine($hrc, $key, $tpx, $tpy, $tpw);
 
         return $out;
@@ -19448,16 +19534,6 @@ protected function parseHTMLTagOPENtd(
             return '';
         }
 
-        if ($this->pdfuaMode !== '') {
-            $role = $elm['value'] === 'th' ? 'TH' : 'TD';
-            $attr = [];
-            if ($role === 'TH') {
-                $attr = ['O' => 'Table', 'Scope' => 'Column'];
-            }
-
-            $this->beginStructElem($role, $this->page->getPageId(), null, $attr);
-        }
-
         $table = $tableNode;
 
         $colindex = $this->getHTMLTableNextFreeColumn($table);
@@ -19483,6 +19559,45 @@ protected function parseHTMLTagOPENtd(
         $colspan = \max(1, \min($remaining, $colspan));
         $rowspan = \max(1, $rowspan);
 
+        if ($this->pdfuaMode !== '') {
+            $role = $elm['value'] === 'th' ? 'TH' : 'TD';
+            $attr = [];
+            if ($role === 'TH') {
+                // Honor an explicit scope; header cells default to column scope.
+                $attr = ['O' => 'Table', 'Scope' => $this->getHTMLCellScope($elm)];
+            }
+
+            // Record the cell spans on the structure element so assistive technology can
+            // reconstruct the table grid. The owner (/O /Table) is required for the span
+            // attributes; the serialiser writes ColSpan/RowSpan as integers.
+            if ($colspan > 1) {
+                $attr['O'] = 'Table';
+                $attr['ColSpan'] = (string) $colspan;
+            }
+
+            if ($rowspan > 1) {
+                $attr['O'] = 'Table';
+                $attr['RowSpan'] = (string) $rowspan;
+            }
+
+            // Pass through explicit header-association markup so complex tables can label
+            // header cells with an id and point data cells at them. The struct-tree
+            // serialiser promotes these to the StructElem /ID and /Headers entries.
+            $cellId = $this->getHTMLNodeStringAttr($elm, 'id');
+            if ($cellId !== '') {
+                $attr['ID'] = $cellId;
+            }
+
+            $cellHeaders = $this->getHTMLNodeStringAttr($elm, 'headers');
+            if ($cellHeaders !== '') {
+                $attr['Headers'] = $cellHeaders;
+            }
+
+            // Keep the cell in the structure tree even when empty so the row preserves
+            // its full column count and the table matrix stays regular.
+            $this->beginStructElem($role, $this->page->getPageId(), null, $attr, true);
+        }
+
         $cellx = $this->getHTMLTableColX($table, $colindex);
         $cellw = $this->getHTMLTableColSpanWidth($table, $colindex, $colspan);
         $rowtop = $table['rowtop'];

src/Output.php

@@ -1726,11 +1726,15 @@ protected function getOutStructTreeRoot(): string
                 }
 
                 $mcid = $kid['id'];
-                if ($entryPageOid > 0) {
-                    $parentTreeMap[$entryPageOid][$mcid] = $elemOids[$entryIdx] ?? 0;
+                // Each MCID belongs to the page it was emitted on, which may differ from
+                // the element's own page when the element's content wraps across a page
+                // break. Use the kid's page so the MCR /Pg and ParentTree key are correct.
+                $kidPageOid = $pidToOid[$kid['pid']] ?? $entryPageOid;
+                if ($kidPageOid > 0) {
+                    $parentTreeMap[$kidPageOid][$mcid] = $elemOids[$entryIdx] ?? 0;
                 }
 
-                $kidsOut .= ' << /Type /MCR /Pg ' . $entryPageOid . ' 0 R /MCID ' . $mcid . ' >>';
+                $kidsOut .= ' << /Type /MCR /Pg ' . $kidPageOid . ' 0 R /MCID ' . $mcid . ' >>';
             }
 
             if ($entry['annots'] !== []) {
@@ -1784,6 +1788,15 @@ protected function getOutStructTreeRoot(): string
                         continue;
                     }
 
+                    if ($akey === 'ColSpan' || $akey === 'RowSpan') {
+                        // Table span attributes are integers, not names (ISO 32000-1 table 348).
+                        if (\is_numeric($aval)) {
+                            $attrPairs .= ' /' . $akey . ' ' . (int) $aval;
+                        }
+
+                        continue;
+                    }
+
                     $attrPairs .= ' /' . $akey . ' /' . $aval;
                 }