gedcom-ts 2026.5.2 → 2026.5.4

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 All notable changes of gedcom-ts
 
+## [2026.5.4] - 2026-05-24
+
+### Added
+
+- **Livret multilingue** : traductions dédiées pour les 11 langues du site (`en`, `fr`, `de`, `nl`, `es`, `zh`, `it`, `pt`, `pl`, `ar`, `he`) — messages PDF, dates, lieux, accords de genre et récits narratifs.
+- **RTL arabe / hébreu** : `isBookletLocaleRtl`, `bookletTextDirection`, mise en page PDF miroir ; **`bidi-js`** (réordonnancement visuel) et **`naqqash`** (formes contextuelles arabes).
+- **Polices PDF intégrées** : Noto Sans Hebrew, Noto Sans Arabic et Noto Sans SC (subset, SIL OFL) en chunks lazy (`dist/font-chunks/`) ; chunk **`booklet-pdf-font-bytes-zh-ext`** (~1,4 MiB) si le GEDCOM contient des hanzi hors subset de base.
+- **Rendu bi-police** : Helvetica pour le latin + Noto pour arabe / hébreu / chinois.
+- **Architecture lazy du livret** : locales (`dist/locale-chunks/`), polices, logo SVG et frise canvas (`dist/feature-chunks/`) via `import()` — cœur `gedcom-ts/booklet` ~75 KiB minifié (~100 KiB obfusqué).
+- **Exports TypeScript des chunks** : chaque sous-chemin `gedcom-ts/booklet/locale-chunks/*`, `font-chunks/*` et `feature-chunks/*` expose `types` + `import` / `require`.
+- **Manifeste unique** : `scripts/booklet-chunk-manifest.mjs` alimente `build.js` et `package.json` (`npm run sync:exports` ou fin de `build:js`).
+- **API hôte** : `registerBookletPdfFontBytes`, `registerPdfFontkit`, `ensureBookletLocale` — preload explicite des chunks (recommandé Vite/Angular).
+- **Scripts** : `prepare:locales`, `prepare:fonts`, `sync:exports`.
+- **Exports** : `BOOKLET_LOCALES`, `BOOKLET_RTL_LOCALES`, `isBookletLocale`, `preparePdfText`, `PdfTextOptions`, `loadBookletPdfFontBytes`, `localeNeedsUnicodePdfFont`, …
+- **Tests** : `tests/booklet/` (i18n, RTL, polices ar/zh, bidi, chunk exports, dist imports).
+
+### Changed
+
+- **`pdf-lib` externalisé** : peer dependency ; `@pdf-lib/fontkit` chargé à la demande pour `zh` / `ar` / `he`.
+- **Pipeline build livret** : esbuild → réécriture `./…-chunks/` → `gedcom-ts/booklet/…-chunks/` → obfuscation avec `reservedStrings` sur les chemins d’import dynamiques (analyse statique Vite).
+- **`resolveBookletLocale`** : retourne la locale demandée (plus de repli silencieux vers l’anglais).
+- **`drawGedcomTsLogoOnPage`** : async ; logo lazy (`getGedcomTsLogoPaths()`).
+- **`ensureBookletLocale(locale)`** requis avant les APIs sync.
+- **Frise chronologique** : titre et libellé « dates inconnues » localisés.
+- **README** : tableau des tailles, guide d’intégration Vite/Angular.
+
+### Fixed
+
+- **Vite / Angular dev** : imports dynamiques relatifs pré-bundleés dans le cache deps — chemins package explicites dans `dist/booklet.mjs` + `exports` complets.
+
+## [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
@@ -113,7 +157,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
 
@@ -174,7 +218,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,23 +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`, 11 locales including RTL Arabic/Hebrew)
 
 ## 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)**
 
 ## Contents
 
 - [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.2` = May 2026). See [CHANGELOG.md](CHANGELOG.md).
+- 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` en peerDependency, chargé depuis `node_modules`)
 
 ## Installation
 
@@ -30,6 +36,14 @@ 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. For the PDF booklet, **`pdf-lib` is a peer dependency** — install it in your app if you use `gedcom-ts/booklet`:
+
+```bash
+npm install pdf-lib
+```
+
+For `zh` / `ar` / `he` PDF output, your bundler should also be able to resolve `@pdf-lib/fontkit` (included in `gedcom-ts` dependencies; the host app typically preloads it — see [Bundle layout](#bundle-layout) below).
+
 ## Runtime Requirements
 
 - modern browser runtime (`File`, `Blob`, `XMLHttpRequest`, `URL.createObjectURL`)
@@ -183,9 +197,179 @@ Network: `GET https://nominatim.openstreetmap.org/search?q=…&format=jsonv2` wi
 
 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 narrative text from GEDCOM acts (birth, marriage, death, …). **English is the default locale** (`DEFAULT_BOOKLET_LOCALE`). Full copy is available for **`en`**, **`fr`**, **`de`**, **`nl`**, **`es`**, **`zh`**, **`it`**, **`pt`**, **`pl`**, **`ar`**, and **`he`** (aligned with [gedcomts.com](https://gedcomts.com) UI languages). Arabic and Hebrew use **RTL layout** in the PDF (`isBookletLocaleRtl`, `bookletTextDirection`).
+
+### Bundle layout
+
+Code is split so the host app only downloads what it uses. Approximate sizes after minify (obfuscation adds ~25–30 KiB on `gedcom-ts/booklet`).
+
+| Artifact | Size (typ.) | When loaded |
+| --- | ---: | --- |
+| `gedcom-ts` (`dist/index.mjs`) | ~180 KiB | GEDCOM import / edit / export |
+| `gedcom-ts/booklet` (`dist/booklet.mjs`) | ~100 KiB | livret (collect, estimate, PDF) |
+| `locale-chunks/booklet-locale-*` | 14–26 KiB | one UI language |
+| `feature-chunks/booklet-logo-draw` | ~11 KiB | cover logo (`coverLogo !== false`) |
+| `feature-chunks/booklet-timeline-raster` | ~3 KiB | `timelineStyle: "canvas"` |
+| `font-chunks/booklet-pdf-font-bytes-ar` | ~43 KiB | Arabic PDF |
+| `font-chunks/booklet-pdf-font-bytes-he` | ~13 KiB | Hebrew PDF |
+| `font-chunks/booklet-pdf-font-bytes-zh` | ~190 KiB | Chinese PDF (base subset) |
+| `font-chunks/booklet-pdf-font-bytes-zh-ext` | ~1.4 MiB | Chinese PDF when GEDCOM names need extra Han |
+| `pdf-lib` (peer, not in gedcom-ts) | ~500 KiB+ | any PDF generation |
+
+**Not bundled in gedcom-ts:** `fflate` (main entry, external), `pdf-lib` (booklet peer). **`bidi-js`** and **`naqqash`** (Arabic shaping / RTL reordering) ship inside `gedcom-ts/booklet` today.
+
+Call **`await ensureBookletLocale(locale)`** before sync APIs. `generateGenealogyBookletPdf` preloads locale, logo, and timeline when needed.
+
+**Lazy chunk subpaths** (for bundler preload or explicit `import()` — normal apps should use `ensureBookletLocale()` instead):
+
+| Subpath | Role |
+| --- | --- |
+| `gedcom-ts/booklet/locale-chunks/booklet-locale-{en,fr,de,nl,es,zh,it,pt,pl,ar,he}` | Messages, narratives, date/place helpers per locale |
+| `gedcom-ts/booklet/font-chunks/booklet-pdf-font-bytes-{ar,he,zh,zh-ext}` | Subset Noto font bytes |
+| `gedcom-ts/booklet/feature-chunks/booklet-logo-draw` | Cover logo SVG paths |
+| `gedcom-ts/booklet/feature-chunks/booklet-timeline-raster` | Canvas timeline PNG rasterizer |
+
+Each subpath is listed in `package.json` **`exports`** with matching **`types`** (`.d.ts` under `dist/booklet/…`) and runtime (`.mjs` / `.cjs` under `dist/…`). TypeScript resolves them via `exports.types` (`moduleResolution: bundler` / `node16`). Adding a locale updates `scripts/booklet-chunk-manifest.mjs`; `npm run build:js` regenerates chunk files and syncs `exports`.
+
+### Vite / Angular integration
+
+1. **Lazy-load the booklet entry** — `import('gedcom-ts/booklet')` only when the user opens export / download (not on every tree page).
+2. **Preload the UI locale** — `import('gedcom-ts/booklet/locale-chunks/booklet-locale-fr')` (or your loader) before sync APIs; then `ensureBookletLocale('fr')`.
+3. **Unicode PDF (`zh` / `ar` / `he`)** — the host app should import font chunks explicitly and call `registerBookletPdfFontBytes` + `registerPdfFontkit` before `generateGenealogyBookletPdf` (see [gedcomts.com](https://gedcomts.com) `booklet-pdf-deps.loader.ts` for a reference pattern).
+4. **Dev server** — exclude the main booklet bundle from Vite pre-bundling so lazy subpaths resolve via `node_modules`:
+
+```ts
+// vite.config.ts / angular.json (esbuild optimizeDeps)
+optimizeDeps: {
+  exclude: ["gedcom-ts/booklet"],
+},
+```
+
+Published `dist/booklet.mjs` keeps **literal** dynamic `import('gedcom-ts/booklet/…')` strings (rewrite before obfuscation, paths reserved from string encoding) so Vite can statically analyze chunk loads.
+
+### Workflow
+
+1. Import with `importGedFile` (`gedcom-ts`).
+2. **`await ensureBookletLocale(locale)`** — load messages/narratives for the chosen language.
+3. Collect persons with `collectBookletPersons` (`gedcom-ts/booklet`).
+4. Optionally preview size with `estimateBookletSize` + `groupBookletIntoChapters`.
+5. Build bytes with `generateGenealogyBookletPdf`, then `downloadBookletPdf` (browser).
+
+```ts
+import { importGedFile } from "gedcom-ts";
+import {
+  collectBookletPersons,
+  ensureBookletLocale,
+  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 locale = "en" as const; // BookletLocale — align with your UI language (en, fr, de, nl, es, zh, it, pt, pl, ar, he)
+  await ensureBookletLocale(locale);
+
+  const entries = collectBookletPersons({
+    ged,
+    scope: "from-reference",
+    referencePerson: root,
+    maxGeneration: 6,
+    locale,
+  });
+
+  const chapters = groupBookletIntoChapters(entries, locale);
+  const families = chapters.reduce((n, ch) => n + ch.families.length, 0);
+  const size = estimateBookletSize(chapters, entries.length, families, "summary", "canvas", locale);
+  console.log(size.label);
+
+  const pdf = await generateGenealogyBookletPdf(
+    entries,
+    {
+      title: "Family booklet",
+      scopeLabel: "Ancestors and descendants",
+      personCount: entries.length,
+      referenceName: root ? personDisplayName(root) : undefined,
+    },
+    {
+      detailLevel: "summary",
+      timelineStyle: "canvas",
+      coverLogo: true,
+      locale,
+    },
+  );
+
+  downloadBookletPdf(pdf, "family-booklet.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"` |
+| `locale` | `BookletLocale` (default `"en"`) — `en`, `fr`, `de`, `nl`, `es`, `zh`, `it`, `pt`, `pl`, `ar`, `he` |
+
+Helpers: `personDisplayName`, `buildBookletPersonEntry`, `sortBookletEntries`, `bookletSexFromPerson`, `DEFAULT_BOOKLET_LOCALE`, `BOOKLET_LOCALES`, `isBookletLocaleRtl`.
+
+### `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 |
+| `locale` | `BookletLocale` (default `"en"`) | Narrative, chapter titles, PDF chrome, timeline legend |
+| `unicodeFont` | `Uint8Array` (optional) | Replace bundled Noto font for `zh` / `ar` / `he` |
+
+`BookletPdfMeta`: `title`, `scopeLabel`, `personCount`, optional `referenceName` (usually translated in the host app).
+
+### Cover logo
+
+The cover draws the **gedcom-ts logo** from lazy-loaded SVG paths (`ensureBookletLogo`, `getGedcomTsLogoPaths`, `getGedcomTsLogoViewbox`). Reuse on custom PDF pages:
+
+```ts
+import { PDFDocument } from "pdf-lib";
+import {
+  drawGedcomTsLogoOnPage,
+  defaultCoverLogoOptions,
+  ensureBookletLogo,
+} from "gedcom-ts/booklet";
+
+const doc = await PDFDocument.create();
+const page = doc.addPage();
+await ensureBookletLogo();
+await drawGedcomTsLogoOnPage(page, defaultCoverLogoOptions());
+```
+
+### Booklet API cheat sheet
+
+| Goal | Export |
+| --- | --- |
+| Persons for the booklet | `collectBookletPersons` |
+| Chapters / families | `groupBookletIntoChapters`, `partnerNamesLabel` |
+| Localized narratives (custom UI) | `buildPersonSummaryNarrative`, `buildPersonDetailedNarratives`, `buildFamilyNarrative`, `buildChapterIntroNarrative` |
+| Page estimate | `estimateBookletSize`, `bookletSizeAdvice` |
+| Timeline data / PNG | `buildGenerationTimeline`, `rasterizeGenerationTimelinePng` |
+| PDF output | `generateGenealogyBookletPdf`, `downloadBookletPdf`, `toPdfText`, `preparePdfText` |
+| Locale helpers | `resolveBookletLocale`, `bookletLocaleToBcp47`, `bookletTextDirection`, `BOOKLET_RTL_LOCALES`, `ensureBookletLocale` |
+| Font preload (host) | `registerBookletPdfFontBytes`, `registerPdfFontkit`, `localeNeedsUnicodePdfFont` |
+| Logo | `ensureBookletLogo`, `drawGedcomTsLogoOnPage`, `getGedcomTsLogoPaths`, `defaultCoverLogoOptions` |
+
 ## API reference
 
-Short description and a minimal snippet for each public export.
+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
 

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

@@ -0,0 +1,9 @@
+export declare const BOOKLET_UNKNOWN_DATE_EN = "Unknown date";
+/** Year-only date (optional GEDCOM qualifier). */
+export declare function isYearOnlyDate(dateLabel: string): boolean;
+/** "on 15 March 1991", "in 1991", "about 1700", "before 1800", etc. */
+export declare function onDate(dateLabel: string): string;
+/** "From 1700 to 1850" or "From 15 March 1700 to 3 January 1850". */
+export declare function lifeDateRange(from: string, to: string): string;
+/** "was born in 1991" or "was born on 15 March 1991". */
+export declare function seesDayOn(dateLabel: string): string;

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

@@ -0,0 +1,21 @@
+export interface BookletDateConfig {
+    readonly unknownDate: string;
+    readonly onUnknown: string;
+    readonly inYear: (year: string) => string;
+    readonly beforeYear: (year: string) => string;
+    readonly afterYear: (year: string) => string;
+    readonly aboutYear: (year: string) => string;
+    readonly onFullDate: (date: string) => string;
+    readonly lifeRange: (from: string, to: string, fromIsYearOnly: boolean) => string;
+    readonly seesDayInYear: (year: string) => string;
+    readonly seesDayOnPhrase: (phrase: string) => string;
+    readonly seesDayOnFullDate: (date: string) => string;
+}
+export interface BookletDateModule {
+    readonly BOOKLET_UNKNOWN_DATE: string;
+    isYearOnlyDate(dateLabel: string): boolean;
+    onDate(dateLabel: string): string;
+    lifeDateRange(from: string, to: string): string;
+    seesDayOn(dateLabel: string): string;
+}
+export declare function createBookletDateModule(config: BookletDateConfig): BookletDateModule;

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

@@ -0,0 +1,9 @@
+export declare const BOOKLET_UNKNOWN_DATE_FR = "Date inconnue";
+/** 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-date.d.ts

@@ -0,0 +1,6 @@
+import type { BookletLocale } from "./booklet-locale";
+export declare function unknownDateLabel(locale?: BookletLocale): string;
+export declare function isYearOnlyDate(dateLabel: string, locale?: BookletLocale): boolean;
+export declare function onDate(dateLabel: string, locale?: BookletLocale): string;
+export declare function lifeDateRange(from: string, to: string, locale?: BookletLocale): string;
+export declare function seesDayOn(dateLabel: string, locale?: BookletLocale): string;

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

@@ -0,0 +1,12 @@
+import type { BookletTimelineStyle } from './booklet-timeline';
+import type { BookletChapter, BookletDetailLevel } from './booklet-structure';
+import type { BookletLocale } from './booklet-locale';
+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, locale?: BookletLocale): BookletSizeEstimate;
+export declare function bookletSizeAdvice(personCount: number, detailLevel: BookletDetailLevel, locale?: BookletLocale): string | null;

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

@@ -0,0 +1,3 @@
+import type { BookletSex, PersonGenderWords } from './booklet-gender';
+export declare const WORDS_EN: Record<BookletSex, PersonGenderWords>;
+export declare const WORDS_FR: Record<BookletSex, PersonGenderWords>;

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

@@ -0,0 +1,9 @@
+import type { BookletLocale } from './booklet-locale';
+import type { BookletSex, PersonGenderWords } from './booklet-gender';
+export interface GenderPhraseBundle {
+    readonly recensedChildren: (count: number) => string;
+    readonly otherUnions: (count: number) => string;
+    readonly usesPluralS: boolean;
+}
+export declare const GENDER_WORDS: Partial<Record<BookletLocale, Record<BookletSex, PersonGenderWords>>>;
+export declare const GENDER_PHRASES: Partial<Record<BookletLocale, GenderPhraseBundle>>;

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

@@ -0,0 +1,22 @@
+import type { BookletLocale } from './booklet-locale';
+/** 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;
+}
+/** Participles / role words aligned with the person's sex. U and X use neutral forms. */
+export declare function personGenderWords(sex: BookletSex, locale?: BookletLocale): PersonGenderWords;
+/** Plural suffix (French-style locales: 0 or 1 → singular; English: unused). */
+export declare function pluralS(count: number, locale?: BookletLocale): string;
+/** Singular / plural pick. */
+export declare function pluralPick<T>(count: number, one: T, many: T): T;
+export declare function recensedChildrenPhrase(count: number, locale?: BookletLocale): string;
+export declare function otherUnionsPhrase(count: number, locale?: BookletLocale): string;

package/dist/booklet/booklet-locale-helpers.d.ts

@@ -0,0 +1,4 @@
+/** Shared place-prefix helpers for locale date/place modules. */
+export declare function hasCountryPrefix(core: string, prefixes: readonly string[]): boolean;
+export declare function prefixedLocation(core: string, prefixes: readonly string[], elsePrefix: string): string;
+export declare function commaPrefixedLocation(core: string, prefixes: readonly string[], elsePrefix: string): string;

package/dist/booklet/booklet-locale-loader.d.ts

@@ -0,0 +1,27 @@
+import type { BookletDateModule } from './booklet-date-factory';
+import type { BookletPlaceModule } from './booklet-place-factory';
+import type { BookletSex, PersonGenderWords } from './booklet-gender';
+import type { GenderPhraseBundle } from './booklet-gender-data';
+import type { BookletLocale } from './booklet-locale';
+import type { BookletMessages } from './booklet-messages-types';
+import type { NarrativeModule } from './booklet-narrative-engine';
+export interface BookletLocaleBundle {
+    readonly messages: BookletMessages;
+    readonly genderWords: Record<BookletSex, PersonGenderWords>;
+    readonly genderPhrases?: GenderPhraseBundle;
+    readonly dateModule: BookletDateModule;
+    readonly placeModule: BookletPlaceModule;
+    readonly narrativeModule: NarrativeModule;
+}
+export declare class BookletLocaleNotLoadedError extends Error {
+    constructor(locale: BookletLocale);
+}
+/** Clears cached locale bundles (tests). */
+export declare function clearBookletLocaleCache(): void;
+/**
+ * Lazy-loads messages, gender, date/place, and narrative modules for one locale.
+ * Required before sync APIs (`getBookletMessages`, `collectBookletPersons`, …).
+ */
+export declare function ensureBookletLocale(locale?: BookletLocale): Promise<BookletLocale>;
+export declare function getBookletLocaleBundle(locale: BookletLocale): BookletLocaleBundle;
+export declare function isBookletLocaleLoaded(locale: BookletLocale): boolean;

package/dist/booklet/booklet-locale-modules-source.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/booklet/booklet-locale-modules.d.ts

@@ -0,0 +1,5 @@
+import type { BookletLocale } from './booklet-locale';
+export declare function getBookletDateModule(locale: BookletLocale): import("./booklet-date-factory").BookletDateModule;
+export declare function getBookletPlaceModule(locale: BookletLocale): import("./booklet-place-factory").BookletPlaceModule;
+export declare function getBookletDateModuleIfLoaded(locale?: BookletLocale): import("./booklet-date-factory").BookletDateModule;
+export declare function getBookletPlaceModuleIfLoaded(locale?: BookletLocale): import("./booklet-place-factory").BookletPlaceModule;

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

@@ -0,0 +1,15 @@
+/** Booklet narrative / PDF locales (aligned with gedcomts.com site languages). */
+export type BookletLocale = 'en' | 'fr' | 'de' | 'nl' | 'es' | 'zh' | 'it' | 'pt' | 'pl' | 'ar' | 'he';
+export declare const DEFAULT_BOOKLET_LOCALE: BookletLocale;
+export declare const BOOKLET_LOCALES: readonly BookletLocale[];
+/** Locales with full booklet copy (messages, dates, places, gender, narratives). */
+export declare const BOOKLET_LOCALES_IMPLEMENTED: readonly BookletLocale[];
+export declare const BOOKLET_RTL_LOCALES: readonly BookletLocale[];
+export declare function isBookletLocale(value: string | null | undefined): value is BookletLocale;
+export declare function resolveBookletLocale(locale?: BookletLocale): BookletLocale;
+export declare function isBookletLocaleRtl(locale?: BookletLocale): boolean;
+export declare function bookletTextDirection(locale?: BookletLocale): 'ltr' | 'rtl';
+/** BCP 47 tag for `toLocaleDateString` on the PDF cover. */
+export declare function bookletLocaleToBcp47(locale: BookletLocale): string;
+/** `Intl.Collator` / `localeCompare` tag for chapter name ordering. */
+export declare function bookletLocaleCompareTag(locale: BookletLocale): string;

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

@@ -0,0 +1,8 @@
+import type { PDFPage } from 'pdf-lib';
+import type { DrawGedcomTsLogoOptions, GedcomTsLogoLayout } from './booklet-logo';
+export declare function clearBookletLogoCache(): void;
+/** Loads SVG logo paths and draw helper (only when the cover logo is shown). */
+export declare function ensureBookletLogo(): Promise<void>;
+export declare function drawGedcomTsLogoOnPage(page: PDFPage, options?: DrawGedcomTsLogoOptions): Promise<GedcomTsLogoLayout>;
+export declare function getGedcomTsLogoPaths(): Promise<readonly string[]>;
+export declare function getGedcomTsLogoViewbox(): Promise<string>;

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

@@ -0,0 +1,15 @@
+import { type RGB } from 'pdf-lib';
+/** Couleur de marque gedcom-ts (#19196f), pour pdf-lib `rgb(...)`. */
+export declare const BOOKLET_BRAND_RGB: RGB;
+export interface GedcomTsLogoLayout {
+    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;

package/dist/booklet/booklet-messages-data.d.ts

@@ -0,0 +1,15 @@
+import type { BookletMessages } from './booklet-messages-types';
+import type { BookletLocale } from './booklet-locale';
+export declare const MESSAGES_EN: BookletMessages;
+export declare const MESSAGES_FR: BookletMessages;
+export declare const MESSAGES_DE: BookletMessages;
+export declare const MESSAGES_NL: BookletMessages;
+export declare const MESSAGES_ES: BookletMessages;
+export declare const MESSAGES_ZH: BookletMessages;
+export declare const MESSAGES_IT: BookletMessages;
+export declare const MESSAGES_PT: BookletMessages;
+export declare const MESSAGES_PL: BookletMessages;
+export declare const MESSAGES_AR: BookletMessages;
+export declare const MESSAGES_HE: BookletMessages;
+export declare const BOOKLET_MESSAGES: Record<BookletLocale, BookletMessages>;
+export declare function messagesForLocale(locale: BookletLocale): BookletMessages;

package/dist/booklet/booklet-messages-types.d.ts

@@ -0,0 +1,46 @@
+import type { BookletLocale } from './booklet-locale';
+export interface BookletMessages {
+    readonly unknownDates: string;
+    readonly unknownDate: string;
+    readonly chapterUnknownDates: string;
+    readonly generation1Title: string;
+    readonly generationTitle: (gen: number) => string;
+    readonly letterTitle: (letter: string) => string;
+    readonly chapterSubtitle: (count: number, dateRange: string) => string;
+    readonly chapterDateAbout: string;
+    readonly childrenNone: string;
+    readonly childrenMore: (n: number) => string;
+    readonly pagesEstimate: (n: number) => string;
+    readonly pagesEmpty: string;
+    readonly adviceDetailed120: string;
+    readonly adviceDetailed50: string;
+    readonly adviceSummary25: string;
+    readonly actTypeLabels: Partial<Record<string, string>>;
+    readonly spouseUnknown: string;
+    readonly timelineTitle: (chapterTitle: string) => string;
+    readonly timelineUnknownDates: string;
+    readonly pdf: {
+        readonly coverSubtitle: string;
+        readonly referencePerson: (name: string) => string;
+        readonly personCount: (n: number) => string;
+        readonly localNote: string;
+        readonly tocTitle: string;
+        readonly modeSummary: string;
+        readonly modeDetailed: string;
+        readonly contentHeading: string;
+        readonly introSummary: string;
+        readonly introDetailed: string;
+        readonly introSosa: string;
+        readonly familyHeading: (names: string) => string;
+        readonly generationLabel: (gen: number) => string;
+        readonly pageFooter: (n: number) => string;
+    };
+    readonly timeline: {
+        readonly legendBirth: string;
+        readonly legendDeath: string;
+        readonly legendMarriage: string;
+        readonly overflow: (n: number) => string;
+        readonly continuation: string;
+    };
+}
+export type { BookletLocale };

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

@@ -0,0 +1,7 @@
+import type { BookletLocale } from './booklet-locale';
+export type { BookletMessages } from './booklet-messages-types';
+export { ensureBookletLocale, clearBookletLocaleCache, isBookletLocaleLoaded } from './booklet-locale-loader';
+export declare function getBookletMessages(locale?: BookletLocale): import("./booklet-messages-types").BookletMessages;
+export declare function actTypeLabel(type: string, locale?: BookletLocale): string;
+/** Loads locale data then returns messages (convenience for async call sites). */
+export declare function loadBookletMessages(locale?: BookletLocale): Promise<import("./booklet-messages-types").BookletMessages>;

package/dist/booklet/booklet-narrative-en.d.ts

@@ -0,0 +1,10 @@
+import type { BookletPersonEntry } from './booklet-person';
+import type { BookletChapter, BookletDetailLevel, BookletFamilyUnit } from './booklet-structure';
+/** Chapter: narrative opening sentence. */
+export declare function buildChapterIntroNarrative(chapter: BookletChapter): string;
+/** Family sheet as narrative. */
+export declare function buildFamilyNarrative(family: BookletFamilyUnit, detailLevel: BookletDetailLevel): readonly string[];
+/** Condensed portrait: one flowing paragraph, name cited once. */
+export declare function buildPersonSummaryNarrative(entry: BookletPersonEntry): string;
+/** Detailed portrait: a few paragraphs, without redundant birth/death. */
+export declare function buildPersonDetailedNarratives(entry: BookletPersonEntry): readonly string[];

package/dist/booklet/booklet-narrative-engine.d.ts

@@ -0,0 +1,17 @@
+import type { BookletDateModule } from './booklet-date-factory';
+import type { BookletPlaceModule } from './booklet-place-factory';
+import type { BookletLocale } from './booklet-locale';
+import type { NarrativeStrings } from './booklet-narrative-i18n';
+import type { BookletPersonEntry } from './booklet-person';
+import type { BookletChapter, BookletDetailLevel, BookletFamilyUnit } from './booklet-structure';
+export interface NarrativeModule {
+    buildChapterIntroNarrative: (chapter: BookletChapter) => string;
+    buildFamilyNarrative: (family: BookletFamilyUnit, detailLevel: BookletDetailLevel) => readonly string[];
+    buildPersonSummaryNarrative: (entry: BookletPersonEntry) => string;
+    buildPersonDetailedNarratives: (entry: BookletPersonEntry) => readonly string[];
+}
+export declare function createNarrativeModule(locale: BookletLocale, strings: NarrativeStrings, deps: {
+    readonly dateModule: BookletDateModule;
+    readonly placeModule: BookletPlaceModule;
+    readonly unknownDates: string;
+}): NarrativeModule;

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

@@ -0,0 +1,10 @@
+import type { BookletPersonEntry } from './booklet-person';
+import type { BookletChapter, BookletDetailLevel, BookletFamilyUnit } from './booklet-structure';
+/** Chapitre : phrase d'ouverture narrative. */
+export declare function buildChapterIntroNarrative(chapter: BookletChapter): string;
+/** Fiche famille en récit. */
+export declare function buildFamilyNarrative(family: BookletFamilyUnit, detailLevel: BookletDetailLevel): readonly string[];
+/** Portrait condensé : un paragraphe fluide, nom cité une fois. */
+export declare function buildPersonSummaryNarrative(entry: BookletPersonEntry): string;
+/** Portrait détaillé : peu de paragraphes, sans redondance naissance/décès. */
+export declare function buildPersonDetailedNarratives(entry: BookletPersonEntry): readonly string[];