DemchaAV · DemchaAV · Jun 28, 2026 · Jun 28, 2026
@@ -19,7 +19,7 @@
 </p>
 
 > **Release status** &mdash;
-> 🟢 **Latest stable**: [v1.8.0](https://github.com/DemchaAV/GraphCompose/releases/tag/v1.8.0) &mdash; codenamed **"illustrative"**: native vector charts, SVG &amp; gradient graphics, free-form clipping, and a leaner engine artifact. **[What's new in v1.8 &darr;](#whats-new-in-v18)**
+> 🟢 **Latest stable**: [v1.9.0](https://github.com/DemchaAV/GraphCompose/releases/tag/v1.9.0) &mdash; codenamed **"navigable"**: in-document navigation (anchors, internal links, a clickable TOC, page references &amp; bookmarks), multi-section documents, and inline chips / SVG icons / colour emoji. **[What's new in v1.9 &darr;](#whats-new-in-v19)**
 
 > &nbsp;·&nbsp; 🟡 **In develop**: next cycle — open (see [CHANGELOG](./CHANGELOG.md))
 > &nbsp;·&nbsp; See [API stability policy](./docs/api-stability.md) for tier definitions.
@@ -51,22 +51,19 @@
 
 Sits between **iText** (low-level page primitives) and **JasperReports** (XML-template-driven layout): a Java DSL describes the document semantically, the engine renders.
 
-## What's new in v1.8
+## What's new in v1.9
 
-The **"illustrative"** release &mdash; the engine gains a vector-graphics dimension.
+The **"navigable"** release &mdash; a rendered PDF becomes a document you can move through.
 
-<p align="center">
-  <img src="./assets/readme/chart-showcase.png" alt="GraphCompose native vector charts" width="720"/>
-</p>
-
-- **Native vector charts** &mdash; bar / line / pie, inline sparklines, and `MONOTONE` / `SMOOTH` line interpolation, drawn as native PDF Béziers (no rasterization): `section.chart(ChartSpec.line()&hellip;, style)`.
-- **SVG path &amp; icon import** &mdash; `SvgIcon.parse(svg)` turns SVG into native vector geometry; recolour per use and place with `addSvgIcon(icon, width, align)`.
-- **Gradients &amp; free-form clipping** &mdash; linear / radial `DocumentPaint` fills and arbitrary `ShapeOutline.Path` clip regions.
-- **Block-level alignment** &mdash; `addAligned(HorizontalAlign.CENTER, node)` centres or right-aligns any fixed node without a wrapper container.
-- **`keepTogether()` pagination** &mdash; keep a section from splitting across a page break.
-- **Leaner publication** &mdash; the bundled Google fonts moved to the independently-versioned `graph-compose-fonts` artifact, so the engine jar dropped from ~20&nbsp;MB to ~2&nbsp;MB. Pure-text / standard-14 documents need nothing extra; add `graph-compose-fonts` (or `graph-compose-bundle`) to keep the bundled families &mdash; see the [migration note](./docs/migration/v1.8.0-fonts.md).
+- **In-document navigation** &mdash; named `anchor(...)` targets and internal `link(...)` jumps emitted as native PDF `GoTo` actions: clickable cross-references, `[text](#heading)`-style links, and bidirectional footnotes (`DocumentLinkTarget` unifies internal and external links).
+- **Native table of contents &amp; page references** &mdash; `addTableOfContents(toc -> toc.entry(label, anchor))` builds a clickable TOC with dot leaders and auto-resolved page numbers; `addPageReference(anchor)` prints a native "see page N" cross-reference; `DocumentSession.pageIndex()` resolves any anchor to its page.
+- **Bookmarks &amp; viewer preferences** &mdash; `section.bookmark(...)` makes any section or container a PDF outline (bookmark-panel) target, and `chrome().viewerPreferences(...)` opens the reader on the outline panel, a chosen page layout, or the doc title in the window.
+- **Multi-section documents** &mdash; `GraphCompose.documents()` concatenates independently authored sections &mdash; each with its own page size, margins, and footer numbering &mdash; into one PDF, with anchors, links, and the outline resolving across section boundaries.
+- **Richer row &amp; page layout** &mdash; `row.columns(auto(), weight(1), fixed(80))`, main-axis `flexSpacer()` / `arrangement(...)`, cross-axis `verticalAlign(...)`, per-page `pageMargins(...)`, and full-bleed `bleed(...)`.
+- **Inline chips, SVG icons &amp; colour emoji** &mdash; text on a rounded highlight chip, a parsed `SvgIcon` on the text baseline, and `RichText.emoji(":star:", size)` colour emoji via the new independently-versioned `graph-compose-emoji` module.
+- **Render straight to images** &mdash; `DocumentSession` renders directly to `BufferedImage`s with no PDF round-trip; plus page-number offset / restart / style and round / dotted line caps.
 
-Core document APIs stay source- and binary-compatible with v1.7 (`ConfigLoader` is the one removal). Full notes in [`CHANGELOG.md`](./CHANGELOG.md).
+Core document APIs stay source- and binary-compatible with v1.8 &mdash; v1.9 is purely additive (two cover-letter / CV shim types are newly `@Deprecated` for 2.0). Full notes in [`CHANGELOG.md`](./CHANGELOG.md).
 
 ## Installation
 

@@ -54,6 +54,8 @@ back here.
 
 ### Roadmaps & migrations
 - **[roadmaps/v1.6-roadmap.md](roadmaps/v1.6-roadmap.md)** — current development roadmap.
+- **[roadmaps/migration-v1-8-to-v1-9.md](roadmaps/migration-v1-8-to-v1-9.md)** — upgrade guide for v1.8 → v1.9.
+- **[roadmaps/migration-v1-7-to-v1-8.md](roadmaps/migration-v1-7-to-v1-8.md)** — upgrade guide for v1.7 → v1.8.
 - **[roadmaps/migration-v1-6-to-v1-7.md](roadmaps/migration-v1-6-to-v1-7.md)** — upgrade guide for v1.6 → v1.7.
 - **[roadmaps/migration-v1-5-to-v1-6.md](roadmaps/migration-v1-5-to-v1-6.md)** — upgrade guide for v1.5 → v1.6.
 - **[roadmaps/migration-v1-4-to-v1-5.md](roadmaps/migration-v1-4-to-v1-5.md)** — upgrade guide for v1.4 → v1.5.

@@ -0,0 +1,84 @@
+# Migration: v1.8 → v1.9
+
+v1.9 — codenamed **"navigable"** — is **additive only**. Every public
+type, method, and behaviour from v1.8 is unchanged: bump the dependency
+to `1.9.0` and rebuild with **no source changes required**. Adding public
+API is what turns the open cycle into a minor release.
+
+The theme of the release is **in-document navigation** — a rendered PDF
+stops being a flat sequence of pages and becomes a document you can move
+through: named anchors, internal links, a native clickable table of
+contents, "see page N" cross-references, and a bookmark outline, all
+emitted as native PDF `GoTo` actions and resolved in a single authoring
+pass.
+
+If your application targets v1.8 today, there is nothing to do but
+upgrade. The rest of this guide is a tour of what you can now reach for.
+
+## TL;DR
+
+Everything below is `@since 1.9.0` and purely additive — no v1.8 API is
+replaced or removed.
+
+| Area | v1.9 addition | Reach for it when |
+| --- | --- | --- |
+| **In-PDF navigation** | `anchor(...)` targets + internal `link(...)`; sealed `DocumentLinkTarget` (`InternalLinkTarget` / `ExternalLinkTarget`) | clickable cross-references and `[text](#heading)`-style jumps emitted as native PDF `GoTo` actions |
+| **Table of contents** | `addTableOfContents(toc -> toc.entry(label, anchor))` + `TocBuilder` / `DocumentLeader` | a native clickable TOC with dot leaders and auto-resolved page numbers |
+| **Page references** | `addPageReference(anchor)` + `PageReferenceNode`; `DocumentSession.pageIndex()` → `PageIndex` / `PageReference` | a "see page N" cross-reference, or resolving any anchor to its page from code |
+| **Bookmarks & viewer prefs** | container `bookmark(DocumentBookmarkOptions)`; `chrome().viewerPreferences(...)` + `DocumentViewerPreferences` / `DocumentPageMode` / `DocumentPageLayout` | a PDF outline (bookmark panel), and controlling how a reader opens the document |
+| **Multi-section documents** | `GraphCompose.documents()` + `MultiSectionDocumentBuilder` / `MultiSectionDocument` | concatenating independently authored sections (own page size / margins / numbering) into one PDF, with links resolving across sections |
+| **Per-page margins & bleed** | `pageMargins(List<PageMarginRule>)`; `bleed(...)` + `DocumentBleed` / `DocumentEdge` | mixing a full-bleed cover with book-margin body pages, or running content to the trimmed page edge |
+| **Row layout** | `row.columns(auto() / weight() / fixed())` + `DocumentRowColumn`; `flexSpacer()` / `pushRight()` / `arrangement(...)` + `RowArrangement`; `verticalAlign(...)` + `RowVerticalAlign` | column tracks, main-axis justify (push a badge flush right), and cross-axis seating within a row |
+| **Inline chips / SVG / emoji** | inline highlight chips, inline `SvgIcon` runs, `RichText.emoji(":star:", size)` via the new `graph-compose-emoji` module | a code/badge chip, an icon on the text baseline, or colour emoji by shortcode |
+| **Page numbering** | `DocumentPageNumbering` / `DocumentPageNumberStyle` | page-number offset / restart / numeral style in headers and footers |
+| **Lines** | `LineBuilder.fill()`; `LineBuilder.lineCap(DocumentLineCap)` | a line that stretches to its slot (dot leaders), and round / square caps or dotted strokes |
+| **Render to images** | render a `DocumentSession` straight to `BufferedImage` | a raster preview / thumbnail with no PDF round-trip |
+
+Runnable code for each lives in the
+[examples gallery](../../examples/README.md); the exact public-API list
+is in [`CHANGELOG.md`](../../CHANGELOG.md) under **v1.9.0**.
+
+## One behaviour to know about
+
+- **A negative page margin is now rejected; a negative bottom *content*
+  margin is honoured.** A negative `margin(...)` on the page fails fast at
+  construction instead of silently mis-laying-out the page, while an
+  intentional negative bottom margin on a block now pulls the following
+  content up as written. This only affects code that passed a negative
+  *page* margin — pass a non-negative one.
+
+## Things that did NOT break
+
+- Every entry point on `GraphCompose`, the full `DocumentSession`
+  authoring lifecycle (`compose`, `pageFlow`, add, `buildPdf`, export,
+  close, `layoutGraph`, `layoutSnapshot`).
+- `DocumentDsl`, `BusinessTheme`, `DocumentPalette`, and the invoice /
+  proposal / CV / cover-letter / weekly-schedule template entry points
+  (V1 and V2).
+- The fixed-layout and semantic backend SPIs and every public render
+  handler.
+- Layout snapshots and visual-regression baselines — navigation markers
+  are non-visual, so a document that adds no anchors, links, or bookmarks
+  renders byte-for-byte as before.
+
+> **Deprecations (informational, not breaking).**
+> `templates.api.CoverLetterTemplate` and the `cv.v2.components`
+> `HeadlineRenderer` / `ContactRenderer` / `BannerRenderer` shims are now
+> `@Deprecated(forRemoval = true, since = "1.9.0")` — superseded by the
+> generic `DocumentTemplate` seam and the `cv.v2.widgets` widgets
+> respectively. They still compile and behave exactly as before in 1.x;
+> they are slated for removal in 2.0. See
+> [`docs/api-stability.md`](../api-stability.md) §3 for the ledger.
+
+## Upgrading
+
+```xml
+<dependency>
+    <groupId>io.github.demchaav</groupId>
+    <artifactId>graph-compose</artifactId>
+    <version>1.9.0</version>
+</dependency>
+```
+
+That is the entire migration. Pull in any of the primitives above as you
+need them.