gedcom-ts 2.0.2 → 2026.5.0

package/README.md

@@ -2,13 +2,20 @@
 
 `gedcom-ts` is a browser-oriented TypeScript library to:
 
-- import genealogy data from GEDCOM (`.ged`) or ZIP (`.zip`)
-- work with a typed JSON model (persons, acts, notes, media, places)
-- export data back to GEDCOM (`.ged`) or ZIP (`.zip`)
+- import genealogy data from GEDCOM (`.ged`) or ZIP (`.zip` / `.gdz`)
+- 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`)
+
+## 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)**
 
 ## Project
 
 - 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
 
@@ -19,58 +26,144 @@ npm install gedcom-ts
 ## Runtime Requirements
 
 - modern browser runtime (`File`, `Blob`, `XMLHttpRequest`, `URL.createObjectURL`)
-- for pure Node.js usage, DOM polyfills are required
+- for pure Node.js usage, DOM polyfills are required (the library targets browsers)
 
-## Import
+## Quick start
 
 ```ts
-import { importGedFile } from "gedcom-ts";
+import { importGedFile, ExportGedzipFile } from "gedcom-ts";
 
-async function loadGenealogy(file: File) {
+async function roundTrip(file: File) {
   const readGed = await importGedFile(file);
-  return readGed.persons;
+  const persons = readGed.persons;
+
+  if (persons.length > 0) {
+    persons[0].lastname = persons[0].lastname.toUpperCase();
+  }
+
+  await new ExportGedzipFile("updated-tree", persons).download();
 }
 ```
 
-`importGedFile(file)` accepts:
+Typical workflow:
+
+1. import a file with `importGedFile` (or start from `createEmptyReadGed()`)
+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
+
+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`.
+
+### Importing a file
 
-- a GED file (`.ged`)
-- a ZIP containing one GED file + optional media files
+#### `importGedFile(file: File): Promise<ReadGed>`
 
-It returns a `ReadGed` instance with parsed persons, families, notes, acts, media and maps.
+Detects the format from the file MIME / extension and dispatches to the right reader.
 
-## Utilisation
+- accepts a single `.ged` file
+- accepts a `.zip` / `.gdz` archive containing one `.ged` + optional media files
+- throws `Error(IMPORT_ERR_ZIP_GED_UNREADABLE)` when the embedded `.ged` cannot be decoded (typical cause: password-protected ZIP)
 
 ```ts
-import { ReadGed, Person, createSosaMap } from "gedcom-ts";
+import { importGedFile } from "gedcom-ts";
 
-function buildViewModel(readGed: ReadGed, root: Person) {
-  const persons = readGed.persons;
-  const personByIndi = readGed.mapPersons;
-  const sosaMap = createSosaMap(root, readGed.partnersMap);
-  return { persons, personByIndi, sosaMap };
+const readGed = await importGedFile(fileInput.files![0]);
+console.log(readGed.persons.length, readGed.datasetVersion);
+```
+
+#### `createEmptyReadGed(options?): ReadGed`
+
+Creates an empty graph with the same runtime shape as a successful import (empty `persons`, initialized `mapPersons` / `partnersMap` / `childsMap` / `placesMap` / `mapFiles`). Use it to start a brand-new tree without parsing a file. `datasetVersion` is set to `"7.0"`.
+
+```ts
+import { createEmptyReadGed } from "gedcom-ts";
+
+const readGed = createEmptyReadGed();
+```
+
+#### `IMPORT_ERR_ZIP_GED_UNREADABLE: string`
+
+Sentinel error message thrown by `importGedFile` when a `.ged` inside a ZIP cannot be decoded (typically because the ZIP is password-protected). Compare with `error.message === IMPORT_ERR_ZIP_GED_UNREADABLE` to display a tailored message.
+
+```ts
+import { importGedFile, IMPORT_ERR_ZIP_GED_UNREADABLE } from "gedcom-ts";
+
+try {
+  await importGedFile(file);
+} catch (error) {
+  if (error instanceof Error && error.message === IMPORT_ERR_ZIP_GED_UNREADABLE) {
+    alert("Please unzip the archive manually and import the .ged file.");
+  }
 }
 ```
 
-Typical workflow:
+#### `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.
+
+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. |
 
-1. import a file with `importGedFile`
-2. read and update `Person` objects
-3. export as `.ged` or `.zip`
+```ts
+import { ReadGed } from "gedcom-ts";
 
-## Export
+function describe(readGed: ReadGed) {
+  return {
+    version: readGed.datasetVersion,
+    persons: readGed.persons.length,
+    places: readGed.placesMap.size,
+  };
+}
+```
 
-### GED (`.ged`)
+### Exporting
+
+#### `ExportGedcomFile`
+
+Writes a GEDCOM 7 (`.ged`) file. Three call signatures are supported:
 
 ```ts
-import { ExportGedcomFile, Person } from "gedcom-ts";
+new ExportGedcomFile(persons);
+new ExportGedcomFile(title, persons);
+new ExportGedcomFile(title, persons, options);
+```
 
-function exportGed(persons: Person[]) {
-  new ExportGedcomFile("my-tree", persons).download();
+`.download()` triggers a browser download. `.toString()` returns the GEDCOM text.
+
+```ts
+import { ExportGedcomFile, type ReadGed } from "gedcom-ts";
+
+function exportGed(readGed: ReadGed) {
+  new ExportGedcomFile("my-tree", readGed.persons, {
+    extraTopLevelRecords: readGed.preservedTopLevelRecords,
+    headLanguageTag: "fr-FR",
+    headCopyright: "© 2026 Family Archive",
+    headDestination: "https://gedcom.io/",
+    headSchemaTagDefs: [{ tag: "_FOO", uri: "https://example.com/foo" }],
+  }).download();
 }
 ```
 
-### ZIP (`.zip`) GED + media
+#### `ExportGedzipFile`
+
+Writes a `.zip` (GEDZIP) bundling the GEDCOM and all attached `MultimediaFile` payloads.
 
 ```ts
 import { ExportGedzipFile, Person } from "gedcom-ts";
@@ -80,37 +173,132 @@ async function exportZip(persons: Person[]) {
 }
 ```
 
-## Public API with Examples
+#### `GedcomExportOptions`
+
+Options shared by both exporters:
+
+| 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 …`. |
 
-Everything exported from `src/index.ts` is shown below with a minimal usage snippet.
+### Domain model
 
-### Person, Sex
+#### `Person`, `Sex`
 
 ```ts
 import { Person, Sex } from "gedcom-ts";
 
 const person = new Person();
 person.INDI = 1;
-person.SEX = Sex.M;
+person.SEX = Sex.M; // M | F | U | X
 person.firstnames = ["Jean"];
 person.lastname = "DUPONT";
+
+person.addMultimedia(/* MultimediaFile */);
+person.deleteMultimedia("1/photo.jpg");
+```
+
+Key fields: `INDI`, `sosa`, `SEX`, `firstnames`, `lastname`, `FAMC`, `FAMS`, `acts`, `notes`, `multimediaFiles`, `nameVariants`, `attributes`.
+
+#### `PersonGedcomImportOptions` (type)
+
+Optional hints consumed by `Person.createPersonJson` when re-parsing a single individual block (label-keyed pointers for `FAMS` / `FAMC` / `NOTE`, and standalone `OBJE` payloads). Useful when assembling a graph manually outside `ReadGed`.
+
+#### `PersonNameVariant`, `PersonNameTranslation`
+
+Lossless representation of every `1 NAME` block of an individual (type, `NPFX`/`GIVN`/`SURN`/… parts, `TRAN` translations). `Person.nameVariants` keeps them in order so alias / translation data survive an import → export round-trip.
+
+```ts
+import { PersonNameVariant, PersonNameTranslation } from "gedcom-ts";
+
+const variant = new PersonNameVariant("Jean /Dupont/", "BIRTH");
+variant.parts.push({ level: "2", tag: "GIVN", value: "Jean" });
+variant.translations.push(new PersonNameTranslation("ジャン /デュポン/", "jp"));
+```
+
+#### `IndiAttribute`, `IndiGedcomSubLine`
+
+Generic level-1 individual attributes (`FACT`, `DSCR`, `CAST`, `EDUC`, `OCCU`, `RELI`, `TITL`, `RESN`, …) with their sub-lines preserved (`IndiGedcomSubLine = { level; tag; value }`).
+
+```ts
+import { IndiAttribute } from "gedcom-ts";
+
+const occ = new IndiAttribute("OCCU", "Blacksmith", [
+  { level: "2", tag: "DATE", value: "1820" },
+]);
 ```
 
-### Act, Acts, TypeAct
+#### `Act`, `Acts`, `TypeAct`, `ActConstructionOptions`
+
+`Act` models an individual or family event (BIRT, MARR, etc.). `Acts` is the ordered collection on a `Person`. `TypeAct` is the union of every supported GEDCOM 7 event tag (= `Gedcom7EventTag`). Event-level notes live on `act.notes` (`2 NOTE` / `3 CONT` in GEDCOM); they are distinct from `person.notes` (`1 NOTE` on `INDI`) and round-trip through ZIP export/import.
 
 ```ts
-import { Act, Acts, TypeAct, Identifier } from "gedcom-ts";
+import { Act, Acts, Identifier, type TypeAct } from "gedcom-ts";
 
-const actType: TypeAct = Identifier.BIRT;
-const act = new Act(actType);
 const acts = new Acts();
-acts.add(act);
+const type: TypeAct = Identifier.BIRT;
+acts.add(new Act(type));
+acts.sortByDate();
+```
+
+`ActConstructionOptions` controls the extras when building an `Act` manually:
+
+```ts
+import { Act, DateAct, Identifier } from "gedcom-ts";
+
+const act = new Act(
+  Identifier.EVEN,
+  new DateAct("12 JAN 1901"),
+  null,
+  null,
+  null,
+  undefined,
+  undefined,
+  {
+    evenDescription: "Won a medal",
+    evenTypeLabel: "Award",
+    sdateAct: new DateAct("13 JAN 1901"),
+    eventPhrases: ["family gathering"],
+    preservedSubrecordPrefix: [],
+    preservedSubrecordSuffix: [],
+  },
+);
+```
+
+#### `GEDCOM_7_ALL_EVENT_TAGS`, `GEDCOM_7_EVENT_SORT_ORDER`, `GEDCOM_7_EVENT_TAG_SET`, `GEDCOM_7_PAIR_UNION_EVENT_TAGS`, `Gedcom7EventTag`, `Gedcom7PairUnionEventTag`
+
+Canonical lists of GEDCOM 7 event tags (`INDIVIDUAL_EVENT_STRUCTURE` ∪ `FAMILY_EVENT_STRUCTURE`, LDS ordinances excluded). Use them to build UI selects or guard custom logic. `GEDCOM_7_PAIR_UNION_EVENT_TAGS` lists tags commonly used when creating a family union via `createMarriageFamily` (`ENGA`, `MARB`, `MARC`, `MARL`, `MARR`, `MARS`).
+
+```ts
+import {
+  GEDCOM_7_ALL_EVENT_TAGS,
+  GEDCOM_7_EVENT_SORT_ORDER,
+  GEDCOM_7_EVENT_TAG_SET,
+  type Gedcom7EventTag,
+} from "gedcom-ts";
+
+const options: Gedcom7EventTag[] = [...GEDCOM_7_ALL_EVENT_TAGS];
+const isEvent = GEDCOM_7_EVENT_TAG_SET.has("MARR");
+const sorted = [...GEDCOM_7_EVENT_SORT_ORDER];
 ```
 
-### DateAct, Day, Month, dateToDateLine, days, months
+#### `DateAct`, `Day`, `Month`, `dateToDateLine`, `days`, `months`, `TypeDateActSimpleQualifier`
+
+GEDCOM dates with full GEDCOM 7 / 5.5 support, including `INT`, `EST`, `CAL`, `BET … AND …`, `FROM … TO …`, ISO `YYYY-MM-DD`, `3 PHRASE` under `DATE`, `3 TIME`, and a verbatim fallback for unparseable payloads.
 
 ```ts
-import { DateAct, Day, Month, dateToDateLine, days, months } from "gedcom-ts";
+import {
+  DateAct,
+  Day,
+  Month,
+  dateToDateLine,
+  days,
+  months,
+} from "gedcom-ts";
 
 const day: Day = 12;
 const month: Month = months[0]; // JAN
@@ -120,38 +308,53 @@ const formattedDate = dateAct.date;
 const knownDaysCount = days.length;
 ```
 
-### MultimediaFile, MultimediaFiles
+`TypeDateActSimpleQualifier` is the union of single-anchor qualifiers (`BEF | ABT | AFT | INT | EST | CAL`) accepted by `DateAct.updateQualifiedDate` and by `DateActEdit.setQualified`.
+
+#### `Place`, `CoordinateGPS`
 
 ```ts
-import { MultimediaFile, MultimediaFiles } from "gedcom-ts";
+import { Place, CoordinateGPS } from "gedcom-ts";
 
-const bucket = new MultimediaFiles();
-bucket.relativePath = "1/BIRT";
-bucket.add(new MultimediaFile(new File(["img"], "birth.jpg")));
+const place = new Place("Paris, FR", new CoordinateGPS(48.8566, 2.3522));
+place.setFromGedcom7PlacPayload("Paris, Île-de-France, France");
+const payload = place.toGedcom7PlacPayload(); // "Paris, , Île-de-France, France"
 ```
 
-### Place, CoordinateGPS
+`Place` understands the `City, County, State, Country` GEDCOM 7 list (1 to 4+ segments) and exposes `placPhrase` for `3 PHRASE` under `PLAC` (import + export).
+
+#### `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.
 
 ```ts
-import { Place, CoordinateGPS } from "gedcom-ts";
+import { MultimediaFile, MultimediaFiles } from "gedcom-ts";
 
-const place = new Place("Paris, FR", new CoordinateGPS(48.8566, 2.3522));
+const bucket = new MultimediaFiles();
+bucket.relativePath = "1/BIRT";
+bucket.add(new MultimediaFile(new File(["img"], "birth.jpg")));
+
+const remote = new MultimediaFile(undefined, "https://example.com/p.jpg");
+const isExportable = remote.hasExportablePayload();
 ```
 
-### Notes, Note, TypeNote
+#### `Note`, `Notes`, `TypeNote`
 
 ```ts
-import { Notes, Note, TypeNote, Identifier } from "gedcom-ts";
+import { Notes, Note, Identifier, type TypeNote } from "gedcom-ts";
 
 const typeNote: TypeNote = Identifier.CONT;
 const note = new Note();
 note.updateType(typeNote);
 note.updateLines(["first line", "second line"]);
+
 const notes = new Notes();
 notes.addNote(note);
+notes.removeFromIndex(0);
 ```
 
-### Identifier (preferred) / Identificator (deprecated)
+#### `Identifier` (and deprecated `Identificator`)
+
+Enum of every GEDCOM tag the library refers to (`INDI`, `BIRT`, `MARR`, `DATE`, `PLAC`, …). Prefer `Identifier`; `Identificator` is kept as a deprecated alias.
 
 ```ts
 import { Identifier } from "gedcom-ts";
@@ -159,93 +362,262 @@ import { Identifier } from "gedcom-ts";
 const birthTag = Identifier.BIRT;
 ```
 
-### ExportGedcomFile, ExportGedzipFile
+#### `EventsByYears`, `ActsByYear`
+
+Group acts by year, deduplicating per individual. Handy to build chronological timelines.
 
 ```ts
-import { ExportGedcomFile, ExportGedzipFile, Person } from "gedcom-ts";
+import { EventsByYears, ActsByYear } from "gedcom-ts";
 
-const persons: Person[] = [];
-new ExportGedcomFile("tree", persons).download();
-await new ExportGedzipFile("tree", persons).download();
+const grouped = new EventsByYears(person.acts.list);
+for (const bucket of grouped.events) {
+  console.log(bucket.year, bucket.list.length);
+}
+
+const yearBucket = new ActsByYear(1901);
 ```
 
-### ReadGed
+### Edit layer (in-place, chainable)
+
+Wrap an existing model object to mutate it with a fluent API. Every method returns `this`, so you can chain. `.value` exposes the underlying target.
 
 ```ts
-import { ReadGed } from "gedcom-ts";
+import { editPerson, editDateAct, DateAct } from "gedcom-ts";
 
-function useReadGed(readGed: ReadGed) {
-  return {
-    persons: readGed.persons,
-    places: readGed.placesMap,
-  };
-}
+editPerson(person)
+  .setLastname("Dupont")
+  .setFirstnames(["Jean", "Marie"])
+  .acts()
+  .at(0)
+  .setDateAct(new DateAct("1 JAN 1900"));
+
+editDateAct(person.acts.list[0].dateAct!).setExactDate(1900, "JAN", 1);
 ```
 
-### importGedFile
+| 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`. |
 
-```ts
-import { importGedFile } from "gedcom-ts";
+### Dataset editing: `ReadGed`, graph, clone, export options, validation
 
-const readGed = await importGedFile(fileInput.files![0]);
+Higher-level helpers complement the per-object edit facades:
+
+```ts
+import type { GedcomExportOptions } from "gedcom-ts";
+import {
+  createEmptyReadGed,
+  createPersonStub,
+  DateAct,
+  Sex,
+  editReadGed,
+  editGedcomExportOptions,
+  clonePerson,
+  cloneAct,
+  createMarriageFamily,
+  linkChildToFamily,
+  removeFamilyReferencesFromDataset,
+  addPersonToReadGed,
+  validateReadGed,
+  Identifier,
+  Act,
+} from "gedcom-ts";
+
+const readGed = createEmptyReadGed();
+const p = createPersonStub(readGed.generateUniqueIndi(), { sex: Sex.M, firstnames: ["Jean"], lastname: "Dupont" });
+editReadGed(readGed).addPerson(p);
+p.acts.add(new Act(Identifier.BIRT, new DateAct("1900")));
+
+editReadGed(readGed).preserved().append("0 @S42@ SOUR Custom");
+
+const opts: GedcomExportOptions = {};
+editGedcomExportOptions(opts)
+  .setHeadCopyright("© 2026")
+  .setExtraTopLevelRecords([...readGed.preservedTopLevelRecords]);
+
+const twin = clonePerson(p, readGed.generateUniqueIndi());
+const birthCopy = cloneAct(p.acts.list[0]!);
+
+// const fam = createMarriageFamily(readGed, spouseA, spouseB, { dateAct: new DateAct("1 JAN 2000") }, { eventTag: Identifier.ENGA });
+// linkChildToFamily(readGed, child, fam);
+// removeFamilyReferencesFromDataset(readGed, fam);
+
+validateReadGed(readGed, {
+  checkMarrParticipants: true,
+  checkFamcWithoutSpouses: true,
+  checkFamsWithoutSpouses: true,
+  checkDuplicateFamsEntries: true,
+  checkAncestorCycles: true,
+});
 ```
 
-### createSosaMap
+#### Commands (invariants before mutation)
+
+`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. |
+
+### Utilities
+
+#### `createSosaMap(root, partnersMap)`
+
+Computes a Sosa numbering (Ahnentafel) starting at `root` (Sosa 1) and recursively walking ancestors via `partnersMap`.
 
 ```ts
 import { createSosaMap, Person } from "gedcom-ts";
 
-const root = new Person();
-root.INDI = 1;
-const sosaMap = createSosaMap(root, new Map());
+const sosaMap = createSosaMap(root, readGed.partnersMap);
+// e.g. sosaMap.get(root.INDI) === 1
 ```
 
-### remainingTypesAct
+#### `remainingTypesAct(acts, actToUpdate?)`
+
+Returns the list of event types still allowed for a person’s `Acts`, enforcing the “unique per individual” rule for `BIRT` / `DEAT` / `BURI` / `CHR` while keeping every other tag selectable. Pass the currently edited act as `actToUpdate` so its own type stays in the list when re-opening a form.
 
 ```ts
 import { remainingTypesAct, Acts } from "gedcom-ts";
 
-const availableTypes = remainingTypesAct(new Acts());
+const available = remainingTypesAct(new Acts());
 ```
 
-### EventsByYears, ActsByYear
+#### `getCityCoordinates(cityName, callback)`
+
+Queries OpenStreetMap’s Nominatim API and returns a list of candidate `Place` objects with coordinates. Browser-only (uses `XMLHttpRequest`).
 
 ```ts
-import { EventsByYears, ActsByYear } from "gedcom-ts";
+import { getCityCoordinates } from "gedcom-ts";
 
-const grouped = new EventsByYears([]);
-const yearBucket = new ActsByYear(1901);
-const eventsByYear = grouped.events;
-const selectedYear = yearBucket.year;
+getCityCoordinates("Paris", (places) => {
+  console.log(places[0]?.coordinate.latitude, places[0]?.coordinate.longitude);
+});
 ```
 
-## End-to-End Example
+#### `resolveDatasetVersion(headerLines)` / `GedcomDatasetVersion`
+
+Inspects the lines of a `0 HEAD` block and returns `"7.0"`, `"5.5"` or `"unknown"`. Useful to branch UI behaviour for legacy datasets.
 
 ```ts
-import { importGedFile, ExportGedzipFile } from "gedcom-ts";
+import { resolveDatasetVersion } from "gedcom-ts";
+
+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`.
+
+```ts
+import { guessMediaFormFromUri } from "gedcom-ts";
+
+guessMediaFormFromUri("https://example.com/photo.jpg"); // "image/jpeg"
+```
+
+#### `extractPersonNameVariants(personLines)` / `extractIndiAttributes(personLines)`
+
+Low-level parsers used by `Person.createPersonJson`. They turn the raw GEDCOM lines of a single `INDI` record into structured `PersonNameVariant[]` / `IndiAttribute[]`. Reuse them when parsing custom GEDCOM fragments outside `ReadGed`.
+
+```ts
+import { extractPersonNameVariants, extractIndiAttributes } from "gedcom-ts";
+
+const variants = extractPersonNameVariants(rawIndiLines);
+const attributes = extractIndiAttributes(rawIndiLines);
+```
+
+#### `selectPrimaryNameVariant(variants)`
+
+Picks the most relevant `1 NAME` block: priority to `2 TYPE BIRTH`, then to a name with a `/surname/` payload, otherwise the first variant.
+
+```ts
+import { selectPrimaryNameVariant } from "gedcom-ts";
+
+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.
+
+```ts
+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) {
-    persons[0].lastname = persons[0].lastname.toUpperCase();
+    editPerson(persons[0])
+      .setLastname(persons[0].lastname.toUpperCase())
+      .acts()
+      .at(0)
+      .setDateAct(new DateAct("1 JAN 1900"));
   }
 
   await new ExportGedzipFile("updated-tree", persons).download();
 }
 ```
 
-## Error Handling
+## 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
-import { importGedFile } from "gedcom-ts";
+import { importGedFile, IMPORT_ERR_ZIP_GED_UNREADABLE } from "gedcom-ts";
 
 try {
   const readGed = await importGedFile(file);
-  const personsCount = readGed.persons.length;
+  console.log(readGed.persons.length);
 } catch (error) {
-  console.error("GED import failed:", error);
+  if (error instanceof Error && error.message === IMPORT_ERR_ZIP_GED_UNREADABLE) {
+    console.error("Encrypted ZIP: please extract the .ged manually.");
+  } else {
+    console.error("GED import failed:", error);
+  }
 }
 ```
-