.beb and .json serialization of the document

src/bedit_core/serialization/json_codec.py

@@ -0,0 +1,36 @@
+"""Versioned UTF-8 JSON codec used by the serialization API."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Mapping
+
+FORMAT_NAME = "json"
+FILE_FORMAT_VERSION = 1
+
+
+def load_data(path: Path) -> tuple[int, Mapping[str, Any]]:
+    """Read JSON and return its file-layout version and raw root object.
+
+    JSON files without ``file_format_version`` are interpreted as version 1.
+    Schema conversion and migrations are intentionally handled by higher
+    layers.
+    """
+    try:
+        with path.open("r", encoding="utf-8") as stream:
+            data = json.load(stream)
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise ValueError(f"could not read JSON document {path}: {exc}") from exc
+    if not isinstance(data, Mapping):
+        raise ValueError(f"JSON document {path} must contain an object at its root")
+    version = data.get("file_format_version", 1)
+    return version, data
+
+
+def save_data(data: Mapping[str, Any], path: Path) -> None:
+    """Write raw document data as indented UTF-8 JSON at the current version."""
+    output = {"file_format_version": FILE_FORMAT_VERSION, **data}
+    with path.open("w", encoding="utf-8") as stream:
+        json.dump(output, stream, ensure_ascii=False, indent=2)
+        stream.write("\n")