diff --git a/CHANGELOG.md b/CHANGELOG.md index 62af1961..5c133ce8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -201,6 +201,26 @@ follow semantic versioning; release dates are ISO 8601. ### Documentation +- **One recipe catalogue instead of two.** The cookbook page and the folder index each + carried a hand-maintained table of all twenty-two recipe pages. They happened to agree + on which pages exist and disagreed on ten of the descriptions — the folder index named + PDF417 and DataMatrix among the barcode symbologies, the cookbook did not; the cookbook + was fuller on themes, transforms and page backgrounds. Merged into the page both the + README and the documentation index point at, taking the better description of each + pair, so nothing is lost. The folder file keeps the one job GitHub gives it — being + what you see when you open the directory — and now says where the catalogue is instead + of holding a copy that drifts. +- **Documents nobody could reach are reachable.** The archive index named its three + files in code spans rather than links, so the folder's own table of contents did not + actually lead anywhere, and one of the three was not listed at all. The two benchmark + notes sitting beside the committed baseline had no inbound link from anywhere; the + benchmark guide names them now, and says what they are — an April 2026 capture and the + before/after of the optimization round it belonged to, six weeks older than the + baseline file and unrelated to it. +- **The starting-point table has an answer for the ordinary document.** Its three rows + each asked a "yes" question — a known template family, pixel-level control, a re-usable + new type — and a reader generating an ordinary report from data matched none of them + and fell off the end. The DSL is the default, not the fallback, and the table says so. - **The example catalogue stops calling current code legacy.** Two examples sat under a heading reading "🗄️ Legacy — pre-rebuild examples kept for downstream callers still on V1; do not start new code here", pointing at a V1 → V2 migration guide. There is no diff --git a/docs/README.md b/docs/README.md index 7e952f5a..75840dc5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -79,7 +79,7 @@ Kept for anyone stepping through the 1.x line one minor at a time. Nothing here ### Recipes (cookbook-style howtos) -- **[recipes.md](recipes.md)** — index of all recipes (coverage map in [recipes/README.md](recipes/README.md)). +- **[recipes.md](recipes.md)** — the catalogue: every recipe page and what it covers. - **[recipes/charts.md](recipes/charts.md)** — native vector bar/line/area/pie charts. - **[recipes/keep-together.md](recipes/keep-together.md)** — blocks that never split at a page break. - **[recipes/shapes.md](recipes/shapes.md)** — cards, dividers, lines, ellipses, images. diff --git a/docs/archive/README.md b/docs/archive/README.md index b3da7048..8817d02a 100644 --- a/docs/archive/README.md +++ b/docs/archive/README.md @@ -22,5 +22,6 @@ The current docs live under [`docs/`](../) at the repository root: | File | Why archived | | --- | --- | -| `v1.2-roadmap.md` | Roadmap planning notes for the v1.2 release. Superseded by `CHANGELOG.md` for shipped features and by the Phase A–F execution plan for in-flight work. | -| `migration-v1-1-to-v1-2.md` | Migration guide from v1.1 to v1.2. Both versions are out of support; v1.4 → v1.5 callers should follow the migration doc at `docs/roadmaps/migration-v1-4-to-v1-5.md`. | +| [`v1.2-roadmap.md`](v1.2-roadmap.md) | Roadmap planning notes for the v1.2 release. Superseded by `CHANGELOG.md` for shipped features and by the Phase A–F execution plan for in-flight work. | +| [`migration-v1-1-to-v1-2.md`](migration-v1-1-to-v1-2.md) | Migration guide from v1.1 to v1.2. Both versions are out of support; v1.4 → v1.5 callers should follow the migration doc at `docs/roadmaps/migration-v1-4-to-v1-5.md`. | +| [`implementation-guide.md`](implementation-guide.md) | Implementation notes for an engine model 2.0 removed. The current route for adding a node, a handler or a backend is [`docs/contributing/extension-guide.md`](../contributing/extension-guide.md), with [`docs/architecture/package-map.md`](../architecture/package-map.md) for where things live. | diff --git a/docs/getting-started.md b/docs/getting-started.md index bccf89c4..6dc7801c 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -19,6 +19,7 @@ tree to choose the right one for the document you're rendering. | Is your document one of the template families (CV, cover letter, invoice, proposal)? | Yes | **Layered template preset.** Skip ahead to "Templates". | | Do you need pixel-level control over a one-off PDF? | Yes | **Raw DSL** (`DocumentSession.pageFlow(...)`). | | Do you need a re-usable scene for a *new* business document type? | Yes | **Custom template that wraps the DSL.** Implement `DocumentTemplate` and take a `BrandTheme` for visual coherence. | +| Anything else — a report, a statement, a brochure, one-off or generated from data | — | **Raw DSL.** This is the default answer, not a fallback: the DSL is the authoring surface, and templates are presets built on it. Continue with "Quick start" below. | The DSL and the templates compose against the SAME `DocumentSession` — a template can also live alongside hand-written DSL inside one diff --git a/docs/operations/benchmarks.md b/docs/operations/benchmarks.md index b8f184a8..b6f18c64 100644 --- a/docs/operations/benchmarks.md +++ b/docs/operations/benchmarks.md @@ -284,7 +284,9 @@ cleanest numbers. `baselines/current-speed-full.json` is a committed median `current-speed` report that `11-verdict-current-speed` judges new runs against (hard gate: average -latency ±10%; peak heap is advisory, GC-timing noisy). Refresh it **only** for an +latency ±10%; peak heap is advisory, GC-timing noisy). + +Refresh it **only** for an intended, verified improvement so the gate ratchets down — never to turn a red gate green. Capture a median of **≥5** runs on the branch that defines the new reference, with the IDE closed: @@ -312,8 +314,17 @@ java -cp "$cp" com.demcha.compose.BenchmarkMedianTool current-speed $runs cp -f target/benchmarks/aggregates/current-speed/full/latest.json baselines/current-speed-full.json ``` -The baseline is machine-class-specific; the JSON records provenance -(`timestamp`, `profile`, `sourceRuns`). Validate the refresh against a *fresh* +The baseline is machine-class-specific; the JSON records its own provenance +(`timestamp`, `profile`, `sourceRuns`) — read those rather than inferring where the +numbers came from. Two older notes share the folder and are **historical context +only**: [`baselines/BASELINE_SUMMARY.md`](../../baselines/BASELINE_SUMMARY.md) is a +smoke-profile capture from April 2026, taken before a round of engine optimization, +and [`baselines/COMPARISON.md`](../../baselines/COMPARISON.md) is that round's +before/after. Neither produced this baseline and neither tracks it: the JSON was first +cut six weeks later as a separate full-profile median when the verdict gate landed, and +has been re-measured independently since. + +Validate the refresh against a *fresh* run — not one of the five that built the median — on that branch; it should score NEUTRAL and exit `0`: diff --git a/docs/recipes.md b/docs/recipes.md index e66431a3..81700d01 100644 --- a/docs/recipes.md +++ b/docs/recipes.md @@ -16,19 +16,19 @@ authoring API; public application code should not import | [Shape-as-container](recipes/shape-as-container.md) | `addCircle` / `addEllipse` / `addContainer` with `ClipPolicy` (clipped layered children) | | [Transforms and z-index](recipes/transforms.md) | `rotate` / `scale` mixin, per-layer `zIndex` for overlays | | [Page backgrounds](recipes/page-backgrounds.md) | `pageBackground` / `pageBackgrounds`, `PageBackgroundFill` columns, bands, point-based fills, layering | -| [Layered page design](recipes/layered-page-design.md) | Choosing between page backgrounds, rows, layer stacks, and canvases | +| [Layered page design](recipes/layered-page-design.md) | Page background vs. row vs. layer stack vs. canvas — choosing the layer | | [Absolute placement](recipes/absolute-placement.md) | `addCanvas` + `position(x, y)` for pixel-precise certificates and badges | | [Tables](recipes/tables.md) | Row span, zebra rows, totals row, repeated header on page break | -| [Rich text](recipes/rich-text.md) | `RichText` mixed-style runs, inline links/images/shapes, SVG icons, emoji shortcodes, checkboxes | -| [Lists](recipes/lists.md) | `addList`, marker customisation, nested lists with per-depth markers | -| [Timelines](recipes/timelines.md) | `addTimeline`: markers on a connector rail, geometry and text-style controls | -| [Barcodes](recipes/barcodes.md) | QR / Code 128 / EAN / UPC and friends, tinting, quiet zone | -| [Images](recipes/images.md) | Sources, sizing precedence, fit modes, images in rows and cards | -| [PDF chrome](recipes/pdf-chrome.md) | Metadata, watermarks, running header/footer placeholders, protection, links, bookmarks | -| [In-PDF navigation](recipes/in-pdf-navigation.md) | Anchors + internal `linkTo` links: clickable contents, heading jumps, bidirectional footnotes, inline-graphic links | -| [Translucency](recipes/translucency.md) | `DocumentColor.rgba` / `withOpacity`, alpha coverage, layered tints | -| [DOCX export](recipes/docx-export.md) | Semantic export, node mapping, fallbacks and skipped kinds | -| [Snapshot testing](recipes/snapshot-testing.md) | Layout-snapshot regression testing in consumer projects | +| [Rich text](recipes/rich-text.md) | `RichText` mixed-style runs in one paragraph: bold/accent/styled segments, inline links, inline images, inline SVG icons, emoji shortcodes, inline shapes and checkboxes | +| [Lists](recipes/lists.md) | `addList`: quick bulleted lists, marker customisation, nested lists with per-depth markers, spacing and styled items | +| [Timelines](recipes/timelines.md) | `addTimeline`: markers (dot / circle / numbered / square) on a connector rail, geometry and text-style controls, pagination opt-ins | +| [Barcodes](recipes/barcodes.md) | QR / Code 128 / Code 39 / EAN / UPC / PDF417 / DataMatrix, tinting, quiet zone, card centring | +| [Images](recipes/images.md) | Sources (bytes/path), sizing precedence, STRETCH/CONTAIN/COVER fit modes, images in rows and cards | +| [PDF chrome](recipes/pdf-chrome.md) | Metadata, watermarks, running header/footer with `{page}/{pages}/{date}`, protection, links and outline bookmarks | +| [In-PDF navigation](recipes/in-pdf-navigation.md) | Named `anchor(...)` destinations + internal `linkTo(...)` links: clickable tables of contents, `#heading`-style jumps, bidirectional footnotes, inline-graphic links — native PDF GoTo actions | +| [Translucency](recipes/translucency.md) | `DocumentColor.rgba` / `withOpacity`: which primitives honour alpha, byte-identity for opaque colours, layered tints | +| [DOCX export](recipes/docx-export.md) | Semantic DOCX export: 1:1 node mapping, chart/shape-container fallbacks, skipped kinds | +| [Snapshot testing](recipes/snapshot-testing.md) | Layout-snapshot regression testing in consumer projects, baseline update flow | | [Streaming and output](recipes/streaming.md) | `buildPdf` / `writePdf` / `toPdfBytes`, DOCX export, layout snapshots, header / footer chrome, guide lines | | [Extending GraphCompose](recipes/extending.md) | New semantic node, fluent setter, render backend, snapshot-based regression tests | diff --git a/docs/recipes/README.md b/docs/recipes/README.md index a16f1d68..f3055321 100644 --- a/docs/recipes/README.md +++ b/docs/recipes/README.md @@ -1,34 +1,10 @@ # Recipes -Task-oriented guides: each page shows how to use one slice of the canonical -API, with copy-pasteable snippets verified against the current release. - -## Available recipes - -| Recipe | Covers | -|---|---| -| [charts.md](charts.md) | Native vector bar / line / area / pie-donut charts: data–spec–style layers, axis & grid toggles, point markers, value-label halos, legend placement, translucent area fills | -| [rich-text.md](rich-text.md) | `RichText` mixed-style runs in one paragraph: bold/accent/styled segments, inline links, inline images, inline SVG icons, emoji shortcodes, inline shapes and checkboxes | -| [lists.md](lists.md) | `addList`: quick bulleted lists, marker customisation, nested lists with per-depth markers, spacing and styled items | -| [timelines.md](timelines.md) | `addTimeline`: markers (dot / circle / numbered / square) on a connector rail, geometry and text-style controls, pagination opt-ins | -| [keep-together.md](keep-together.md) | `keepTogether()` / `keepEntriesTogether()` — blocks that relocate whole instead of orphaning a heading at a page break | -| [shapes.md](shapes.md) | Filled cards, dividers, accent bars, lines, spacers, ellipses, images | -| [shape-as-container.md](shape-as-container.md) | Circles/ellipses/rounded cards holding clipped children, `ClipPolicy` | -| [absolute-placement.md](absolute-placement.md) | `CanvasLayerNode` — children at explicit (x, y) | -| [layered-page-design.md](layered-page-design.md) | Page background vs. row vs. layer stack vs. canvas — choosing the layer | -| [page-backgrounds.md](page-backgrounds.md) | Per-page fills: sidebars, bands, layered tints | -| [transforms.md](transforms.md) | Rotation, scaling, skewing | -| [tables.md](tables.md) | Tabular layouts: columns, headers, zebra rows, composed cells | -| [themes.md](themes.md) | `BrandTheme` factories and custom token bundles | -| [barcodes.md](barcodes.md) | QR / Code 128 / Code 39 / EAN / UPC / PDF417 / DataMatrix, tinting, quiet zone, card centring | -| [images.md](images.md) | Sources (bytes/path), sizing precedence, STRETCH/CONTAIN/COVER fit modes, images in rows and cards | -| [pdf-chrome.md](pdf-chrome.md) | Metadata, watermarks, running header/footer with `{page}/{pages}/{date}`, protection, links and outline bookmarks | -| [in-pdf-navigation.md](in-pdf-navigation.md) | Named `anchor(...)` destinations + internal `linkTo(...)` links: clickable tables of contents, `#heading`-style jumps, bidirectional footnotes, inline-graphic links — native PDF GoTo actions | -| [translucency.md](translucency.md) | `DocumentColor.rgba` / `withOpacity`: which primitives honour alpha, byte-identity for opaque colours, layered tints | -| [docx-export.md](docx-export.md) | Semantic DOCX export: 1:1 node mapping, chart/shape-container fallbacks, skipped kinds | -| [snapshot-testing.md](snapshot-testing.md) | Layout-snapshot regression testing in consumer projects, baseline update flow | -| [streaming.md](streaming.md) | Streaming PDFs to HTTP responses | -| [extending.md](extending.md) | Extension patterns: custom nodes via the `NodeDefinition` SPI | - -Every shipped feature now has a recipe; the runnable -[examples](../../examples/README.md) remain the end-to-end references. +Task-oriented guides: each page shows how to use one slice of the canonical API, with +copy-pasteable snippets verified against the current release. + +The catalogue — every page in this folder and what it covers — lives one level up, in +**[`docs/recipes.md`](../recipes.md)**. That is the page the root README and the +documentation index point at, so it is the one kept current; this file used to carry a +second copy of the same table, and two hand-maintained copies of one list only ever +agree until they don't.