gedcom-ts 2026.5.1 → 2026.5.3

package/CHANGELOG.md

@@ -2,7 +2,33 @@
 
 All notable changes of gedcom-ts
 
-## [Unreleased]
+## [2026.5.3] - 2026-05-16
+
+### Added
+
+- **Module `gedcom-ts/booklet`** : génération de livrets généalogiques en PDF (collecte des personnes, récits en français, frises chronologiques, estimation de taille, `generateGenealogyBookletPdf`, `downloadBookletPdf`). Dépendance `pdf-lib` incluse dans ce sous-paquet.
+- **Logo couverture** : chemins SVG `GEDCOM_TS_LOGO_PATHS` / `GEDCOM_TS_LOGO_VIEWBOX` et `drawGedcomTsLogoOnPage` exportés ; logo gedcom-ts sur la couverture par défaut (`coverLogo` dans `BookletPdfOptions`).
+- **Tests** : `tests/booklet/` (date/lieu/genre, logo, PDF smoke).
+- **README** : guide `gedcom-ts/booklet`, double point d’entrée npm.
+
+### Changed
+
+- **`findHarmonizationClustersFromActs`** : si plusieurs libellés similaires partagent une seule position GPS et que tous les actes ont des coordonnées, unifie automatiquement le libellé (libellé le plus long) sans cluster d’harmonisation manuel.
+- Critère d’harmonisation : ne signale plus les seules variantes d’orthographe lorsque les coordonnées sont déjà identiques.
+
+## [2026.5.2] - 2026-05-16
+
+### Added
+
+- **Regroupement des lieux** : `groupActsBySimilarCity`, `actsNeedingGeocodeForCity` (alias géoloc), `similarCityKey` ; harmonisation et carte alignées sur `citiesAreSimilar` (plus de divergence `normalizeCityKey` seul).
+
+### Changed
+
+- **`findHarmonizationClustersFromActs`** : union-find sur `citiesAreSimilar` (corrige le cas Pleurtuit 29+11 actes après géoloc complète).
+- **`clusterKeyForCity`** : clé carte basée sur la localité principale (segment avant la virgule), alignée avec le regroupement par similarité.
+- **README** : guide d’intégration géoloc restructuré (section dédiée, tableaux par cas d’usage) ; retrait de la documentation développement interne.
+
+## [2026.5.1] - 2026-05-15
 
 ### Added
 
@@ -101,7 +127,7 @@ Les entrées historiques du changelog conservent leurs numéros semver d’origi
 
 - Major GEDCOM 7 coverage push: round-trip preservation (`preservedTopLevelRecords`, label-keyed FAM / NOTE xrefs, level-0 `OBJE`), richer `HEAD` export options, full P1.4 dates and places (INT/EST/CAL, `3 PHRASE`, `3 TIME`, `2 SDATE`, `2 PHRASE` event-level, ISO date input, verbatim fallback).
 - New **fluent edit layer** (`editPerson`, `editAct`, `editActs`, `editDateAct`, `editPlace`, `editNotes` + `*Edit` classes) for in-place model mutations with chainable APIs.
-- **README fully rewritten** with a complete public-API reference and a link to the live graphical demo at **[https://gedcomts.jaunet.me](https://gedcomts.jaunet.me)**.
+- **README fully rewritten** with a complete public-API reference and a link to the live graphical demo at **[https://gedcomts.com](https://gedcomts.com)**.
 
 ### Added
 
@@ -162,7 +188,7 @@ Les entrées historiques du changelog conservent leurs numéros semver d’origi
 #### Documentation
 
 - **README intégralement réécrit** : référence complète de l’API publique (un sous-titre par export de `src/index.ts`), tables synthétiques pour `ReadGed`, `GedcomExportOptions` et la couche `*Edit`, exemples mis à jour pour chaque type / classe / fonction exposés.
-- Mention en tête du README du **site de démo graphique** : **[https://gedcomts.jaunet.me](https://gedcomts.jaunet.me)**.
+- Mention en tête du README du **site de démo graphique** : **[https://gedcomts.com](https://gedcomts.com)**.
 
 ### Changed
 

package/README.md

@@ -6,16 +6,29 @@
 - work with a typed JSON model (persons, acts, dates, places, notes, media, name variants, attributes)
 - edit the model in-place through a fluent, chainable API (`editPerson`, `editAct`, …)
 - export data back to GEDCOM (`.ged`) or GEDZIP (`.zip`)
+- geocode event places (OpenStreetMap / Nominatim) and group similar city names
+- generate a **genealogy booklet** as PDF (`gedcom-ts/booklet`, French narratives)
 
 ## Live demo
 
-A graphical demo showcasing the public API (import a `.ged` / `.zip`, browse the typed model, export back) is available at **[https://gedcomts.jaunet.me](https://gedcomts.jaunet.me)**
+A graphical demo showcasing the public API (import a `.ged` / `.zip`, browse the typed model, export back) is available at **[https://gedcomts.com](https://gedcomts.com)**
 
-## Project
+## Contents
 
-- NPM package: [gedcom-ts](https://www.npmjs.com/package/gedcom-ts)
-- **Versioning (CalVer)** : releases use **`AAAA.M.micro`** (e.g. `2026.5.0` = May 2026). The npm `version`, `GEDCOM_LIBRARY_VERSION` (export `HEAD`.`SOUR`.`VERS`), and release branches share the same label. Older changelog entries still refer to semver (`2.1.0`, …). See [CHANGELOG.md](CHANGELOG.md).
-- **GEDCOM 7 roadmap** (spec gedcom.io, coverage matrix, prioritized gaps): [docs/GEDCOM7-roadmap.md](docs/GEDCOM7-roadmap.md)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Geocoding places](#geocoding-places)
+- [Genealogy booklet (PDF)](#genealogy-booklet-pdf)
+- [API reference](#api-reference)
+- [Error handling](#error-handling)
+
+## Package
+
+- NPM: [gedcom-ts](https://www.npmjs.com/package/gedcom-ts)
+- Version format **CalVer** `AAAA.M.micro` (e.g. `2026.5.3` = May 2026). See [CHANGELOG.md](CHANGELOG.md).
+- Entry points:
+  - **`gedcom-ts`** — import, model, edit layer, export, geocoding
+  - **`gedcom-ts/booklet`** — PDF livret (`pdf-lib` bundled in that chunk)
 
 ## Installation
 
@@ -23,6 +36,8 @@ A graphical demo showcasing the public API (import a `.ged` / `.zip`, browse the
 npm install gedcom-ts
 ```
 
+Both entry points come from the same package; no extra install for the booklet.
+
 ## Runtime Requirements
 
 - modern browser runtime (`File`, `Blob`, `XMLHttpRequest`, `URL.createObjectURL`)
@@ -51,9 +66,243 @@ Typical workflow:
 2. read / mutate the typed `Person`, `Act`, `Place`, `Note`, `MultimediaFile` objects (directly or through `editPerson` / `editAct` / `editPlace` / …)
 3. export as `.ged` (`ExportGedcomFile`) or `.zip` (`ExportGedzipFile`)
 
-## Public API reference
+## Geocoding places
+
+Use this section when your app needs **GPS coordinates** on event places, a **list of cities still without coordinates**, **map markers**, or a **data-quality** view for inconsistent place names.
+
+You work with a `ReadGed` (after import) and a flat `Act[]` built from every person’s events (see [Prepare act list](#prepare-act-list)).
+
+### How city names are matched
+
+The library groups variants of the same place with **`citiesAreSimilar`**, not exact string equality.
+
+
+| Label A     | Label B                              | Same place?                 |
+| ----------- | ------------------------------------ | --------------------------- |
+| `Pleurtuit` | `Pleurtuit, Ille-et-Vilaine, France` | Yes                         |
+| `Paris`     | `Paris, TX, USA`                     | Depends on similarity rules |
+
+
+Use the functions in the tables below for grouping, geocoding, and maps. Do **not** compare raw strings yourself, and do **not** use `normalizeCityKey` for grouping (spelling normalization only).
+
+### Prepare act list
+
+```ts
+import type { ReadGed, Act } from "gedcom-ts";
+
+function collectAllActs(ged: ReadGed): Act[] {
+  const acts: Act[] = [];
+  for (const person of ged.persons) {
+    for (const act of person.acts.list) acts.push(act);
+  }
+  return acts;
+}
+```
+
+### Geocode one city (typical flow)
+
+When the user picks a city and a Nominatim result, update **every similar act that still has no GPS** — not only acts with the exact same label.
+
+
+| Step                                           | Function                                                    |
+| ---------------------------------------------- | ----------------------------------------------------------- |
+| 1. Context from the tree (countries, centroid) | `inferGeocodeContext(ged)`                                  |
+| 2. Search OpenStreetMap                        | `searchPlacesWithContext(cityName, context)`                |
+| 3. Acts to update                              | `actsNeedingGeocodeForCity(allActs, cityName)`              |
+| 4. Write coordinates                           | `applyGeocodeCandidateToActs(targets, candidate, cityName)` |
+
+
+```ts
+import {
+  inferGeocodeContext,
+  searchPlacesWithContext,
+  actsNeedingGeocodeForCity,
+  applyGeocodeCandidateToActs,
+} from "gedcom-ts";
+import type { ReadGed, Act } from "gedcom-ts";
+
+async function geocodeCity(ged: ReadGed, allActs: Act[], cityName: string) {
+  const context = inferGeocodeContext(ged);
+  const candidates = await searchPlacesWithContext(cityName, context);
+  const chosen = candidates[0];
+  if (!chosen) return;
+
+  const targets = actsNeedingGeocodeForCity(allActs, cityName);
+  applyGeocodeCandidateToActs(targets, chosen, cityName);
+}
+```
+
+> **Tip:** Do not pass only acts from a harmonization cluster to `applyGeocodeCandidateToActs`. Longer labels (e.g. `Pleurtuit, Ille-et-Vilaine, France`) would stay without GPS. Always use `actsNeedingGeocodeForCity`.
+
+### List cities missing coordinates
+
+One row per city; `withoutCoordCount` is how many acts still need GPS.
+
+```ts
+import { groupActsBySimilarCity } from "gedcom-ts";
+
+const groups = groupActsBySimilarCity(allActs, { onlyWithoutCoordinates: true });
+
+for (const group of groups) {
+  console.log(group.cityLabel, group.withoutCoordCount);
+  // group.acts — acts in this group without GPS
+}
+```
+
+Largest groups first (`group.acts.length`).
+
+### Map: one marker per city
+
+```ts
+import { clusterKeyForCity } from "gedcom-ts";
+
+const markerKey = clusterKeyForCity(act.place?.city ?? "");
+// merge markers that share the same markerKey
+```
+
+### Harmonization (data quality, optional)
+
+Use when spellings, GPS positions, or “some acts with / without GPS” disagree for the same similar city.
+
+```ts
+import { findHarmonizationClusters } from "gedcom-ts";
+
+for (const cluster of findHarmonizationClusters(ged)) {
+  console.log(cluster.labels, cluster.coordVariants, cluster.actsWithoutCoord);
+}
+```
+
+After a full geocode via `actsNeedingGeocodeForCity`, you should not get a cluster that only reports missing GPS for that city.
+
+### Geocoding API cheat sheet
+
+
+| Goal                      | Call                                                             |
+| ------------------------- | ---------------------------------------------------------------- |
+| Search                    | `searchPlacesWithContext(city, inferGeocodeContext(ged))`        |
+| Acts to update on confirm | `actsNeedingGeocodeForCity(acts, city)`                          |
+| Apply lat/lng             | `applyGeocodeCandidateToActs(targets, candidate, city)`          |
+| Cities without GPS        | `groupActsBySimilarCity(acts, { onlyWithoutCoordinates: true })` |
+| Map marker id             | `clusterKeyForCity(city)`                                        |
+| Inconsistencies           | `findHarmonizationClusters(ged)`                                 |
+
+
+Network: `GET https://nominatim.openstreetmap.org/search?q=…&format=jsonv2` with a `User-Agent` (`gedcom-ts/<version> (genealogy library)`). For offline or mocked search, pass `fetchFn` in `searchPlaces` / `searchPlacesWithContext` options.
+
+The legacy callback `getCityCoordinates` is deprecated — use the flow above.
+
+## Genealogy booklet (PDF)
+
+The **`gedcom-ts/booklet`** subpath builds a printable family booklet: cover page, table of contents, chapters by generation (Sosa), family sheets, and French narrative text from GEDCOM acts (birth, marriage, death, …). Optional generation timelines are rasterized for PDF.
+
+### Workflow
+
+1. Import with `importGedFile` (`gedcom-ts`).
+2. Collect persons with `collectBookletPersons` (`gedcom-ts/booklet`).
+3. Optionally preview size with `estimateBookletSize` + `groupBookletIntoChapters`.
+4. Build bytes with `generateGenealogyBookletPdf`, then `downloadBookletPdf` (browser).
+
+```ts
+import { importGedFile } from "gedcom-ts";
+import {
+  collectBookletPersons,
+  groupBookletIntoChapters,
+  estimateBookletSize,
+  generateGenealogyBookletPdf,
+  downloadBookletPdf,
+  personDisplayName,
+} from "gedcom-ts/booklet";
+
+async function exportBooklet(file: File) {
+  const ged = await importGedFile(file);
+  const root = ged.persons[0] ?? null;
+
+  const entries = collectBookletPersons({
+    ged,
+    scope: "from-reference",
+    referencePerson: root,
+    maxGeneration: 6,
+  });
+
+  const chapters = groupBookletIntoChapters(entries);
+  const families = chapters.reduce((n, ch) => n + ch.families.length, 0);
+  const size = estimateBookletSize(chapters, entries.length, families, "summary", "canvas");
+  console.log(size.label);
+
+  const pdf = await generateGenealogyBookletPdf(
+    entries,
+    {
+      title: "Livret familial",
+      scopeLabel: "Ancêtres et descendance",
+      personCount: entries.length,
+      referenceName: root ? personDisplayName(root) : undefined,
+    },
+    {
+      detailLevel: "summary",
+      timelineStyle: "canvas",
+      coverLogo: true,
+    },
+  );
+
+  downloadBookletPdf(pdf, "livret.pdf");
+}
+```
+
+Use `scope: "all"` and `referencePerson: null` to include every individual in the file.
+
+### `collectBookletPersons` options
+
+| Option | Role |
+| --- | --- |
+| `ged` | `ReadGed` after import |
+| `scope` | `"all"` or `"from-reference"` (Sosa from `referencePerson`) |
+| `referencePerson` | Root person for `"from-reference"`; `null` if scope is `"all"` |
+| `maxGeneration` | Max Sosa generation (e.g. `6`); ignored when `scope === "all"` |
+
+Helpers: `personDisplayName`, `buildBookletPersonEntry`, `sortBookletEntries`, `bookletSexFromPerson`.
+
+### `generateGenealogyBookletPdf` options
+
+| Option | Values | Effect |
+| --- | --- | --- |
+| `detailLevel` | `"summary"` \| `"detailed"` | Short prose per person vs longer biographies |
+| `timelineStyle` | `"off"` \| `"canvas"` | Generation timeline pages per chapter |
+| `coverLogo` | `true` (default), `false`, or `DrawGedcomTsLogoOptions` | gedcom-ts vector logo on the cover |
+
+`BookletPdfMeta`: `title`, `scopeLabel`, `personCount`, optional `referenceName`.
+
+### Cover logo
+
+The cover draws the **gedcom-ts logo** from paths shipped in the package (`GEDCOM_TS_LOGO_PATHS`, `GEDCOM_TS_LOGO_VIEWBOX`). Reuse on custom PDF pages:
+
+```ts
+import { PDFDocument } from "pdf-lib";
+import {
+  drawGedcomTsLogoOnPage,
+  defaultCoverLogoOptions,
+  BOOKLET_BRAND_RGB,
+} from "gedcom-ts/booklet";
+
+const doc = await PDFDocument.create();
+const page = doc.addPage();
+drawGedcomTsLogoOnPage(page, defaultCoverLogoOptions());
+```
+
+### Booklet API cheat sheet
+
+| Goal | Export |
+| --- | --- |
+| Persons for the booklet | `collectBookletPersons` |
+| Chapters / families | `groupBookletIntoChapters`, `partnerNamesLabel` |
+| French narratives (custom UI) | `buildPersonSummaryNarrative`, `buildPersonDetailedNarratives`, `buildFamilyNarrative`, `buildChapterIntroNarrative` |
+| Page estimate | `estimateBookletSize`, `bookletSizeAdvice` |
+| Timeline data / PNG | `buildGenerationTimeline`, `rasterizeGenerationTimelinePng` |
+| PDF output | `generateGenealogyBookletPdf`, `downloadBookletPdf`, `toPdfText` |
+| Logo | `drawGedcomTsLogoOnPage`, `defaultCoverLogoOptions`, `GEDCOM_TS_LOGO_PATHS` |
+
+## API reference
 
-Everything exported from `gedcom-ts` is documented below with a short description and a minimal usage snippet. The full list mirrors the public exports of `src/index.ts`.
+Short description and a minimal snippet for each export of **`gedcom-ts`**. For the PDF booklet, see [Genealogy booklet (PDF)](#genealogy-booklet-pdf) (`gedcom-ts/booklet`).
 
 ### Importing a file
 
@@ -104,22 +353,24 @@ Result of an import. Top-level GEDCOM records not modeled into the typed graph (
 
 Notable members:
 
-| Member | Description |
-| --- | --- |
-| `persons: Person[]` | Imported individuals. |
-| `mapPersons: Map<number, Person>` | `INDI` (integer) → `Person`. |
-| `partnersMap: Map<number, Person[]>` | Family id → spouses. |
-| `childsMap: Map<number, Person[]>` | Family id → children. |
-| `placesMap: Map<string, Place>` | City name → `Place` (first occurrence wins). |
-| `mapFiles: Map<string, File>` | Relative path → media `File` (for ZIP imports). |
-| `datasetVersion: GedcomDatasetVersion` | `"7.0"`, `"5.5"` or `"unknown"`. |
-| `preservedTopLevelRecords: string[]` | Raw blocks for partial round-trip. |
-| `resolveIndividualPointer(raw)` | Resolves `@I12@`, `I12`, `@Homer_Simpson@`, `Homer_Simpson` to a `Person`. |
-| `getChildrenForParent(parent)` | All children attached to a parent (via `FAMS`). |
-| `getChildrenOfFamily(familyId)` | Children of a single family. |
-| `groupPartners()` | Rebuilds `partnersMap` / `childsMap` after editing links. |
-| `generateUniqueIndi()` | Next free `INDI` number for new persons. |
-| `rehydratePlacesFromActs()` | Rebuilds `placesMap` from act places (e.g. after manual graph edits). Use `editReadGed(readGed).addPerson(...)` to register persons so maps stay coherent. |
+
+| Member                                 | Description                                                                                                                                                |
+| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `persons: Person[]`                    | Imported individuals.                                                                                                                                      |
+| `mapPersons: Map<number, Person>`      | `INDI` (integer) → `Person`.                                                                                                                               |
+| `partnersMap: Map<number, Person[]>`   | Family id → spouses.                                                                                                                                       |
+| `childsMap: Map<number, Person[]>`     | Family id → children.                                                                                                                                      |
+| `placesMap: Map<string, Place>`        | City name → `Place` (first occurrence wins).                                                                                                               |
+| `mapFiles: Map<string, File>`          | Relative path → media `File` (for ZIP imports).                                                                                                            |
+| `datasetVersion: GedcomDatasetVersion` | `"7.0"`, `"5.5"` or `"unknown"`.                                                                                                                           |
+| `preservedTopLevelRecords: string[]`   | Raw blocks for partial round-trip.                                                                                                                         |
+| `resolveIndividualPointer(raw)`        | Resolves `@I12@`, `I12`, `@Homer_Simpson@`, `Homer_Simpson` to a `Person`.                                                                                 |
+| `getChildrenForParent(parent)`         | All children attached to a parent (via `FAMS`).                                                                                                            |
+| `getChildrenOfFamily(familyId)`        | Children of a single family.                                                                                                                               |
+| `groupPartners()`                      | Rebuilds `partnersMap` / `childsMap` after editing links.                                                                                                  |
+| `generateUniqueIndi()`                 | Next free `INDI` number for new persons.                                                                                                                   |
+| `rehydratePlacesFromActs()`            | Rebuilds `placesMap` from act places (e.g. after manual graph edits). Use `editReadGed(readGed).addPerson(...)` to register persons so maps stay coherent. |
+
 
 ```ts
 import { ReadGed } from "gedcom-ts";
@@ -177,13 +428,15 @@ async function exportZip(persons: Person[]) {
 
 Options shared by both exporters:
 
-| Option | Effect |
-| --- | --- |
+
+| Option                 | Effect                                                                                                   |
+| ---------------------- | -------------------------------------------------------------------------------------------------------- |
 | `extraTopLevelRecords` | Raw `0 …` blocks re-emitted before `SUBM` / `TRLR` (round-trip with `readGed.preservedTopLevelRecords`). |
-| `headLanguageTag` | BCP 47 tag for `HEAD`.`LANG` (defaults to `en-US`). |
-| `headCopyright` | One-line `1 COPR` notice. |
-| `headDestination` | Value of `HEAD`.`DEST` (target app / URI). |
-| `headSchemaTagDefs` | Extension tag definitions emitted as `HEAD`.`SCHMA` / `2 TAG …`. |
+| `headLanguageTag`      | BCP 47 tag for `HEAD`.`LANG` (defaults to `en-US`).                                                      |
+| `headCopyright`        | One-line `1 COPR` notice.                                                                                |
+| `headDestination`      | Value of `HEAD`.`DEST` (target app / URI).                                                               |
+| `headSchemaTagDefs`    | Extension tag definitions emitted as `HEAD`.`SCHMA` / `2 TAG …`.                                         |
+
 
 ### Domain model
 
@@ -394,14 +647,16 @@ editPerson(person)
 editDateAct(person.acts.list[0].dateAct!).setExactDate(1900, "JAN", 1);
 ```
 
-| Helper / class | Purpose |
-| --- | --- |
-| `editPerson(person)` / `PersonEdit` | Identity, `FAMS` / `FAMC` / `removeFams*`, `nameVariants()` / `attributes()` / `multimedia()`, bulk `clear*`, entry points to `acts()` and `notes()`. |
-| `editActs(acts)` / `ActsEdit` | `add`, `addNew`, `insertAt`, `insertNewAt`, `replaceAt`, `removeAt`, `removeAct`, `removeLast`, `clear`, `sortByDate`, `at`, `indexOfAct`. |
-| `editAct(act)` / `ActEdit` | `setType`, `setIndis`, dates, place, EVEN fields, preserved lines, `notes()`, `multimedia()`, `clearNotes`, `clearMultimedia`. |
-| `editDateAct(dateAct)` / `DateActEdit` | `clear`, `applyGedcomPayload`, `setExactDate`, `setQualified`, `setBetween`, `setFromTo`, `setTime`, `setDatePhrase` / `appendDatePhrase`, `setVerbatimPayload`. |
-| `editPlace(place)` / `PlaceEdit` | `setFromGedcom7Payload`, `setCity`, `setCounty`, `setState`, `setCountry`, `setPlacPhrase` / `appendPlacPhrase` / `clearPlacPhrase`, `setCoordinates` / `clearCoordinates` / `replaceCoordinateModel`, `clearStructured`. |
-| `editNotes(notes)` / `NotesEdit` | `add`, `addNew`, `insertAt`, `insertNewAt`, `replaceAt`, `removeAt`, `removeNote`, `removeLast`, `clear`, `at`, `indexOfNote`. |
+
+| Helper / class                         | Purpose                                                                                                                                                                                                                   |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `editPerson(person)` / `PersonEdit`    | Identity, `FAMS` / `FAMC` / `removeFams*`, `nameVariants()` / `attributes()` / `multimedia()`, bulk `clear*`, entry points to `acts()` and `notes()`.                                                                     |
+| `editActs(acts)` / `ActsEdit`          | `add`, `addNew`, `insertAt`, `insertNewAt`, `replaceAt`, `removeAt`, `removeAct`, `removeLast`, `clear`, `sortByDate`, `at`, `indexOfAct`.                                                                                |
+| `editAct(act)` / `ActEdit`             | `setType`, `setIndis`, dates, place, EVEN fields, preserved lines, `notes()`, `multimedia()`, `clearNotes`, `clearMultimedia`.                                                                                            |
+| `editDateAct(dateAct)` / `DateActEdit` | `clear`, `applyGedcomPayload`, `setExactDate`, `setQualified`, `setBetween`, `setFromTo`, `setTime`, `setDatePhrase` / `appendDatePhrase`, `setVerbatimPayload`.                                                          |
+| `editPlace(place)` / `PlaceEdit`       | `setFromGedcom7Payload`, `setCity`, `setCounty`, `setState`, `setCountry`, `setPlacPhrase` / `appendPlacPhrase` / `clearPlacPhrase`, `setCoordinates` / `clearCoordinates` / `replaceCoordinateModel`, `clearStructured`. |
+| `editNotes(notes)` / `NotesEdit`       | `add`, `addNew`, `insertAt`, `insertNewAt`, `replaceAt`, `removeAt`, `removeNote`, `removeLast`, `clear`, `at`, `indexOfNote`.                                                                                            |
+
 
 ### Dataset editing: `ReadGed`, graph, clone, export options, validation
 
@@ -459,15 +714,17 @@ validateReadGed(readGed, {
 
 `tryAddPersonToReadGed`, `tryRemovePersonFromReadGedByIndi`, `tryLinkChildToFamily`, `tryUnlinkChildFromFamily`, and `tryCreateMarriageFamily` return a `CommandResult` (`ok` + `issues` or `value` + optional `warnings`). `editReadGed(...).addPerson` uses these checks internally (throws on blocking errors). For UI or transactional flows, prefer the `try*` APIs and inspect `commandBlockingIssues`.
 
-| Export | Role |
-| --- | --- |
-| `editReadGed(readGed)` / `ReadGedEdit` | `addPerson`, `removePersonByIndi`, `preserved()` → `PreservedTopLevelEdit` (`append`, `insertAt`, `replaceAt`, `removeAt`, `clear`) on `preservedTopLevelRecords`. Low-level helpers: `addPersonToReadGed`, `removePersonFromReadGedByIndi`. |
-| `editGedcomExportOptions(opts)` / `GedcomExportOptionsEdit` | Fluent setters for `extraTopLevelRecords`, `headLanguageTag`, `headCopyright`, `headDestination`, `headSchemaTagDefs`. |
-| `clonePerson(person, newIndi)` / `cloneAct(act)` / `person.clone` / `act.clone` | Deep copies for templates or undo stacks. |
-| `nextFamilyId(persons)` | Next internal family id `F`. |
-| `createMarriageFamily`, `linkChildToFamily`, `unlinkChildFromFamily`, `removeFamilyReferencesFromDataset` | Crée une `F` et des actes sur les deux conjoints. 5ᵉ argument : `{ eventTag }` (défaut `MARR`) pour `ENGA`, bans, contrat, `EVEN`+`CreateActInit`, etc. Voir `GEDCOM_7_PAIR_UNION_EVENT_TAGS`. |
-| `validateReadGed`, `assertReadGedConsistent`, `validatePerson`, `assertPersonConsistent` | Typed `code` / `severity` (`error` \| `warn`). Options: `checkMarrParticipants`, `checkDuplicateIndis`, `checkFamcWithoutSpouses`, `checkFamsWithoutSpouses`, `checkDuplicateFamsEntries`, `checkAncestorCycles`. Assertions: `failOn` (default: `error`). |
-| `tryAddPersonToReadGed`, `tryRemovePersonFromReadGedByIndi`, `tryLinkChildToFamily`, `tryUnlinkChildFromFamily`, `tryCreateMarriageFamily`, `commandBlockingIssues` | Command layer with `CommandResult` / `validate*Command` prechecks. |
+
+| Export                                                                                                                                                              | Role                                                                                                                                                                                                                                                      |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `editReadGed(readGed)` / `ReadGedEdit`                                                                                                                              | `addPerson`, `removePersonByIndi`, `preserved()` → `PreservedTopLevelEdit` (`append`, `insertAt`, `replaceAt`, `removeAt`, `clear`) on `preservedTopLevelRecords`. Low-level helpers: `addPersonToReadGed`, `removePersonFromReadGedByIndi`.              |
+| `editGedcomExportOptions(opts)` / `GedcomExportOptionsEdit`                                                                                                         | Fluent setters for `extraTopLevelRecords`, `headLanguageTag`, `headCopyright`, `headDestination`, `headSchemaTagDefs`.                                                                                                                                    |
+| `clonePerson(person, newIndi)` / `cloneAct(act)` / `person.clone` / `act.clone`                                                                                     | Deep copies for templates or undo stacks.                                                                                                                                                                                                                 |
+| `nextFamilyId(persons)`                                                                                                                                             | Next internal family id `F`.                                                                                                                                                                                                                              |
+| `createMarriageFamily`, `linkChildToFamily`, `unlinkChildFromFamily`, `removeFamilyReferencesFromDataset`                                                           | Create family `F` and spouse acts; optional `{ eventTag }` (default `MARR`, also `ENGA`, banns, contract, `EVEN` + `CreateActInit`, …). See `GEDCOM_7_PAIR_UNION_EVENT_TAGS`.                                                                             |
+| `validateReadGed`, `assertReadGedConsistent`, `validatePerson`, `assertPersonConsistent`                                                                            | Typed `code` / `severity` (`error` \| `warn`). Options: `checkMarrParticipants`, `checkDuplicateIndis`, `checkFamcWithoutSpouses`, `checkFamsWithoutSpouses`, `checkDuplicateFamsEntries`, `checkAncestorCycles`. Assertions: `failOn` (default: `error`). |
+| `tryAddPersonToReadGed`, `tryRemovePersonFromReadGedByIndi`, `tryLinkChildToFamily`, `tryUnlinkChildFromFamily`, `tryCreateMarriageFamily`, `commandBlockingIssues` | Command layer with `CommandResult` / `validate*Command` prechecks.                                                                                                                                                                                        |
+
 
 ### Utilities
 
@@ -492,31 +749,9 @@ import { remainingTypesAct, Acts } from "gedcom-ts";
 const available = remainingTypesAct(new Acts());
 ```
 
-#### Geocoding (Nominatim)
-
-Place search uses the official Nominatim endpoint `GET https://nominatim.openstreetmap.org/search` with `q`, `format=jsonv2`, and `addressdetails=1` (not the legacy `search.php?city=` API). A `User-Agent` header is required (`gedcom-ts/<version> (genealogy library)` by default).
-
-```ts
-import {
-  inferGeocodeContext,
-  searchPlacesWithContext,
-  rankGeocodeCandidates,
-  findHarmonizationClusters,
-  applyGeocodeCandidateToActs,
-} from "gedcom-ts";
-
-const context = inferGeocodeContext(ged);
-const candidates = await searchPlacesWithContext("Valence", context);
-// candidates are ranked (French tree → Valence FR before ES)
-
-const clusters = findHarmonizationClusters(ged);
-```
-
-For tests or Node without a global `fetch`, pass `fetchFn` in options. Low-level API: `searchPlaces(query, { countryCodes, limit, userAgent, fetchFn })`.
-
 #### `getCityCoordinates(cityName, callback)` (deprecated)
 
-Legacy callback API; delegates to `searchPlaces` and maps results to `Place[]`. Prefer `searchPlaces` / `searchPlacesWithContext`.
+Legacy callback API. Use [Geocoding places](#geocoding-places) instead.
 
 #### `resolveDatasetVersion(headerLines)` / `GedcomDatasetVersion`
 
@@ -561,7 +796,7 @@ const primary = selectPrimaryNameVariant(person.nameVariants);
 
 #### `GEDCOM_LIBRARY_VERSION`
 
-CalVer string embedded in the exported `HEAD`.`SOUR`.`VERS` (same value as `package.json` `version`, e.g. `2026.5.0`). A test (`version-package-sync`) enforces the match on every CI run.
+CalVer string written in exported `HEAD`.`SOUR`.`VERS` (same value as the npm package version, e.g. `2026.5.2`).
 
 ```ts
 import { GEDCOM_LIBRARY_VERSION } from "gedcom-ts";
@@ -569,56 +804,6 @@ import { GEDCOM_LIBRARY_VERSION } from "gedcom-ts";
 console.log(`gedcom-ts ${GEDCOM_LIBRARY_VERSION}`);
 ```
 
-## End-to-end example
-
-```ts
-import {
-  importGedFile,
-  ExportGedzipFile,
-  editPerson,
-  DateAct,
-  Identifier,
-} from "gedcom-ts";
-
-async function importModifyExport(file: File) {
-  const readGed = await importGedFile(file);
-  const persons = readGed.persons;
-
-  if (persons.length > 0) {
-    editPerson(persons[0])
-      .setLastname(persons[0].lastname.toUpperCase())
-      .acts()
-      .at(0)
-      .setDateAct(new DateAct("1 JAN 1900"));
-  }
-
-  await new ExportGedzipFile("updated-tree", persons).download();
-}
-```
-
-## Development
-
-### Local scripts
-
-| Script | Role |
-| --- | --- |
-| `npm run lint` | ESLint on the codebase |
-| `npm run test` | Vitest test suite |
-| `npm run build` | Production bundle + `.d.ts` |
-| `npm run tgz` | `build` then `npm pack` (local `.tgz`) |
-
-### GitLab CI (`.gitlab-ci.yml`)
-
-Every pipeline runs **`InstallDependencies`** (`npm ci`, `node_modules` artifact) — required by all other jobs.
-
-| Job | When it runs |
-| --- | --- |
-| `InstallDependencies` | Always |
-| `Lint`, `Test` | Merge requests and branch pushes (not on `master` after a merge commit titled `Merge…`) |
-| `BuildTgz`, `PublishNpm` | Push to `master` after merge only (`Merge…` commit title) |
-
-Typical flow: open an MR from a release branch (e.g. `2026.5.0`) → lint + test run there → after merge to `master`, only package build and npm publish run (quality checks are not repeated).
-
 ## Error handling
 
 ```ts
@@ -635,3 +820,4 @@ try {
   }
 }
 ```
+

package/dist/booklet/booklet-date-fr.d.ts

@@ -0,0 +1,8 @@
+/** Date réduite à une année (éventuellement avec qualificateur GEDCOM). */
+export declare function isYearOnlyDate(dateLabel: string): boolean;
+/** « le 15 mars 1991 », « en 1991 », « vers 1700 », « avant 1800 »… */
+export declare function onDate(dateLabel: string): string;
+/** « De 1700 à 1850 » ou « Du 15 mars 1700 au 3 janvier 1850 ». */
+export declare function lifeDateRange(from: string, to: string): string;
+/** « voit le jour en 1991 » ou « voit le jour le 15 mars 1991 ». */
+export declare function seesDayOn(dateLabel: string): string;

package/dist/booklet/booklet-estimate.d.ts

@@ -0,0 +1,11 @@
+import type { BookletTimelineStyle } from './booklet-timeline';
+import type { BookletChapter, BookletDetailLevel } from './booklet-structure';
+export interface BookletSizeEstimate {
+    readonly pages: number;
+    readonly label: string;
+}
+/** Nombre de pages frise estimé pour un chapitre (tranches dynamiques). */
+export declare function estimateTimelineSliceCount(rowCount: number): number;
+/** Estimation grossière du nombre de pages pour orienter l’utilisateur. */
+export declare function estimateBookletSize(chapters: readonly BookletChapter[], personCount: number, familyCount: number, detailLevel: BookletDetailLevel, timelineStyle?: BookletTimelineStyle): BookletSizeEstimate;
+export declare function bookletSizeAdvice(personCount: number, detailLevel: BookletDetailLevel): string | null;

package/dist/booklet/booklet-gender.d.ts

@@ -0,0 +1,23 @@
+/** Sexe GEDCOM exploité pour les accords du livret (M, F, U, X). */
+export type BookletSex = 'M' | 'F' | 'U' | 'X';
+export interface PersonGenderWords {
+    readonly born: string;
+    readonly died: string;
+    readonly baptized: string;
+    readonly present: string;
+    readonly linked: string;
+    readonly offspring: string;
+    readonly descendant: string;
+    readonly childOf: string;
+    readonly parentOf: string;
+}
+/** Participes / noms accordés au genre de la personne. U et X → formes neutres. */
+export declare function personGenderWords(sex: BookletSex): PersonGenderWords;
+/** Suffixe pluriel français (0 ou 1 → singulier). */
+export declare function pluralS(count: number): string;
+/** Choisit la forme singulier / pluriel. */
+export declare function pluralPick<T>(count: number, one: T, many: T): T;
+/** « 1 enfant recensé » / « N enfants recensés ». */
+export declare function recensedChildrenPhrase(count: number): string;
+/** « 1 autre union citée… » / « N autres unions citées… ». */
+export declare function otherUnionsPhrase(count: number): string;

package/dist/booklet/booklet-logo.d.ts

@@ -0,0 +1,19 @@
+import { type PDFPage, type RGB } from 'pdf-lib';
+export { GEDCOM_TS_LOGO_PATHS, GEDCOM_TS_LOGO_VIEWBOX } from "./gedcom-ts-logo.paths";
+/** Couleur de marque gedcom-ts (#19196f), pour pdf-lib `rgb(...)`. */
+export declare const BOOKLET_BRAND_RGB: RGB;
+export interface GedcomTsLogoLayout {
+    /** Ordonnée PDF du bas du logo (pour placer texte et barre en dessous). */
+    readonly bottomY: number;
+    readonly height: number;
+}
+export interface DrawGedcomTsLogoOptions {
+    readonly pageWidth?: number;
+    readonly maxWidth?: number;
+    readonly bottomY?: number;
+    readonly color?: RGB;
+}
+/** Options par défaut du logo sur une page A4 (couverture du livret). */
+export declare function defaultCoverLogoOptions(pageWidth?: number, pageHeight?: number): DrawGedcomTsLogoOptions;
+/** Dessine le logo gedcom-ts en vecteur SVG sur la page (pdf-lib drawSvgPath). */
+export declare function drawGedcomTsLogoOnPage(page: PDFPage, options?: DrawGedcomTsLogoOptions): GedcomTsLogoLayout;