gedcom-ts 2026.5.3 → 2026.6.0

package/CHANGELOG.md

@@ -2,6 +2,60 @@
 
 All notable changes of gedcom-ts
 
+## [2026.6.0] - 2026-06-01
+
+### Added
+
+- **Multimédia GEDCOM 7 (`OBJE`)** : import et export complets des enregistrements `0 @O…@ OBJE` avec plusieurs `FILE`, `FORM`, `MEDI` (`AUDIO`, `PHOTO`, `VIDEO`, …), `PHRASE`, `TITL` et variantes `FILE`.`TRAN` (transcodage, WebVTT).
+- **`ReadGed.objeRecordsById`** : map des OBJE absorbés depuis le fichier (round-trip via `GedcomExportOptions.objeRecordsById`).
+- **Types et utilitaires OBJE** : `ObjeRecord`, `ObjeFileEntry`, `primaryObjeFileUri`, `parseStandaloneObjeBlock`, `formatObjeRecordBlock`, `guessMediFromForm`, `registerObjeRecord`.
+- **Entretiens audio / histoire orale** : actes `EVEN` + `TYPE Interview` (ou « Oral history ») avec lien `2 OBJE`, note de transcription (`2 NOTE`) et API dédiée — `createAudioInterviewAct`, `attachAudioInterviewToAct`, `editAct(act).asAudioInterview()`, `editAudioInterviewAct`.
+- **Détection et lecture** : `isAudioInterviewAct`, `isAudioInterviewEvenType`, `getAudioInterviewTranscription`, `getAudioInterviewMedia`, `getAudioInterviewObjeRecords`, `primaryAudioInterviewUri`, `nextObjeXrefId`.
+- **Constantes** : `GEDCOM_7_EVEN_TYPE_AUDIO_INTERVIEW`, `GEDCOM_7_EVEN_TYPE_ORAL_HISTORY`.
+- **`GedcomExportOptionsEdit.setObjeRecordsById`** / **`clearObjeRecordsById`**.
+- **Tests** : `parseStandaloneObje`, `guessMediFromForm`, `audioInterviewAct`, extension des specs export / import `maximal70`.
+
+### Changed
+
+- **Export OBJE** : émission de `MEDI` dérivé du MIME lorsque absent ; sérialisation multi-fichiers via `formatObjeRecordBlock`.
+- **Import** : `objePayloadById` remplacé par `objeRecordsById` (`PersonGedcomImportOptions`, `ActsByExtraction`).
+- **CI** : script `test:ci` (`build` puis `vitest run`) pour les tests qui lisent `dist/` ; `prepublishOnly` aligné.
+
+### Fixed
+
+- **GEDZIP** : inclusion des binaires locaux liés par pointeur `OBJE` (chemins résolus depuis `sourceUri` / `relativePath`).
+- **FORM audio** : reconnaissance de **WebM**, OGG, WAV, M4A, FLAC, etc. (`guessMediaFormFromUri`, `guessMediaFormFromFile`) ; affinage des exports `application/octet-stream` issus de l’UI.
+
+## [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

package/README.md

@@ -6,8 +6,10 @@
 - 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`)
+- attach **audio** and other media via GEDCOM 7 `OBJE` records (`MEDI AUDIO`, multi-`FILE`, `TRAN`)
+- model **oral history interviews** as `EVEN` acts with `OBJE` + transcription notes
 - geocode event places (OpenStreetMap / Nominatim) and group similar city names
-- generate a **genealogy booklet** as PDF (`gedcom-ts/booklet`, French narratives)
+- generate a **genealogy booklet** as PDF (`gedcom-ts/booklet`, 11 locales including RTL Arabic/Hebrew)
 
 ## Live demo
 
@@ -19,16 +21,17 @@ A graphical demo showcasing the public API (import a `.ged` / `.zip`, browse the
 - [Quick start](#quick-start)
 - [Geocoding places](#geocoding-places)
 - [Genealogy booklet (PDF)](#genealogy-booklet-pdf)
+- [Audio and oral history (GEDCOM 7)](#audio-and-oral-history-gedcom-7)
 - [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).
+- Current release **`2026.6.0`** — audio / OBJE / oral history. Version format **CalVer** `AAAA.M.micro` (e.g. `2026.6.0` = June 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)
+  - **`gedcom-ts/booklet`** — PDF livret (`pdf-lib` en peerDependency, chargé depuis `node_modules`)
 
 ## Installation
 
@@ -36,7 +39,13 @@ 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.
+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
 
@@ -193,19 +202,69 @@ 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.
+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. Collect persons with `collectBookletPersons` (`gedcom-ts/booklet`).
-3. Optionally preview size with `estimateBookletSize` + `groupBookletIntoChapters`.
-4. Build bytes with `generateGenealogyBookletPdf`, then `downloadBookletPdf` (browser).
+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,
@@ -217,23 +276,27 @@ 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);
+  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");
+  const size = estimateBookletSize(chapters, entries.length, families, "summary", "canvas", locale);
   console.log(size.label);
 
   const pdf = await generateGenealogyBookletPdf(
     entries,
     {
-      title: "Livret familial",
-      scopeLabel: "Ancêtres et descendance",
+      title: "Family booklet",
+      scopeLabel: "Ancestors and descendants",
       personCount: entries.length,
       referenceName: root ? personDisplayName(root) : undefined,
     },
@@ -241,10 +304,11 @@ async function exportBooklet(file: File) {
       detailLevel: "summary",
       timelineStyle: "canvas",
       coverLogo: true,
+      locale,
     },
   );
 
-  downloadBookletPdf(pdf, "livret.pdf");
+  downloadBookletPdf(pdf, "family-booklet.pdf");
 }
 ```
 
@@ -258,8 +322,9 @@ Use `scope: "all"` and `referencePerson: null` to include every individual in th
 | `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`.
+Helpers: `personDisplayName`, `buildBookletPersonEntry`, `sortBookletEntries`, `bookletSexFromPerson`, `DEFAULT_BOOKLET_LOCALE`, `BOOKLET_LOCALES`, `isBookletLocaleRtl`.
 
 ### `generateGenealogyBookletPdf` options
 
@@ -268,24 +333,27 @@ Helpers: `personDisplayName`, `buildBookletPersonEntry`, `sortBookletEntries`, `
 | `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`.
+`BookletPdfMeta`: `title`, `scopeLabel`, `personCount`, optional `referenceName` (usually translated in the host app).
 
 ### 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:
+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,
-  BOOKLET_BRAND_RGB,
+  ensureBookletLogo,
 } from "gedcom-ts/booklet";
 
 const doc = await PDFDocument.create();
 const page = doc.addPage();
-drawGedcomTsLogoOnPage(page, defaultCoverLogoOptions());
+await ensureBookletLogo();
+await drawGedcomTsLogoOnPage(page, defaultCoverLogoOptions());
 ```
 
 ### Booklet API cheat sheet
@@ -294,11 +362,72 @@ drawGedcomTsLogoOnPage(page, defaultCoverLogoOptions());
 | --- | --- |
 | Persons for the booklet | `collectBookletPersons` |
 | Chapters / families | `groupBookletIntoChapters`, `partnerNamesLabel` |
-| French narratives (custom UI) | `buildPersonSummaryNarrative`, `buildPersonDetailedNarratives`, `buildFamilyNarrative`, `buildChapterIntroNarrative` |
+| Localized 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` |
+| 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` |
+
+## Audio and oral history (GEDCOM 7)
+
+Since **`2026.6.0`**, gedcom-ts models audio according to [FamilySearch GEDCOM 7](https://gedcom.io/): external files referenced by **`OBJE`** records (`FILE` + `FORM` + optional `MEDI AUDIO` + `TRAN` for alternate formats or WebVTT). Text transcriptions belong in **`NOTE`** under the event, not inside `OBJE`.
+
+**Oral history pattern:** `1 EVEN` + `2 TYPE Interview` (or `Oral history`) + `2 OBJE @O…@` + `2 NOTE` (transcription).
+
+```ts
+import {
+  createAudioInterviewAct,
+  editAct,
+  ExportGedzipFile,
+  type Person,
+  type ReadGed,
+} from "gedcom-ts";
+
+async function addInterview(readGed: ReadGed, person: Person, mp3: File) {
+  const objeMap = new Map(readGed.objeRecordsById);
+
+  const { act, objeRecord } = createAudioInterviewAct(
+    {
+      description: "Entretien avec grand-mère",
+      participantIndis: [person.INDI],
+      ownerIndi: person.INDI,
+      audioFile: mp3,
+      transcription: "Bonjour, je m'appelle Marie…",
+      vttUri: "media/transcript.vtt", // optional FILE.TRAN on OBJE
+    },
+    readGed.persons,
+    objeMap,
+  );
+
+  person.acts.add(act);
+  if (objeRecord) {
+    objeMap.set(objeRecord.id, objeRecord);
+  }
+
+  await new ExportGedzipFile("my-tree", readGed.persons, {
+    extraTopLevelRecords: readGed.preservedTopLevelRecords,
+    objeRecordsById: objeMap,
+  }).download();
+}
+
+// enrich an existing act:
+editAct(act)
+  .asAudioInterview(readGed.persons, objeMap)
+  .setTranscription("Suite de l'entretien…")
+  .attachAudio({ audioUri: "https://example.org/rec.mp3", ownerIndi: person.INDI });
+```
+
+| Goal | API |
+| --- | --- |
+| Create interview act | `createAudioInterviewAct` |
+| Attach audio to act | `attachAudioInterviewToAct`, `editAct(act).asAudioInterview()` |
+| Detect imported interviews | `isAudioInterviewAct`, `isAudioInterviewEvenType` |
+| Read transcription / media | `getAudioInterviewTranscription`, `primaryAudioInterviewUri` |
+| OBJE round-trip | `readGed.objeRecordsById` → `objeRecordsById` in export options |
+| Low-level OBJE parse/emit | `parseStandaloneObjeBlock`, `formatObjeRecordBlock`, `guessMediFromForm` |
+| EVEN type constants | `GEDCOM_7_EVEN_TYPE_AUDIO_INTERVIEW`, `GEDCOM_7_EVEN_TYPE_ORAL_HISTORY` |
 
 ## API reference
 
@@ -349,7 +478,7 @@ try {
 
 #### `ReadGed`
 
-Result of an import. Top-level GEDCOM records not modeled into the typed graph (`OBJE`, `REPO`, `SOUR`, `SUBM`, …) are kept in order on `readGed.preservedTopLevelRecords` for round-trip export.
+Result of an import. Standalone `0 @O…@ OBJE` blocks with at least one `FILE` are parsed into **`objeRecordsById`** (multi-file, `MEDI`, `TRAN`). Other top-level records (`REPO`, `SOUR`, `SUBM`, …) stay on `preservedTopLevelRecords` for round-trip export.
 
 Notable members:
 
@@ -363,6 +492,7 @@ Notable members:
 | `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"`.                                                                                                                           |
+| `objeRecordsById: Map<number, ObjeRecord>` | Parsed `OBJE` records (audio, images, …) keyed by `@O{n}@`.                                                                                            |
 | `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`).                                                                                                            |
@@ -404,6 +534,7 @@ import { ExportGedcomFile, type ReadGed } from "gedcom-ts";
 function exportGed(readGed: ReadGed) {
   new ExportGedcomFile("my-tree", readGed.persons, {
     extraTopLevelRecords: readGed.preservedTopLevelRecords,
+    objeRecordsById: readGed.objeRecordsById,
     headLanguageTag: "fr-FR",
     headCopyright: "© 2026 Family Archive",
     headDestination: "https://gedcom.io/",
@@ -432,6 +563,7 @@ Options shared by both exporters:
 | Option                 | Effect                                                                                                   |
 | ---------------------- | -------------------------------------------------------------------------------------------------------- |
 | `extraTopLevelRecords` | Raw `0 …` blocks re-emitted before `SUBM` / `TRLR` (round-trip with `readGed.preservedTopLevelRecords`). |
+| `objeRecordsById`      | Full `OBJE` records (multi-`FILE`, `MEDI AUDIO`, `TRAN`) from `readGed.objeRecordsById`.                 |
 | `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).                                                               |
@@ -577,7 +709,7 @@ const payload = place.toGedcom7PlacPayload(); // "Paris, , Île-de-France, Franc
 
 #### `MultimediaFile`, `MultimediaFiles`
 
-Wraps either a local `File`, an external URI (`sourceUri`) or an OBJE pointer (`objeXrefId`) so the same model can survive a GED / ZIP round-trip.
+Wraps either a local `File`, an external URI (`sourceUri`) or an OBJE pointer (`objeXrefId`) so the same model can survive a GED / ZIP round-trip. See [Audio and oral history](#audio-and-oral-history-gedcom-7) for interview workflows.
 
 ```ts
 import { MultimediaFile, MultimediaFiles } from "gedcom-ts";
@@ -652,7 +784,8 @@ editDateAct(person.acts.list[0].dateAct!).setExactDate(1900, "JAN", 1);
 | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `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`.                                                                                            |
+| `editAct(act)` / `ActEdit`             | `setType`, `setIndis`, dates, place, EVEN fields, preserved lines, `notes()`, `multimedia()`, `asAudioInterview()`, `clearNotes`, `clearMultimedia`.                                                                        |
+| `editAudioInterviewAct(act)` / `AudioInterviewActEdit` | Oral-history facade: `attachAudio`, `setTranscription`, `setDescription`, `registerPendingObje`, `isAudioInterview`, …                                                                                    |
 | `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`.                                                                                            |
@@ -718,7 +851,7 @@ validateReadGed(readGed, {
 | 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`.                                                                                                                                    |
+| `editGedcomExportOptions(opts)` / `GedcomExportOptionsEdit`                                                                                                         | Fluent setters for `extraTopLevelRecords`, `objeRecordsById`, `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`.                                                                             |
@@ -765,12 +898,13 @@ const version = resolveDatasetVersion(headLines); // "7.0" | "5.5" | "unknown"
 
 #### `guessMediaFormFromUri(uri)`
 
-Best-effort media type detection from a path/URI (jpg, png, gif, webp, mp3, mp4, pdf, …). Used internally to fill `OBJE`.`FILE`.`FORM`.
+Best-effort media type detection from a path/URI or local `File` (`file.type` when set). Covers images, **audio** (mp3, **webm**, ogg, wav, m4a, flac, …), video, WebVTT, PDF. Used to fill `OBJE`.`FILE`.`FORM`. Pair with `guessMediFromForm` for `MEDI` (`AUDIO`, `PHOTO`, …). `refineGenericObjeForm` upgrades legacy `application/octet-stream` exports using the file extension.
 
 ```ts
-import { guessMediaFormFromUri } from "gedcom-ts";
+import { guessMediaFormFromUri, guessMediaFormFromFile } from "gedcom-ts";
 
-guessMediaFormFromUri("https://example.com/photo.jpg"); // "image/jpeg"
+guessMediaFormFromUri("media/recording.webm"); // "audio/webm"
+guessMediaFormFromFile(new File(["x"], "take.webm", { type: "audio/webm" })); // "audio/webm"
 ```
 
 #### `extractPersonNameVariants(personLines)` / `extractIndiAttributes(personLines)`
@@ -796,7 +930,7 @@ const primary = selectPrimaryNameVariant(person.nameVariants);
 
 #### `GEDCOM_LIBRARY_VERSION`
 
-CalVer string written in exported `HEAD`.`SOUR`.`VERS` (same value as the npm package version, e.g. `2026.5.2`).
+CalVer string written in exported `HEAD`.`SOUR`.`VERS` (same value as the npm package version, e.g. `2026.6.0`).
 
 ```ts
 import { GEDCOM_LIBRARY_VERSION } from "gedcom-ts";

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

@@ -1,3 +1,4 @@
+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 »… */

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

@@ -1,11 +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): BookletSizeEstimate;
-export declare function bookletSizeAdvice(personCount: number, detailLevel: BookletDetailLevel): string | null;
+/** 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

@@ -1,3 +1,4 @@
+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 {
@@ -11,13 +12,11 @@ export interface PersonGenderWords {
     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. */
+/** 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;
-/** « 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;
+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>;