feat(api): addTableOfContents(...) — native clickable table of contents

[DemchaAV]

Why

A table of contents had to be hand-assembled: a row per entry, a leader sized by hand, and a manual two-pass to resolve the page numbers. addTableOfContents(...) makes it native — and is the payoff of the table-of-contents groundwork (pageIndex() #231, line().fill() #234, columns() #235, addPageReference #236).

What changed

• addTableOfContents(toc -> toc.entry(label, anchor)) on every flow. Each entry becomes a row whose label links to the chapter (clickable), a dotted/dashed leader fills the gap, and the page number is resolved automatically from the laid-out document.
• TocBuilder configures the title, leader(DocumentLeader.{NONE,DOTS,DASHES}), leader color, and entry/page-number/title text styles. A blank entry label or anchor is rejected at the call site.
• No new engine code. Each row is assembled from the existing primitives — columns(auto(), weight(1), auto()), a line().fill() leader, and an addPageReference number; the numbers resolve through the already-merged page-reference two-pass.
• The entry rows are added to the surrounding flow (not wrapped in one block), so a long contents paginates across pages — a single Section/Container wrapper is atomic and would force the whole TOC onto one page.

Lane: canonical DSL (TocBuilder, addTableOfContents) + style (DocumentLeader). Purely additive → japicmp-safe; documents without a TOC are byte-identical.

Verification

• ./mvnw test -pl . — green, 0 visual baselines changed.
• TocTest: each entry prints its resolved page (PDFTextStripper), each label is a clickable go-to link to its anchor's page (PDActionGoTo destination == pageOf), and a 30-entry contents paginates across pages (builds without atomic-too-large, totalPages > 1). TocBuilderTest: blank label/anchor rejected.
• A cold review drove a fix (validate entry(...) at the call site instead of a late generic error).
• Runnable TocExample (a Contents page + five chapters) with a committed preview — labels auto-size, dotted leaders fill, page numbers resolve.

This closes the native table-of-contents gap: pageIndex → fill → columns → page reference → TOC.