gedcom-ts 2.1.0 → 2026.5.1

package/CHANGELOG.md

@@ -4,6 +4,97 @@ All notable changes of gedcom-ts
 
 ## [Unreleased]
 
+### Added
+
+- **`src/geocode/`** : géocodage Nominatim (`GET /search?q=…&format=jsonv2`), contexte arbre (`inferGeocodeContext`), ranking (`rankGeocodeCandidates`), harmonisation des lieux (`findHarmonizationClusters`, `applyGeocodeCandidateToActs`), utilitaires ville (`normalizeCityKey`, `findCanonicalCityLabel`). `fetch` et `User-Agent` configurables pour les tests.
+
+### Changed
+
+- **`getCityCoordinates`** : marqué `@deprecated` ; utilise la nouvelle API Nominatim (plus `search.php?city=` ni `XMLHttpRequest`).
+
+## [2026.5.0] - 2026-05-15
+
+### Versioning
+
+À partir de cette release, le numéro de version du paquet npm et de **`GEDCOM_LIBRARY_VERSION`** (`src/version.ts`, exporté dans `HEAD`.`SOUR`.`VERS`) suit un schéma **CalVer** :
+
+- format **`AAAA.M.micro`** (ex. **`2026.5.0`** = mai 2026, première publication de la série) ;
+- remplace l’ancien **semver** (`2.1.0`, `2.0.x`, …) pour les releases applicatives ;
+- la propriété `version` de `package.json` et `GEDCOM_LIBRARY_VERSION` doivent rester **identiques** (vérifié par `tests/version-package-sync.spec.ts`) ;
+- les branches de release peuvent porter le même libellé (ex. `2026.5.0`).
+
+Les entrées historiques du changelog conservent leurs numéros semver d’origine.
+
+### Highlights
+
+- Nouvelle couche **`src/dataset/`** : mutations du graphe `ReadGed`, opérations famille, validation typée, commandes sûres (`try*` / `CommandResult`) et clones.
+- Extension majeure de la **couche d’édition** (`*Edit`, factories, médias, variants de nom, attributs, options d’export).
+- **Round-trip des notes sous actes** corrigé (import `2 NOTE` / `3 CONT` après `DATE`, ordre d’export `ActLine`).
+- Refactor interne : médias centralisés, buffer des enregistrements préservés, `Person.clone` / `Act.clone`.
+
+### Added
+
+#### Dataset (`src/dataset/`)
+
+- **`readGedMutations`** : `addPersonToReadGed`, `removePersonFromReadGedByIndi` (mise à jour `mapPersons`, `persons`, lieux, `groupPartners`).
+- **`ReadGedEdit`** / `editReadGed` : `addPerson`, `removePersonByIndi`, `preserved()` → `PreservedTopLevelEdit` (`append`, `insertAt`, `replaceAt`, `removeAt`, `clear`).
+- **`graphOps`** : `nextFamilyId`, `createMarriageFamily`, `linkChildToFamily`, `unlinkChildFromFamily`, `removeFamilyReferencesFromDataset`.
+- **`CreateUnionFamilyOptions`** : `eventTag` sur `createMarriageFamily` / `tryCreateMarriageFamily` (défaut `MARR` ; aussi `ENGA`, `MARB`, `MARC`, `MARL`, `MARS`, `EVEN` + `CreateActInit`, etc.) ; constante **`GEDCOM_7_PAIR_UNION_EVENT_TAGS`**.
+- **`readGedCommands`** : `tryAddPersonToReadGed`, `tryRemovePersonFromReadGedByIndi`, `tryLinkChildToFamily`, `tryUnlinkChildFromFamily`, `tryCreateMarriageFamily` ; `validate*Command` ; **`CommandResult`** / `commandBlockingIssues`.
+- **`validation`** : `ModelConsistencyIssue` avec `code`, `severity` (`error` | `warn`), `validatePerson` / `validateReadGed` ; options `checkMarrParticipants`, `checkDuplicateIndis`, `checkFamcWithoutSpouses`, `checkFamsWithoutSpouses`, `checkDuplicateFamsEntries`, `checkAncestorCycles` ; `assertPersonConsistent` / `assertReadGedConsistent` avec `failOn`.
+- **`cloneModels`** : `clonePerson`, `cloneAct` (délèguent à `Person.clone` / `Act.clone`).
+
+#### Import / modèle
+
+- **`PreservedRecordsBuffer`** : encapsulation des blocs `0 …` préservés (`SplitGedcom` / `ReadGed.preservedTopLevelRecords`).
+- **`ReadGed.rehydratePlacesFromActs()`** : reconstruction de `placesMap` après édition manuelle du graphe.
+- **`importGedcomNote`** : `createNoteFromGedcomPayload`, `appendGedcomNoteSubline`, `isPersonLevelGedcomLine`, `isActLevelGedcomNoteLine`, `isGedcomNoteContinuationTag`.
+- **`registerTrackedMedia`** : chemins relatifs uniques pour médias personne / acte.
+- **`uriBasename`** : nom de fichier logique depuis une URI média.
+- **`clonePrimitives`** : briques de copie profonde partagées (dates, lieux, notes, médias, variants, attributs).
+- **`Person.clone(newIndi)`**, **`Act.clone()`** sur les classes domaine.
+
+#### Fluent edit layer (extensions)
+
+- **`factories`** : `createAct`, `createNote`, `createPersonStub`, `createPersonNameVariant`, `createIndiAttribute` (+ types `CreateActInit`, `CreatePersonStubInit`).
+- **`NoteEdit`** / `editNote` ; **`NotesEdit`** : `addNew`, `insertNewAt`, `removeNote`, `indexOfNote`.
+- **`ActMediaEdit`** / **`PersonMediaEdit`** / **`MultimediaFileEdit`** ; **`NameVariantsEdit`** / **`PersonNameVariantEdit`** ; **`IndiAttributesEdit`**.
+- **`ActsEdit`** : `addNew`, `insertNewAt`, `removeAct`, `indexOfAct`.
+- **`ActEdit`** : `notes()`, `multimedia()`, `clearNotes`, `clearMultimedia`.
+- **`PersonEdit`** : `multimedia()`, `nameVariants()`, `attributes()`, `appendFams`, `removeFamsAt`, `removeFamsById`, etc.
+- **`GedcomExportOptionsEdit`** / `editGedcomExportOptions` : `setExtraTopLevelRecords`, `setHeadCopyright`, `setHeadDestination`, `setHeadLanguageTag`, `setHeadSchemaTagDefs`, `clear*`.
+
+#### Public API (`src/index.ts`)
+
+- Réexport de tout le dataset, des commandes `try*`, des types de validation, `GEDCOM_7_PAIR_UNION_EVENT_TAGS`, `Gedcom7PairUnionEventTag`, `CreateUnionFamilyOptions`, `CommandResult`, etc.
+
+#### Tests
+
+- `tests/dataset/readGedCommands.spec.ts` : commandes et validations FAM optionnelles.
+- `tests/edit/extendedLayer.spec.ts` : ReadGed, graphe, export options, clones, validation, `removeFamilyReferencesFromDataset`.
+- `tests/edit/editApi.spec.ts` : facades étendues.
+- `tests/commons/Person.spec.ts` / `Act.spec.ts` : notes d’acte (`2 NOTE` / `3 CONT`, ordre après `DATE`).
+- `tests/export/GEDCOM.spec.ts` : round-trip ZIP avec note multi-lignes sous acte.
+- `tests/utils/uriBasename.spec.ts`.
+
+#### Documentation
+
+- README : section **Dataset editing** (ReadGed, graphe, clones, validation, commandes) ; table `ReadGed` mise à jour (`rehydratePlacesFromActs`, plus de `addPerson` direct sur `ReadGed`).
+
+### Changed
+
+- **`ReadGed`** : `addPerson` / `removePersonByIndi` retirés de la classe ; préférer `editReadGed` ou `addPersonToReadGed` / `removePersonFromReadGedByIndi`.
+- **`Person.addMultimedia` / `addMultimediaFromUri`** et **`Act.addMultimedia` / `addMultimediaFromUri`** : délégation à `registerTrackedMedia`.
+- **`SplitGedcom`** : liste préservée via `PreservedRecordsBuffer` au lieu d’un tableau interne brut.
+- **`package.json`** / **`package-lock.json`** : version **`2026.5.0`** (CalVer).
+- CI (`.gitlab-ci.yml`) : ajustements mineurs liés à la release.
+
+### Fixed
+
+- **Notes d’acte au réimport** : `parsePersonLine` n’attache plus les `NOTE` de niveau 2 au individu ; `convertToActs` traite `2 NOTE` et `3 CONC`/`CONT` **avant** les blocs `pendingAfterDate` / `Plac` / `Sdate`, ce qui évite de perdre les `3 CONT` lorsque l’export place la note après `DATE` (`ActLine`).
+- **`ReadGedEdit.addPerson`** : discrimination TypeScript correcte sur `CommandResult` (`r.ok === false`).
+- Alignement **`GEDCOM_LIBRARY_VERSION`** ↔ **`package.json`** pour la série `2026.5.0`.
+
 ## [2.1.0] - 2026-05-13
 
 ### Highlights

package/README.md

@@ -14,6 +14,7 @@ A graphical demo showcasing the public API (import a `.ged` / `.zip`, browse the
 ## 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
@@ -118,6 +119,7 @@ Notable members:
 | `getChildrenOfFamily(familyId)` | Children of a single family. |
 | `groupPartners()` | Rebuilds `partnersMap` / `childsMap` after editing links. |
 | `generateUniqueIndi()` | Next free `INDI` number for new persons. |
+| `rehydratePlacesFromActs()` | Rebuilds `placesMap` from act places (e.g. after manual graph edits). Use `editReadGed(readGed).addPerson(...)` to register persons so maps stay coherent. |
 
 ```ts
 import { ReadGed } from "gedcom-ts";
@@ -232,7 +234,7 @@ const occ = new IndiAttribute("OCCU", "Blacksmith", [
 
 #### `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`).
+`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, Identifier, type TypeAct } from "gedcom-ts";
@@ -267,9 +269,9 @@ const act = new Act(
 );
 ```
 
-#### `GEDCOM_7_ALL_EVENT_TAGS`, `GEDCOM_7_EVENT_SORT_ORDER`, `GEDCOM_7_EVENT_TAG_SET`, `Gedcom7EventTag`
+#### `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.
+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 {
@@ -394,12 +396,78 @@ editDateAct(person.acts.list[0].dateAct!).setExactDate(1900, "JAN", 1);
 
 | Helper / class | Purpose |
 | --- | --- |
-| `editPerson(person)` / `PersonEdit` | identity (`setLastname`, `setFirstnames`, `setSex`, `setSosa`), links (`setFamc`, `setFams`, `clearFams`, `appendFams`), name variants (`setNameVariants`), attributes (`setAttributes`), entry points to `acts()` and `notes()`. |
-| `editActs(acts)` / `ActsEdit` | `add`, `replaceAt`, `removeAt`, `clear`, `sortByDate`, `at(index)`. |
-| `editAct(act)` / `ActEdit` | `setType`, `setIndis`, `setDateAct`, `setSdateAct`, `setPlace`, `setEvenDescription`, `setEvenTypeLabel`, `setEventPhrases` / `appendEventPhrase` / `clearEventPhrases`, plus `setPreservedPrefix` / `Suffix` helpers. |
+| `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`, `replaceAt`, `removeAt`, `clear`. |
+| `editNotes(notes)` / `NotesEdit` | `add`, `addNew`, `insertAt`, `insertNewAt`, `replaceAt`, `removeAt`, `removeNote`, `removeLast`, `clear`, `at`, `indexOfNote`. |
+
+### Dataset editing: `ReadGed`, graph, clone, export options, validation
+
+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,
+});
+```
+
+#### 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
 
@@ -424,18 +492,32 @@ import { remainingTypesAct, Acts } from "gedcom-ts";
 const available = remainingTypesAct(new Acts());
 ```
 
-#### `getCityCoordinates(cityName, callback)`
+#### Geocoding (Nominatim)
 
-Queries OpenStreetMap’s Nominatim API and returns a list of candidate `Place` objects with coordinates. Browser-only (uses `XMLHttpRequest`).
+Place search uses the official Nominatim endpoint `GET https://nominatim.openstreetmap.org/search` with `q`, `format=jsonv2`, and `addressdetails=1` (not the legacy `search.php?city=` API). A `User-Agent` header is required (`gedcom-ts/<version> (genealogy library)` by default).
 
 ```ts
-import { getCityCoordinates } from "gedcom-ts";
+import {
+  inferGeocodeContext,
+  searchPlacesWithContext,
+  rankGeocodeCandidates,
+  findHarmonizationClusters,
+  applyGeocodeCandidateToActs,
+} from "gedcom-ts";
 
-getCityCoordinates("Paris", (places) => {
-  console.log(places[0]?.coordinate.latitude, places[0]?.coordinate.longitude);
-});
+const context = inferGeocodeContext(ged);
+const candidates = await searchPlacesWithContext("Valence", context);
+// candidates are ranked (French tree → Valence FR before ES)
+
+const clusters = findHarmonizationClusters(ged);
 ```
 
+For tests or Node without a global `fetch`, pass `fetchFn` in options. Low-level API: `searchPlaces(query, { countryCodes, limit, userAgent, fetchFn })`.
+
+#### `getCityCoordinates(cityName, callback)` (deprecated)
+
+Legacy callback API; delegates to `searchPlaces` and maps results to `Place[]`. Prefer `searchPlaces` / `searchPlacesWithContext`.
+
 #### `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.
@@ -479,7 +561,7 @@ const primary = selectPrimaryNameVariant(person.nameVariants);
 
 #### `GEDCOM_LIBRARY_VERSION`
 
-The library version embedded in the exported `HEAD`.`SOUR`.`VERS`. Kept aligned with the `version` field of `package.json` (a test enforces it).
+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";
@@ -514,6 +596,29 @@ async function importModifyExport(file: File) {
 }
 ```
 
+## 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

package/dist/commons/Act.d.ts

@@ -46,8 +46,13 @@ export declare class Act {
      * Suffixe `_1`, `_2`, … avant l’extension si le chemin est déjà pris sur cet acte.
      */
     addMultimedia(multimediaFile: MultimediaFile, ownerIndi?: number): void;
+    /**
+     * Média distant (URI) sans fichier local ; `ownerIndi` requis si {@link INDIS} est vide.
+     */
+    addMultimediaFromUri(sourceUri: string, ownerIndi?: number, objeXrefId?: number | null): void;
     removeMultimedia(index: number): void;
-    private mediaRelativePathsInUse;
+    /** Copie profonde de l’acte (nouvelle instance, mêmes valeurs). */
+    clone(): Act;
     updateType(typeAct: TypeAct): void;
     addIndis(INDIS: number[]): void;
     updatePlace(place: Place | null): void;
@@ -72,7 +77,9 @@ export declare class Acts {
 export declare class ActsByExtraction extends Acts {
     extractActsInfo(lines: string[], INDIS: number[], mapFiles: Map<string, File>, objePayloadById?: ReadonlyMap<number, {
         sourceUri: string;
-    }>, textualIndiXrefToIndi?: ReadonlyMap<string, number>): void;
+    }>, textualIndiXrefToIndi?: ReadonlyMap<string, number>, globalNotes?: Map<number, string[]>, importOptions?: {
+        notePointerToId?: ReadonlyMap<string, number>;
+    }): void;
     private convertToActs;
     private resolveTypeAct;
 }

package/dist/commons/Person.d.ts

@@ -51,8 +51,13 @@ export declare class Person {
      * Si le même nom existe déjà pour cet individu, suffixe `_1`, `_2`, etc. avant l’extension.
      */
     addMultimedia(multimediaFile: MultimediaFile): void;
+    /**
+     * Média distant (`FILE` / OBJE avec URI) sans fichier local : chemins relatifs uniques comme {@link addMultimedia}.
+     */
+    addMultimediaFromUri(sourceUri: string, objeXrefId?: number | null): void;
     deleteMultimedia(path: string): void;
-    private mediaRelativePathsInUse;
+    /** Copie profonde avec un nouvel `INDI` (actes via {@link Act.clone}, notes, médias, variants, attributs). */
+    clone(newIndi: number): Person;
     private createFirstnamesAndLastnameJson;
 }
 export declare class TreePerson extends Person {

package/dist/commons/clonePrimitives.d.ts

@@ -0,0 +1,17 @@
+import { DateAct } from "./DateAct";
+import { IndiAttribute } from "./IndiAttribute";
+import { MultimediaFile, MultimediaFiles } from "./MultimediaFile";
+import { Note, Notes } from "./Note";
+import { PersonNameVariant } from "./PersonNameVariant";
+import { Place } from "./Place";
+export declare function cloneDateAct(d: DateAct): DateAct;
+export declare function clonePlace(p: Place): Place;
+export declare function cloneNote(note: Note): Note;
+export declare function cloneNotesColl(notes: Notes): Notes;
+export declare function cloneMultimediaFile(m: MultimediaFile): MultimediaFile;
+export declare function cloneMultimediaBundle(files: readonly MultimediaFile[], relativePathRoot: string): {
+    files: MultimediaFiles;
+    map: Map<string, MultimediaFile>;
+};
+export declare function cloneNameVariant(v: PersonNameVariant): PersonNameVariant;
+export declare function cloneAttribute(a: IndiAttribute): IndiAttribute;

package/dist/commons/gedcomEventTags.d.ts

@@ -5,6 +5,13 @@ import { Identifier } from "./Identifier.enum";
  */
 export declare const GEDCOM_7_ALL_EVENT_TAGS: readonly [Identifier.ADOP, Identifier.BAPM, Identifier.BARM, Identifier.BASM, Identifier.BIRT, Identifier.BLES, Identifier.BURI, Identifier.CENS, Identifier.CHR, Identifier.CHRA, Identifier.CONF, Identifier.CREM, Identifier.DEAT, Identifier.EMIG, Identifier.EVEN, Identifier.FCOM, Identifier.GRAD, Identifier.IMMI, Identifier.NATU, Identifier.ORDN, Identifier.PROB, Identifier.RETI, Identifier.WILL, Identifier.ANUL, Identifier.DIV, Identifier.DIVF, Identifier.ENGA, Identifier.MARB, Identifier.MARC, Identifier.MARL, Identifier.MARR, Identifier.MARS];
 export type Gedcom7EventTag = (typeof GEDCOM_7_ALL_EVENT_TAGS)[number];
+/**
+ * Sous-ensemble des tags GEDCOM 7 typiquement utilisés pour lier deux personnes à une même famille `F`
+ * (fiançailles, bans, contrat, mariage, etc.). D’autres tags (`EVEN`, …) restent utilisables via
+ * {@link CreateUnionFamilyOptions.eventTag} s’ils figurent dans {@link GEDCOM_7_ALL_EVENT_TAGS}.
+ */
+export declare const GEDCOM_7_PAIR_UNION_EVENT_TAGS: readonly [Identifier.ENGA, Identifier.MARB, Identifier.MARC, Identifier.MARL, Identifier.MARR, Identifier.MARS];
+export type Gedcom7PairUnionEventTag = (typeof GEDCOM_7_PAIR_UNION_EVENT_TAGS)[number];
 /** Document order when two acts have no usable sortable date (`Acts.sortByDate`). */
 export declare const GEDCOM_7_EVENT_SORT_ORDER: readonly Gedcom7EventTag[];
 export declare const GEDCOM_7_EVENT_TAG_SET: ReadonlySet<string>;

package/dist/dataset/ReadGedEdit.d.ts

@@ -0,0 +1,27 @@
+import type { ReadGed } from "../import/ReadGed";
+import type { Person } from "../commons/Person";
+/**
+ * Édition des blocs `0 …` conservés pour round-trip (voir {@link ReadGed.preservedTopLevelRecords}).
+ */
+export declare class PreservedTopLevelEdit {
+    private readonly target;
+    constructor(target: ReadGed);
+    get value(): ReadonlyArray<string>;
+    append(block: string): this;
+    insertAt(index: number, block: string): this;
+    replaceAt(index: number, block: string): this;
+    removeAt(index: number): this;
+    clear(): this;
+}
+/**
+ * Facade d’édition sur un {@link ReadGed} (personnes + enregistrements préservés).
+ */
+export declare class ReadGedEdit {
+    private readonly target;
+    constructor(target: ReadGed);
+    get value(): ReadGed;
+    addPerson(person: Person): this;
+    removePersonByIndi(indi: number): boolean;
+    preserved(): PreservedTopLevelEdit;
+}
+export declare function editReadGed(readGed: ReadGed): ReadGedEdit;

package/dist/dataset/cloneModels.d.ts

@@ -0,0 +1,8 @@
+import type { Act } from "../commons/Act";
+import type { Person } from "../commons/Person";
+/** Copie profonde d’un {@link Act} (nouvelle instance, mêmes valeurs). */
+export declare function cloneAct(act: Act): Act;
+/**
+ * Copie profonde d’une {@link Person} avec un nouvel `INDI` (identité, actes, notes, médias, variants, attributs).
+ */
+export declare function clonePerson(person: Person, newIndi: number): Person;

package/dist/dataset/graphOps.d.ts

@@ -0,0 +1,29 @@
+import type { ReadGed } from "../import/ReadGed";
+import type { TypeAct } from "../commons/Act";
+import { Person } from "../commons/Person";
+import type { CreateActInit } from "../edit/factories";
+/** Prochain identifiant de famille `F` libre d'après les `FAMC` / `FAMS` du jeu. */
+export declare function nextFamilyId(persons: readonly Person[]): number;
+/** Rattache un enfant à une famille (`FAMC`). */
+export declare function linkChildToFamily(readGed: ReadGed, child: Person, familyId: number): void;
+/** Retire le rattachement `FAMC` d'un enfant. */
+export declare function unlinkChildFromFamily(readGed: ReadGed, child: Person): void;
+/**
+ * Retire toutes les références à une famille `familyId` : `FAMS` (toutes occurrences) et `FAMC` si égal.
+ * Puis {@link ReadGed.groupPartners}.
+ */
+export declare function removeFamilyReferencesFromDataset(readGed: ReadGed, familyId: number): void;
+export type CreateUnionFamilyOptions = {
+    /**
+     * Type d’acte créé sur chaque conjoint pour matérialiser l’union (défaut : {@link Identifier.MARR}).
+     * Doit appartenir à {@link GEDCOM_7_EVENT_TAG_SET} (ex. {@link Identifier.ENGA}, ou `EVEN` avec
+     * `CreateActInit.construction` pour une union civile / custom).
+     */
+    eventTag?: TypeAct;
+};
+/**
+ * Crée une famille `F` (nouvel id), rattache les deux conjoints en `FAMS` et ajoute le même type d’acte
+ * sur chacun (par défaut `MARR`). Voir {@link CreateUnionFamilyOptions} pour fiançailles, bans, etc.
+ * @returns l'identifiant interne de famille créé.
+ */
+export declare function createMarriageFamily(readGed: ReadGed, spouseA: Person, spouseB: Person, init?: CreateActInit | null, unionOptions?: CreateUnionFamilyOptions | null): number;

package/dist/dataset/index.d.ts

@@ -0,0 +1,9 @@
+export { addPersonToReadGed, removePersonFromReadGedByIndi } from "./readGedMutations";
+export { commandBlockingIssues, tryAddPersonToReadGed, tryCreateMarriageFamily, tryLinkChildToFamily, tryRemovePersonFromReadGedByIndi, tryUnlinkChildFromFamily, validateAddPersonCommand, validateCreateMarriageCommand, validateLinkChildCommand, validateUnlinkChildCommand, } from "./readGedCommands";
+export type { CommandFail, CommandOk, CommandResult } from "./readGedCommands";
+export { createMarriageFamily, linkChildToFamily, nextFamilyId, removeFamilyReferencesFromDataset, unlinkChildFromFamily, } from "./graphOps";
+export type { CreateUnionFamilyOptions } from "./graphOps";
+export { PreservedTopLevelEdit, ReadGedEdit, editReadGed } from "./ReadGedEdit";
+export { cloneAct, clonePerson } from "./cloneModels";
+export { assertPersonConsistent, assertReadGedConsistent, validatePerson, validateReadGed, } from "./validation";
+export type { AssertConsistencyOptions, ConsistencySeverity, ModelConsistencyIssue, ModelConsistencyIssueCode, ValidatePersonContext, ValidateReadGedOptions, } from "./validation";

package/dist/dataset/readGedCommands.d.ts

@@ -0,0 +1,46 @@
+import type { ReadGed } from "../import/ReadGed";
+import type { Person } from "../commons/Person";
+import type { CreateActInit } from "../edit/factories";
+import { type CreateUnionFamilyOptions } from "./graphOps";
+import type { ModelConsistencyIssue } from "./validation";
+export type CommandOk<T = void> = {
+    ok: true;
+    value: T;
+    warnings?: ModelConsistencyIssue[];
+};
+export type CommandFail = {
+    ok: false;
+    issues: ModelConsistencyIssue[];
+};
+export type CommandResult<T = void> = CommandOk<T> | CommandFail;
+/** Filtre les problèmes qui bloquent une commande (`severity === "error"`). */
+export declare function commandBlockingIssues(issues: readonly ModelConsistencyIssue[]): ModelConsistencyIssue[];
+/** Préconditions pour {@link tryAddPersonToReadGed} (sans effet de bord). */
+export declare function validateAddPersonCommand(readGed: ReadGed, person: Person): ModelConsistencyIssue[];
+/**
+ * Ajoute une personne au graphe après validation des préconditions.
+ * Effets en cas de succès : `mapPersons`, `persons`, lieux, `groupPartners()` (voir {@link addPersonToReadGed}).
+ */
+export declare function tryAddPersonToReadGed(readGed: ReadGed, person: Person): CommandResult;
+/**
+ * Retire une personne par `INDI`. Si absent, `ok: false` et aucune mutation.
+ */
+export declare function tryRemovePersonFromReadGedByIndi(readGed: ReadGed, indi: number): CommandResult;
+/** Préconditions pour rattacher un enfant à une famille. */
+export declare function validateLinkChildCommand(readGed: ReadGed, child: Person, familyId: number): ModelConsistencyIssue[];
+/**
+ * Rattache `child.FAMC = familyId` puis `groupPartners()`.
+ * Les avertissements (famille sans conjoints) n’empêchent pas la mutation ; ils sont renvoyés dans `warnings`.
+ */
+export declare function tryLinkChildToFamily(readGed: ReadGed, child: Person, familyId: number): CommandResult;
+/** Préconditions pour {@link tryUnlinkChildFromFamily}. */
+export declare function validateUnlinkChildCommand(readGed: ReadGed, child: Person): ModelConsistencyIssue[];
+/** Retire `FAMC` sur l’enfant puis `groupPartners()`. */
+export declare function tryUnlinkChildFromFamily(readGed: ReadGed, child: Person): CommandResult;
+/** Préconditions pour {@link tryCreateMarriageFamily}. */
+export declare function validateCreateMarriageCommand(readGed: ReadGed, spouseA: Person, spouseB: Person): ModelConsistencyIssue[];
+/**
+ * Crée une union (nouvel id `F`, actes MARR) après validation.
+ * @returns l’identifiant de famille en cas de succès.
+ */
+export declare function tryCreateMarriageFamily(readGed: ReadGed, spouseA: Person, spouseB: Person, init?: CreateActInit | null, unionOptions?: CreateUnionFamilyOptions | null): CommandResult<number>;

package/dist/dataset/readGedMutations.d.ts

@@ -0,0 +1,12 @@
+import type { ReadGed } from "../import/ReadGed";
+import { Person } from "../commons/Person";
+/**
+ * Ajoute une personne au graphe (met à jour `mapPersons`, `persons`, lieux, `groupPartners`).
+ * Si `person.INDI` n’est pas défini, un nouvel identifiant unique est attribué.
+ */
+export declare function addPersonToReadGed(readGed: ReadGed, person: Person): void;
+/**
+ * Retire une personne par `INDI` et purge les références à cet `INDI` dans les actes et notes du jeu.
+ * @returns `false` si aucune personne ne correspond.
+ */
+export declare function removePersonFromReadGedByIndi(readGed: ReadGed, indi: number): boolean;

package/dist/dataset/validation.d.ts

@@ -0,0 +1,36 @@
+import type { ReadGed } from "../import/ReadGed";
+import { Person } from "../commons/Person";
+export type ConsistencySeverity = "error" | "warn";
+export type ModelConsistencyIssueCode = "person_missing_indi" | "act_unknown_indi" | "note_unknown_indi" | "marr_missing_spouse_indi" | "duplicate_indi_in_dataset" | "add_person_already_registered" | "add_person_indi_conflict" | "remove_person_not_found" | "link_child_indi_missing" | "link_child_not_bound_to_readged" | "link_child_family_has_no_spouses" | "unlink_child_indi_missing" | "unlink_child_not_bound_to_readged" | "marriage_spouses_same_person" | "marriage_spouses_same_indi" | "marriage_spouse_indi_missing" | "marriage_spouse_not_in_readged" | "famc_family_without_spouses" | "fams_family_without_spouses" | "fams_duplicate_family_id" | "famc_ancestor_cycle";
+export type ModelConsistencyIssue = {
+    code: ModelConsistencyIssueCode;
+    severity: ConsistencySeverity;
+    message: string;
+    detail?: unknown;
+};
+export type ValidatePersonContext = {
+    knownIndis?: ReadonlySet<number>;
+    checkMarrParticipants?: boolean;
+};
+export type ValidateReadGedOptions = ValidatePersonContext & {
+    checkDuplicateIndis?: boolean;
+    /** `FAMC` pointant vers une famille sans entrée dans `partnersMap` ou liste vide. */
+    checkFamcWithoutSpouses?: boolean;
+    /** Chaque `FAMS` sans conjoints dans `partnersMap` (souvent import incomplet). */
+    checkFamsWithoutSpouses?: boolean;
+    /** Même identifiant de famille plusieurs fois dans `FAMS` d’une même personne. */
+    checkDuplicateFamsEntries?: boolean;
+    /** Cycle dans la remontée `FAMC` → parents (données impossibles biologiquement). */
+    checkAncestorCycles?: boolean;
+};
+export type AssertConsistencyOptions = {
+    failOn?: ConsistencySeverity;
+};
+/** Contrôles de base sur une personne (INDI, références d’actes). */
+export declare function validatePerson(person: Person, context?: ValidatePersonContext): ModelConsistencyIssue[];
+/** Agrège {@link validatePerson} pour toutes les personnes du graphe, plus les contrôles optionnels sur FAM. */
+export declare function validateReadGed(readGed: ReadGed, options?: ValidateReadGedOptions): ModelConsistencyIssue[];
+/** Lève une erreur si {@link validatePerson} retourne des problèmes selon `failOn` (défaut : seulement `error`). */
+export declare function assertPersonConsistent(person: Person, context?: ValidatePersonContext & AssertConsistencyOptions): void;
+/** Lève une erreur si {@link validateReadGed} retourne des problèmes selon `failOn` (défaut : seulement `error`). */
+export declare function assertReadGedConsistent(readGed: ReadGed, options?: ValidateReadGedOptions & AssertConsistencyOptions): void;

package/dist/edit/ActEdit.d.ts

@@ -1,6 +1,8 @@
 import { Act, type TypeAct } from "../commons/Act";
 import { DateAct } from "../commons/DateAct";
 import { Place } from "../commons/Place";
+import { ActMediaEdit } from "./ActMediaEdit";
+import { NotesEdit } from "./NotesEdit";
 /**
  * API d’édition cohérente autour d’un {@link Act} existant (mutation in-place).
  */
@@ -25,5 +27,11 @@ export declare class ActEdit {
     setPreservedSuffix(lines: readonly string[]): this;
     appendPreservedSuffixLine(line: string): this;
     clearPreservedSuffix(): this;
+    notes(): NotesEdit;
+    multimedia(): ActMediaEdit;
+    /** Supprime toutes les notes rattachées à l’acte. */
+    clearNotes(): this;
+    /** Supprime tous les médias rattachés à l’acte. */
+    clearMultimedia(): this;
 }
 export declare function editAct(act: Act): ActEdit;

package/dist/edit/ActMediaEdit.d.ts

@@ -0,0 +1,21 @@
+import { MultimediaFile } from "../commons/MultimediaFile";
+import type { Act } from "../commons/Act";
+import { MultimediaFileEdit } from "./MultimediaFileEdit";
+/**
+ * Médias rattachés à un {@link Act} : délègue à {@link Act.addMultimedia} / {@link Act.removeMultimedia}.
+ */
+export declare class ActMediaEdit {
+    private readonly target;
+    constructor(target: Act);
+    get value(): Act;
+    /**
+     * Crée un {@link MultimediaFile} à partir d'un fichier local, l'ajoute et renvoie sa facade.
+     */
+    addNewFromFile(file: File, ownerIndi?: number): MultimediaFileEdit;
+    addNewFromUri(uri: string, ownerIndi?: number, objeXrefId?: number | null): MultimediaFileEdit;
+    add(multimediaFile: MultimediaFile, ownerIndi?: number): this;
+    removeAt(index: number): this;
+    clear(): this;
+    at(index: number): MultimediaFileEdit;
+}
+export declare function editActMedia(act: Act): ActMediaEdit;

package/dist/edit/ActsEdit.d.ts

@@ -1,5 +1,6 @@
-import { Acts } from "../commons/Act";
+import { Act, Acts, type TypeAct } from "../commons/Act";
 import { ActEdit } from "./ActEdit";
+import { type CreateActInit } from "./factories";
 /**
  * API d’édition cohérente autour d’un {@link Acts}.
  */
@@ -7,7 +8,23 @@ export declare class ActsEdit {
     private readonly target;
     constructor(target: Acts);
     get value(): Acts;
+    /**
+     * Crée un {@link Act}, l’ajoute en fin de liste et renvoie sa facade d’édition.
+     */
+    addNew(type: TypeAct, init?: CreateActInit | null): ActEdit;
     add(act: Parameters<Acts["add"]>[0]): this;
+    /** Insère un acte existant à la position donnée (0 = début). */
+    insertAt(index: number, act: Act): this;
+    /**
+     * Crée un acte et l’insère à la position donnée.
+     */
+    insertNewAt(index: number, type: TypeAct, init?: CreateActInit | null): ActEdit;
+    /** Supprime le dernier acte s’il en existe au moins un. */
+    removeLast(): this;
+    /** Index de l’acte par identité de référence, ou `-1`. */
+    indexOfAct(act: Act): number;
+    /** Retire l’acte s’il appartient à la liste ; @returns si une entrée a été supprimée. */
+    removeAct(act: Act): boolean;
     replaceAt(index: number, act: Parameters<Acts["updateFromIndex"]>[0]): this;
     removeAt(index: number): this;
     clear(): this;