xmindpy 0.1.0__tar.gz

xmindpy-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+venv/
+env/
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# uv
+.uv-cache/
+
+# IDE
+.vscode/
+.idea/
+.DS_Store

xmindpy-0.1.0/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 Funnlink
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This project is a rewrite of https://github.com/zhuifengshen/xmind (MIT licensed).
+Original work Copyright (c) 2018 Devin (1324556701@qq.com).

xmindpy-0.1.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.5
+Name: xmindpy
+Version: 0.1.0
+Summary: Modern Python SDK for XMind 2020+ JSON format. A clean rewrite of zhuifengshen/xmind for the new file format.
+Project-URL: Homepage, https://github.com/innotools/xmindpy
+Project-URL: Repository, https://github.com/innotools/xmindpy
+Project-URL: Issues, https://github.com/innotools/xmindpy/issues
+Author-email: Funnlink <edward@innoshop.com>
+License: MIT
+License-File: LICENSE
+Keywords: json,mind-map,xmind,xmind-2020,思维导图
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# xmindpy
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+Modern Python SDK for creating, reading, and editing **XMind 2020+** mind map files (JSON format).
+
+This is a clean rewrite of [zhuifengshen/xmind](https://github.com/zhuifengshen/xmind) — the original library only supports the legacy XMind 2.0 XML format and **cannot produce files that XMind 2020/2022/2024 can open**. This fork replaces the XML DOM core with native Python objects and emits the JSON-based file format that modern XMind expects.
+
+## Install
+
+```bash
+pip install xmindpy
+```
+
+## Quick start
+
+```python
+from xmindpy import Workbook, Topic
+
+wb = Workbook()
+sheet = wb.create_sheet("Project Plan")
+root = Topic("Project Plan")
+root.add(Topic("Research"))
+root.add(Topic("Design"))
+root.add(Topic("Build"))
+sheet.root_topic = root
+
+wb.save("plan.xmind")
+```
+
+Open `plan.xmind` in XMind 2020 or later — it just works.
+
+## Loading
+
+```python
+from xmindpy import load_workbook
+
+wb = load_workbook("plan.xmind")
+for sheet in wb.sheets:
+    print(sheet.title)
+    print(sheet.root_topic.title)
+```
+
+## Convert legacy `.xmind` files (XML format)
+
+```python
+from xmindpy import convert
+convert.to_json("legacy.xmind", "modern.xmind")
+```
+
+## API
+
+| Class | Purpose |
+|-------|---------|
+| `Workbook` | Container for one or more sheets |
+| `Sheet` | One mind map (tab) in the workbook |
+| `Topic` | A node in the mind map; has children, notes, labels, markers |
+| `load_workbook(path)` | Load an `.xmind` file (auto-detects JSON or legacy XML format) |
+| `convert.to_json(src, dst)` | Migrate a legacy XML-format `.xmind` to modern JSON format |
+
+## File format
+
+The generated `.xmind` is a ZIP with:
+
+| File | Purpose |
+|------|---------|
+| `mimetype` | Always `application/vnd.xmind.workbook` |
+| `content.json` | Top-level array of sheets |
+| `metadata.json` | `dataStructureVersion: "3"`, `layoutEngineVersion: "5"` |
+| `manifest.json` | File-entry registry (`file-entries` object, `media-type` kebab-case) |
+| `Thumbnails/thumbnail.png` | 1×1 transparent PNG (required by some parsers) |
+
+This matches the format documented at the [XMind Wiki](https://github.com/xmindltd/xmind/wiki/XMindFileFormat).
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+Forked from [zhuifengshen/xmind](https://github.com/zhuifengshen/xmind) by Devin (MIT).

xmindpy-0.1.0/README.md

@@ -0,0 +1,79 @@
+# xmindpy
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+Modern Python SDK for creating, reading, and editing **XMind 2020+** mind map files (JSON format).
+
+This is a clean rewrite of [zhuifengshen/xmind](https://github.com/zhuifengshen/xmind) — the original library only supports the legacy XMind 2.0 XML format and **cannot produce files that XMind 2020/2022/2024 can open**. This fork replaces the XML DOM core with native Python objects and emits the JSON-based file format that modern XMind expects.
+
+## Install
+
+```bash
+pip install xmindpy
+```
+
+## Quick start
+
+```python
+from xmindpy import Workbook, Topic
+
+wb = Workbook()
+sheet = wb.create_sheet("Project Plan")
+root = Topic("Project Plan")
+root.add(Topic("Research"))
+root.add(Topic("Design"))
+root.add(Topic("Build"))
+sheet.root_topic = root
+
+wb.save("plan.xmind")
+```
+
+Open `plan.xmind` in XMind 2020 or later — it just works.
+
+## Loading
+
+```python
+from xmindpy import load_workbook
+
+wb = load_workbook("plan.xmind")
+for sheet in wb.sheets:
+    print(sheet.title)
+    print(sheet.root_topic.title)
+```
+
+## Convert legacy `.xmind` files (XML format)
+
+```python
+from xmindpy import convert
+convert.to_json("legacy.xmind", "modern.xmind")
+```
+
+## API
+
+| Class | Purpose |
+|-------|---------|
+| `Workbook` | Container for one or more sheets |
+| `Sheet` | One mind map (tab) in the workbook |
+| `Topic` | A node in the mind map; has children, notes, labels, markers |
+| `load_workbook(path)` | Load an `.xmind` file (auto-detects JSON or legacy XML format) |
+| `convert.to_json(src, dst)` | Migrate a legacy XML-format `.xmind` to modern JSON format |
+
+## File format
+
+The generated `.xmind` is a ZIP with:
+
+| File | Purpose |
+|------|---------|
+| `mimetype` | Always `application/vnd.xmind.workbook` |
+| `content.json` | Top-level array of sheets |
+| `metadata.json` | `dataStructureVersion: "3"`, `layoutEngineVersion: "5"` |
+| `manifest.json` | File-entry registry (`file-entries` object, `media-type` kebab-case) |
+| `Thumbnails/thumbnail.png` | 1×1 transparent PNG (required by some parsers) |
+
+This matches the format documented at the [XMind Wiki](https://github.com/xmindltd/xmind/wiki/XMindFileFormat).
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+Forked from [zhuifengshen/xmind](https://github.com/zhuifengshen/xmind) by Devin (MIT).

xmindpy-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "xmindpy"
+version = "0.1.0"
+description = "Modern Python SDK for XMind 2020+ JSON format. A clean rewrite of zhuifengshen/xmind for the new file format."
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+    {name = "Funnlink", email = "edward@innoshop.com"},
+]
+keywords = ["xmind", "mind-map", "思维导图", "json", "xmind-2020"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: OS Independent",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/innotools/xmindpy"
+Repository = "https://github.com/innotools/xmindpy"
+Issues = "https://github.com/innotools/xmindpy/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["xmindpy"]
+
+[tool.hatch.build.targets.sdist]
+include = ["xmindpy", "README.md", "LICENSE"]
+
+[tool.uv]
+package = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+]

xmindpy-0.1.0/xmindpy/__init__.py

@@ -0,0 +1,8 @@
+"""xmindpy — modern Python SDK for XMind 2020+ JSON format."""
+
+from .workbook import Workbook, Sheet, Topic
+from .loader import load_workbook
+from . import convert
+
+__all__ = ["Workbook", "Sheet", "Topic", "load_workbook", "convert"]
+__version__ = "0.1.0"

xmindpy-0.1.0/xmindpy/convert.py

@@ -0,0 +1,92 @@
+"""Convert legacy XMind 2.0 XML-format `.xmind` files to the modern JSON format."""
+
+from __future__ import annotations
+
+import json
+import zipfile
+from xml.etree import ElementTree as ET
+
+from .workbook import Workbook, Sheet, Topic
+from .saver import save_workbook
+
+XML_NS = "{urn:xmind:xmap:xmlns:content:2.0}"
+
+
+def to_json(src_path: str, dst_path: str) -> Workbook:
+    """Read ``src_path`` (legacy XML) and save it as ``dst_path`` (modern JSON).
+
+    Returns the migrated :class:`Workbook` so the caller can inspect it.
+    """
+    workbook = _read_legacy_xml(src_path)
+    save_workbook(workbook, dst_path)
+    return workbook
+
+
+def _read_legacy_xml(path: str) -> Workbook:
+    """Best-effort XML→JSON parser for the XMind 2.0 schema.
+
+    Supports title, nested ``topic`` children, and ``notes/plain``. Other fields
+    (markers, labels, relationships, hyperlinks) are best-effort: when present
+    in the XML they are preserved; otherwise they are dropped.
+    """
+    with zipfile.ZipFile(path, "r") as z:
+        with z.open("content.xml") as f:
+            tree = ET.parse(f)
+    root = tree.getroot()
+
+    workbook = Workbook()
+    for sheet_el in root.findall(f"{XML_NS}sheet"):
+        title_el = sheet_el.find(f"{XML_NS}title")
+        title = title_el.text if title_el is not None else "Sheet"
+        topic_el = sheet_el.find(f"{XML_NS}topic")
+        root_topic = _topic_from_xml(topic_el) if topic_el is not None else Topic(title=title)
+        sheet = Sheet(title=title, root_topic=root_topic)
+        workbook.sheets.append(sheet)
+    return workbook
+
+
+def _topic_from_xml(topic_el: ET.Element) -> Topic:
+    title_el = topic_el.find(f"{XML_NS}title")
+    title = title_el.text if title_el is not None else ""
+
+    topic = Topic(title=title or "", id=topic_el.get("id", ""))
+
+    children_el = topic_el.find(f"{XML_NS}children")
+    if children_el is not None:
+        topics_el = children_el.find(f"{XML_NS}topics")
+        if topics_el is not None:
+            for child_el in topics_el.findall(f"{XML_NS}topic"):
+                topic.children.append(_topic_from_xml(child_el))
+
+    notes_el = topic_el.find(f"{XML_NS}notes")
+    if notes_el is not None:
+        plain_el = notes_el.find(f"{XML_NS}plain")
+        if plain_el is not None and plain_el.text:
+            topic.notes = plain_el.text
+
+    markers_el = topic_el.find(f"{XML_NS}marker-refs")
+    if markers_el is not None:
+        for marker_el in markers_el.findall(f"{XML_NS}marker-ref"):
+            mid = marker_el.get("marker-id")
+            if mid:
+                topic.markers.append(mid)
+
+    labels_el = topic_el.find(f"{XML_NS}labels")
+    if labels_el is not None:
+        for label_el in labels_el.findall(f"{XML_NS}label"):
+            if label_el.text:
+                topic.labels.append(label_el.text)
+
+    return topic
+
+
+def to_legacy_xml(src_path: str, dst_path: str) -> None:
+    """Inverse of :func:`to_json`: write the workbook back as legacy XML.
+
+    Useful if you still need to open the file with very old XMind builds (<2018)
+    that predate the JSON format.
+    """
+    raise NotImplementedError(
+        "Round-tripping back to legacy XML is not implemented. "
+        "Modern XMind (>= 2018) supports the JSON format produced by save_workbook()."
+    )

xmindpy-0.1.0/xmindpy/loader.py

@@ -0,0 +1,64 @@
+"""Load an XMind workbook from a `.xmind` file (auto-detects JSON or legacy XML)."""
+
+from __future__ import annotations
+
+import json
+import zipfile
+from typing import IO
+
+from .workbook import Workbook
+
+
+def _is_json_format(names: list[str]) -> bool:
+    return "content.json" in names
+
+
+def _is_xml_format(names: list[str]) -> bool:
+    return "content.xml" in names
+
+
+def load_workbook(path: str) -> Workbook:
+    """Load an `.xmind` file. Supports modern JSON format and legacy XML."""
+    with zipfile.ZipFile(path, "r") as z:
+        names = z.namelist()
+        if _is_json_format(names):
+            return _load_json(z)
+        if _is_xml_format(names):
+            raise UnsupportedFormatError(
+                "Detected legacy XMind 2.0 XML format. "
+                "Use xmindpy.convert.to_json() to migrate first."
+            )
+        raise ValueError(f"Unrecognized .xmind archive (members: {names[:5]})")
+
+
+def load_from_stream(stream: IO[bytes]) -> Workbook:
+    import io
+
+    with zipfile.ZipFile(io.BytesIO(stream.read()), "r") as z:
+        names = z.namelist()
+        if _is_json_format(names):
+            return _load_json(z)
+        if _is_xml_format(names):
+            raise UnsupportedFormatError(
+                "Detected legacy XMind 2.0 XML format. "
+                "Use xmindpy.convert.to_json() to migrate first."
+            )
+        raise ValueError(f"Unrecognized .xmind archive (members: {names[:5]})")
+
+
+def _load_json(z: zipfile.ZipFile) -> Workbook:
+    content_bytes = z.read("content.json")
+    content = json.loads(content_bytes.decode("utf-8"))
+    if not isinstance(content, list):
+        raise ValueError(
+            f"Invalid content.json: expected array of sheets, got {type(content).__name__}"
+        )
+    workbook = Workbook.from_content(content)
+    if "metadata.json" in z.namelist():
+        metadata = json.loads(z.read("metadata.json").decode("utf-8"))
+        workbook.metadata = metadata
+    return workbook
+
+
+class UnsupportedFormatError(Exception):
+    """Raised when the input file uses a format this library does not parse directly."""

xmindpy-0.1.0/xmindpy/saver.py

@@ -0,0 +1,70 @@
+"""Save a Workbook as a modern XMind 2020+ JSON-format `.xmind` file."""
+
+from __future__ import annotations
+
+import json
+import zipfile
+from datetime import datetime, timezone
+from typing import IO, Any
+
+from .workbook import Workbook
+
+MIMETYPE = "application/vnd.xmind.workbook"
+
+# 1x1 transparent PNG; some XMind builds require a thumbnail to render preview.
+THUMBNAIL_PNG: bytes = bytes.fromhex(
+    "89504e470d0a1a0a0000000d49484452000000010000000108060000001f15c4"
+    "890000000d49444154789c6300010000000500010d0a2db40000000049454e44"
+    "ae426082"
+)
+
+
+def _build_metadata(workbook: Workbook) -> dict[str, Any]:
+    md = {
+        "modifier": workbook.metadata.get("modifier", ""),
+        "dataStructureVersion": "3",
+        "creator": workbook.metadata.get("creator") or {"name": "xmindpy"},
+        "layoutEngineVersion": "5",
+    }
+    if workbook.sheets:
+        md["activeSheetId"] = workbook.sheets[0].id
+    md["created"] = datetime.now(timezone.utc).isoformat(timespec="milliseconds")
+    return md
+
+
+def _build_manifest(file_entries: dict[str, str]) -> str:
+    entries = {path: {"media-type": media} for path, media in file_entries.items()}
+    return json.dumps({"file-entries": entries}, ensure_ascii=False, indent=2)
+
+
+def save_workbook(workbook: Workbook, path: str) -> None:
+    """Save ``workbook`` to ``path`` in modern XMind JSON format."""
+    content_json = json.dumps(workbook.to_content(), ensure_ascii=False, indent=2)
+    metadata_json = json.dumps(_build_metadata(workbook), ensure_ascii=False, indent=2)
+
+    # manifest lists every file we actually put in the zip; compute media-types.
+    manifest_data = _build_manifest({
+        "content.json": "application/json",
+        "metadata.json": "application/json",
+        "Thumbnails/thumbnail.png": "image/png",
+    })
+
+    with zipfile.ZipFile(path, "w", zipfile.ZIP_DEFLATED) as z:
+        # mimetype MUST be the first entry, stored uncompressed
+        mimetype_info = zipfile.ZipInfo("mimetype")
+        mimetype_info.compress_type = zipfile.ZIP_STORED
+        z.writestr(mimetype_info, MIMETYPE)
+
+        z.writestr("content.json", content_json)
+        z.writestr("metadata.json", metadata_json)
+        z.writestr("manifest.json", manifest_data)
+        z.writestr("Thumbnails/thumbnail.png", THUMBNAIL_PNG)
+
+
+def save_to_stream(workbook: Workbook, stream: IO[bytes]) -> None:
+    """Like :func:`save_workbook` but writes to a binary stream."""
+    import io
+
+    buf = io.BytesIO()
+    save_workbook(workbook, buf)
+    stream.write(buf.getvalue())

xmindpy-0.1.0/xmindpy/workbook.py

@@ -0,0 +1,180 @@
+"""Native Python object model for an XMind workbook."""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from typing import Any
+
+
+def _new_id() -> str:
+    return str(uuid.uuid4())
+
+
+# Fields we know how to round-trip; everything else lands in ``_extras``.
+_KNOWN_TOPIC_KEYS = frozenset({
+    "id", "class", "title", "styleId", "labels", "markers", "notes",
+    "hyperlinks", "children", "detached",
+})
+
+
+@dataclass
+class Topic:
+    """A node in the mind map.
+
+    Children are stored on ``self.children`` as a list of ``Topic`` instances.
+    Detached floating topics go on ``self.detached`` (rare; mirrors XMind's
+    "free" topic positioning).
+
+    Unrecognized JSON fields (e.g. ``callout``, ``summary``, ``boundary``,
+    image references) loaded from a file are preserved in ``self._extras``
+    and re-emitted on save, so the library is forward-compatible with
+    XMind features we don't model explicitly.
+    """
+
+    title: str
+    id: str = field(default_factory=_new_id)
+    children: list[Topic] = field(default_factory=list)
+    detached: list[Topic] = field(default_factory=list)
+    notes: str | None = None
+    labels: list[str] = field(default_factory=list)
+    markers: list[str] = field(default_factory=list)
+    style_id: str | None = None
+    hyperlinks: list[str] = field(default_factory=list)
+    _extras: dict[str, Any] = field(default_factory=dict)
+
+    def add(self, topic: Topic) -> Topic:
+        self.children.append(topic)
+        return topic
+
+    def add_detached(self, topic: Topic) -> Topic:
+        self.detached.append(topic)
+        return topic
+
+    # --- serialization helpers --------------------------------------------------
+
+    def to_dict(self) -> dict[str, Any]:
+        data: dict[str, Any] = {
+            "id": self.id,
+            "class": "topic",
+            "title": self.title,
+        }
+        if self.style_id:
+            data["styleId"] = self.style_id
+        if self.labels:
+            data["labels"] = list(self.labels)
+        if self.markers:
+            data["markers"] = [{"markerId": m} for m in self.markers]
+        if self.notes:
+            data["notes"] = {"plain": {"content": self.notes}}
+        if self.hyperlinks:
+            data["hyperlinks"] = [
+                {"href": h, "description": h} for h in self.hyperlinks
+            ]
+        if self.children:
+            data["children"] = {"attached": [c.to_dict() for c in self.children]}
+        if self.detached:
+            data["detached"] = [t.to_dict() for t in self.detached]
+        # Preserve any unrecognized fields as-is (callouts, summaries, etc.)
+        data.update(self._extras)
+        return data
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Topic:
+        topic = cls(
+            title=data.get("title", ""),
+            id=data.get("id") or _new_id(),
+        )
+        if "styleId" in data:
+            topic.style_id = data["styleId"]
+        if "labels" in data:
+            topic.labels = list(data["labels"])
+        if "markers" in data:
+            topic.markers = [m["markerId"] for m in data["markers"] if "markerId" in m]
+        if "notes" in data:
+            plain = data["notes"].get("plain", {})
+            topic.notes = plain.get("content")
+        if "hyperlinks" in data:
+            topic.hyperlinks = [h.get("href", "") for h in data["hyperlinks"]]
+        children = data.get("children", {}).get("attached", [])
+        topic.children = [cls.from_dict(c) for c in children]
+        detached = data.get("detached", [])
+        topic.detached = [cls.from_dict(t) for t in detached]
+        # Save any unknown keys so re-save doesn't drop them.
+        topic._extras = {k: v for k, v in data.items() if k not in _KNOWN_TOPIC_KEYS}
+        return topic
+
+
+# Same pattern for Sheet: keep unknown fields round-trippable.
+_KNOWN_SHEET_KEYS = frozenset({
+    "id", "class", "title", "rootTopic", "relationships",
+})
+
+
+@dataclass
+class Sheet:
+    """One tab / mind map in the workbook.
+
+    Unrecognized JSON fields are preserved in ``self._extras`` so the library
+    is forward-compatible with XMind features we don't model explicitly.
+    """
+
+    title: str
+    root_topic: Topic
+    id: str = field(default_factory=_new_id)
+    relationships: list[dict[str, Any]] = field(default_factory=list)
+    _extras: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        data: dict[str, Any] = {
+            "id": self.id,
+            "class": "sheet",
+            "title": self.title,
+            "rootTopic": self.root_topic.to_dict(),
+            "relationships": list(self.relationships),
+        }
+        data.update(self._extras)
+        return data
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Sheet:
+        root = Topic.from_dict(data["rootTopic"])
+        sheet = cls(
+            title=data.get("title", "Sheet"),
+            root_topic=root,
+            id=data.get("id") or _new_id(),
+            relationships=list(data.get("relationships", [])),
+        )
+        sheet._extras = {k: v for k, v in data.items() if k not in _KNOWN_SHEET_KEYS}
+        return sheet
+
+
+@dataclass
+class Workbook:
+    """Container of one or more sheets."""
+
+    sheets: list[Sheet] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def create_sheet(self, title: str = "Sheet") -> Sheet:
+        sheet = Sheet(
+            title=title,
+            root_topic=Topic(title=title),
+        )
+        self.sheets.append(sheet)
+        return sheet
+
+    def to_content(self) -> list[dict[str, Any]]:
+        return [s.to_dict() for s in self.sheets]
+
+    def save(self, path: str) -> None:
+        """Save to a file in modern XMind JSON format."""
+        from .saver import save_workbook
+        save_workbook(self, path)
+
+    @classmethod
+    def from_content(cls, content: list[dict[str, Any]]) -> Workbook:
+        wb = cls()
+        for sheet_data in content:
+            wb.sheets.append(Sheet.from_dict(sheet_data))
+        return wb