psdparse 0.1.0__tar.gz

psdparse-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+/build
+/.vs
+/.vscode
+
+# sample PSDs for testing (see README for sourcing)
+*.psd
+
+# tools/psd_export.py outputs
+/_export_*/
+
+# Python cache and build artifacts
+__pycache__/
+*.pyc
+.pytest_cache/
+*.pyd
+
+# install output
+/install/
+
+# Python build / packaging artifacts (scikit-build-core, wheels, sdists)
+/dist/
+*.egg-info/
+_wt/
+_skbuild/

psdparse-0.1.0/CMakeLists.txt

@@ -0,0 +1,24 @@
+cmake_minimum_required(VERSION 3.16)
+
+if(CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
+    add_compile_options("$<$<AND:$<C_COMPILER_ID:MSVC>,$<COMPILE_LANGUAGE:C>>:/utf-8>")
+    add_compile_options("$<$<AND:$<CXX_COMPILER_ID:MSVC>,$<COMPILE_LANGUAGE:CXX>>:/utf-8>")
+    add_compile_options("$<$<AND:$<CXX_COMPILER_ID:MSVC>,$<COMPILE_LANGUAGE:CXX>>:/Zc:__cplusplus>")
+    project(psdparse LANGUAGES CXX)
+endif()
+
+# Python バインディング (オプション、別プリセット / pip で ON)
+option(PSDPARSE_BUILD_PYTHON "Build pybind11 Python bindings" OFF)
+if(PSDPARSE_BUILD_PYTHON)
+    # 拡張モジュールは libpsdparse.a (および取得した zlib) を .so にリンクするため、
+    # 静的オブジェクトはすべて位置独立コード (PIC) でビルドする必要がある。
+    # add_subdirectory(psdparse) より前に設定し、配下の全ターゲットへ波及させる。
+    set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+endif()
+
+# C++ ライブラリ本体 (吉里吉里非依存、pure C++17)
+add_subdirectory(psdparse)
+
+if(PSDPARSE_BUILD_PYTHON)
+    add_subdirectory(python)
+endif()

psdparse-0.1.0/CMakePresets.json

@@ -0,0 +1,67 @@
+{
+    "version": 2,
+    "configurePresets": [
+        {
+            "name": "default",
+            "description": "Default build using Ninja Multi-Config (vcpkg-free; zlib via system or FetchContent)",
+            "generator": "Ninja Multi-Config",
+            "binaryDir": "$env{BUILD_DIR}",
+            "environment": {
+                "BUILD_DIR": "build/${presetName}"
+            },
+            "cacheVariables": {
+                "CMAKE_CXX_STANDARD": "17",
+                "CMAKE_CXX_STANDARD_REQUIRED": "ON",
+                "PSDPARSE_BUILD_CLI": "ON"
+            }
+        },
+        {
+            "name": "x64-windows",
+            "description": "Windows x64 (MSVC, static CRT). C++ library + CLI only.",
+            "inherits": "default",
+            "architecture": {
+                "value": "x64",
+                "strategy": "external"
+            },
+            "cacheVariables": {
+                "CMAKE_C_COMPILER": "cl",
+                "CMAKE_CXX_COMPILER": "cl",
+                "CMAKE_MSVC_RUNTIME_LIBRARY": "MultiThreaded$<$<CONFIG:Debug>:Debug>"
+            }
+        },
+        {
+            "name": "x86-windows",
+            "description": "Windows x86 (MSVC, static CRT). C++ library + CLI only.",
+            "inherits": "default",
+            "architecture": {
+                "value": "x86",
+                "strategy": "external"
+            },
+            "cacheVariables": {
+                "CMAKE_C_COMPILER": "cl",
+                "CMAKE_CXX_COMPILER": "cl",
+                "CMAKE_MSVC_RUNTIME_LIBRARY": "MultiThreaded$<$<CONFIG:Debug>:Debug>"
+            }
+        },
+        {
+            "name": "x64-windows-python",
+            "description": "Windows x64 Python bindings (MSVC, dynamic CRT to match CPython). Prefer `pip install .` (scikit-build-core).",
+            "inherits": "default",
+            "architecture": {
+                "value": "x64",
+                "strategy": "external"
+            },
+            "cacheVariables": {
+                "CMAKE_C_COMPILER": "cl",
+                "CMAKE_CXX_COMPILER": "cl",
+                "CMAKE_MSVC_RUNTIME_LIBRARY": "MultiThreaded$<$<CONFIG:Debug>:Debug>DLL",
+                "PSDPARSE_BUILD_PYTHON": "ON"
+            }
+        }
+    ],
+    "buildPresets": [
+        { "name": "x64-windows",         "configurePreset": "x64-windows" },
+        { "name": "x86-windows",         "configurePreset": "x86-windows" },
+        { "name": "x64-windows-python",  "configurePreset": "x64-windows-python" }
+    ]
+}

psdparse-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wamsoft
+
+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.

psdparse-0.1.0/Makefile

@@ -0,0 +1,57 @@
+SHELL = /bin/bash
+
+# vcpkg-free: zlib comes from the system or is fetched from source by CMake.
+
+ifeq ($(shell type cygpath >& /dev/null && echo true),true)
+FIXPATH = cygpath -ma
+else
+FIXPATH = realpath
+endif
+
+# Detect OS and set default PRESET accordingly
+ifeq ($(OS),Windows_NT)
+	PRESET?=x64-windows
+else
+	UNAME_S := $(shell uname -s)
+	UNAME_M := $(shell uname -m)
+	ifeq ($(UNAME_S),Linux)
+		ifeq ($(UNAME_M),aarch64)
+			PRESET?=arm64-linux
+		else
+			PRESET?=x64-linux
+		endif
+	else ifeq ($(UNAME_S),Darwin)
+		ifeq ($(UNAME_M),arm64)
+			PRESET?=arm64-osx
+		else
+			PRESET?=x64-osx
+		endif
+	else
+		PRESET?=x64-windows
+	endif
+endif
+
+BUILD_TYPE?=Release
+CMAKEOPT?=""
+INSTALL_PREFIX?=install
+
+BUILD_PATH=$(shell cmake --preset $(PRESET) -N | grep BUILD_DIR | sed 's/.*BUILD_DIR="\(.*\)"/\1/')
+
+.PHONY: prebuild build clean install run
+
+all: build
+
+# cmake 処理実行
+# CMAKEOPT で引数定義追加
+prebuild:
+	cmake --preset $(PRESET) ${CMAKEOPT}
+# ビルド実行
+build:
+	cmake --build $(BUILD_PATH) --config $(BUILD_TYPE)
+
+clean:
+	cmake --build $(BUILD_PATH) --config $(BUILD_TYPE) --target clean
+
+install:
+	cmake --install $(BUILD_PATH) --config $(BUILD_TYPE) --prefix $(INSTALL_PREFIX)
+

psdparse-0.1.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.2
+Name: psdparse
+Version: 0.1.0
+Summary: Fast PSD (Photoshop) reader/writer — C++17 core with pybind11 bindings
+Keywords: psd,photoshop,parser,image,graphics
+Author-Email: wamsoft <wtnbgo@gmail.com>
+License: MIT License
+         
+         Copyright (c) 2026 wamsoft
+         
+         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.
+         
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
+Project-URL: Homepage, https://github.com/wamsoft/psdparse
+Project-URL: Repository, https://github.com/wamsoft/psdparse
+Project-URL: Issues, https://github.com/wamsoft/psdparse/issues
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# psdparse
+
+Pure C++17 PSD (Photoshop) reader/writer library, with pybind11-based Python bindings.
+
+- Lazy I/O: PSD pixel data is **not** copied into memory at parse time. Only the structural metadata (a few hundred KB even for large files) is read upfront; layer pixels are paged in on demand via mmap or stream callbacks.
+- Round-trip save: `load(p) -> save(q)` produces a byte-identical PSD file.
+- Python wrapper: `import psdparse` → `PSDFile.load(path) / layer_image(i) / merged_image() / save(path)`.
+
+The library was extracted from the [psdfile](https://github.com/wamsoft/psdfile) kirikiri plugin in 2026. psdfile now consumes this library as a submodule.
+
+## Architecture (quick read)
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for full details.
+
+```
+IteratorBase (psdbase.h, pure virtual — parser only sees this)
+├── MemoryReader   (psdparse.h)  ... mmap / contiguous buffer
+└── StreamReader   (psdparse.h)  ... arbitrary seekable stream
+    └── Source (pure virtual; subclass per backend)
+        ├── IStreamSource              ... std::istream
+        └── (your custom Source)       ... e.g. iTJSBinaryStream wrapper
+
+WriterBase (psdwrite.h, pure virtual — symmetric to IteratorBase)
+└── FileWriter (FILE*)
+```
+
+`psd::PSDFile::load(const char *path)` mmaps a local file. `loadFromStream(std::istream&)` / `loadFromReader(IteratorBase&)` accept arbitrary I/O. `save(const char *path)` writes the loaded data back as PSD.
+
+All public path arguments are **UTF-8** (`char *`). On Win32, conversion to UTF-16 happens internally via `psd::utf8ToWide` (inline in psdbase.h).
+
+## Install (Python)
+
+```bash
+pip install psdparse          # once published to PyPI
+```
+
+Build from source — needs only a C++17 compiler + CMake 3.16+, **no vcpkg**:
+
+```bash
+pip install .                 # or:  pip wheel . -w dist
+```
+
+`zlib` is taken from the system if present, otherwise fetched from source by
+CMake (`FetchContent`), so no package manager is required. Packaging uses
+[scikit-build-core](https://scikit-build-core.readthedocs.io/); cross-platform
+wheels are built in CI (`.github/workflows/wheels.yml`, cibuildwheel).
+
+## Build (C++ library / CLI)
+
+Requires CMake 3.16+ and a C++17 compiler. **vcpkg is no longer needed.**
+
+```powershell
+# C++ library + CLI (static CRT)
+cmake --preset x64-windows
+cmake --build --preset x64-windows --config Release
+
+# C++ library + Python module (dynamic CRT, matches CPython)
+cmake --preset x64-windows-python
+cmake --build --preset x64-windows-python --config Release
+```
+
+`Makefile` is a thin wrapper:
+
+```
+make PRESET=x64-windows prebuild build
+make PRESET=x64-windows-python prebuild build
+```
+
+Build artifacts:
+- `build/x64-windows/psdparse/Release/psdparse_cli.exe`
+- `build/x64-windows-python/python/Release/psdparse.cp312-win_amd64.pyd`
+
+Only dependency: `zlib` (system, or auto-fetched from source).
+
+## Python API
+
+```python
+import psdparse
+
+p = psdparse.PSDFile()
+p.load(r"path/to/file.psd")   # mmap-backed
+
+print(p.header.width, p.header.height, len(p.layers))
+for layer in p.layers:
+    print(layer.name_unicode, layer.blend_mode.name, layer.opacity)
+
+bgra = p.merged_image()                # bytes, BGRA, 4*W*H
+layer_bgra = p.layer_image(0, "masked") # bytes, BGRA, 4*w*h
+
+p.save(r"out.psd")              # byte-identical round-trip
+```
+
+Full API reference: [docs/PYTHON_API.md](docs/PYTHON_API.md).
+
+## Tests
+
+Tests live under `tests/` and use [pytest](https://docs.pytest.org/). They need two sample PSDs at the repo root (not in git — see below).
+
+```powershell
+# After building with x64-windows-python preset:
+python -m pytest -v
+```
+
+### Sample PSDs
+
+The 27 pytest tests use these files:
+
+| File | Size | Description |
+|---|---|---|
+| `UI-PSDサンプル.psd` | 800×600, 50 layers, ~2 MB | UI button mock-up. Folder groups, transparent overlays. |
+| `園部由夏_a.psd` | 2500×3500, 28 layers, ~21 MB | Illustration. PASS_THROUGH groups, Unicode layer names (luni records). |
+
+Place them at the repo root (the conftest.py also checks `tests/data/` first). They are listed in `.gitignore`. If you can't source them, the tests will skip rather than fail.
+
+## tools/psd_export.py
+
+```
+python tools/psd_export.py input.psd [--out-dir DIR] [--mode masked|image|mask]
+```
+
+Outputs `layers.json` (full layer metadata), `merged.png` (composite), and per-layer PNGs.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

psdparse-0.1.0/README.md

@@ -0,0 +1,125 @@
+# psdparse
+
+Pure C++17 PSD (Photoshop) reader/writer library, with pybind11-based Python bindings.
+
+- Lazy I/O: PSD pixel data is **not** copied into memory at parse time. Only the structural metadata (a few hundred KB even for large files) is read upfront; layer pixels are paged in on demand via mmap or stream callbacks.
+- Round-trip save: `load(p) -> save(q)` produces a byte-identical PSD file.
+- Python wrapper: `import psdparse` → `PSDFile.load(path) / layer_image(i) / merged_image() / save(path)`.
+
+The library was extracted from the [psdfile](https://github.com/wamsoft/psdfile) kirikiri plugin in 2026. psdfile now consumes this library as a submodule.
+
+## Architecture (quick read)
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for full details.
+
+```
+IteratorBase (psdbase.h, pure virtual — parser only sees this)
+├── MemoryReader   (psdparse.h)  ... mmap / contiguous buffer
+└── StreamReader   (psdparse.h)  ... arbitrary seekable stream
+    └── Source (pure virtual; subclass per backend)
+        ├── IStreamSource              ... std::istream
+        └── (your custom Source)       ... e.g. iTJSBinaryStream wrapper
+
+WriterBase (psdwrite.h, pure virtual — symmetric to IteratorBase)
+└── FileWriter (FILE*)
+```
+
+`psd::PSDFile::load(const char *path)` mmaps a local file. `loadFromStream(std::istream&)` / `loadFromReader(IteratorBase&)` accept arbitrary I/O. `save(const char *path)` writes the loaded data back as PSD.
+
+All public path arguments are **UTF-8** (`char *`). On Win32, conversion to UTF-16 happens internally via `psd::utf8ToWide` (inline in psdbase.h).
+
+## Install (Python)
+
+```bash
+pip install psdparse          # once published to PyPI
+```
+
+Build from source — needs only a C++17 compiler + CMake 3.16+, **no vcpkg**:
+
+```bash
+pip install .                 # or:  pip wheel . -w dist
+```
+
+`zlib` is taken from the system if present, otherwise fetched from source by
+CMake (`FetchContent`), so no package manager is required. Packaging uses
+[scikit-build-core](https://scikit-build-core.readthedocs.io/); cross-platform
+wheels are built in CI (`.github/workflows/wheels.yml`, cibuildwheel).
+
+## Build (C++ library / CLI)
+
+Requires CMake 3.16+ and a C++17 compiler. **vcpkg is no longer needed.**
+
+```powershell
+# C++ library + CLI (static CRT)
+cmake --preset x64-windows
+cmake --build --preset x64-windows --config Release
+
+# C++ library + Python module (dynamic CRT, matches CPython)
+cmake --preset x64-windows-python
+cmake --build --preset x64-windows-python --config Release
+```
+
+`Makefile` is a thin wrapper:
+
+```
+make PRESET=x64-windows prebuild build
+make PRESET=x64-windows-python prebuild build
+```
+
+Build artifacts:
+- `build/x64-windows/psdparse/Release/psdparse_cli.exe`
+- `build/x64-windows-python/python/Release/psdparse.cp312-win_amd64.pyd`
+
+Only dependency: `zlib` (system, or auto-fetched from source).
+
+## Python API
+
+```python
+import psdparse
+
+p = psdparse.PSDFile()
+p.load(r"path/to/file.psd")   # mmap-backed
+
+print(p.header.width, p.header.height, len(p.layers))
+for layer in p.layers:
+    print(layer.name_unicode, layer.blend_mode.name, layer.opacity)
+
+bgra = p.merged_image()                # bytes, BGRA, 4*W*H
+layer_bgra = p.layer_image(0, "masked") # bytes, BGRA, 4*w*h
+
+p.save(r"out.psd")              # byte-identical round-trip
+```
+
+Full API reference: [docs/PYTHON_API.md](docs/PYTHON_API.md).
+
+## Tests
+
+Tests live under `tests/` and use [pytest](https://docs.pytest.org/). They need two sample PSDs at the repo root (not in git — see below).
+
+```powershell
+# After building with x64-windows-python preset:
+python -m pytest -v
+```
+
+### Sample PSDs
+
+The 27 pytest tests use these files:
+
+| File | Size | Description |
+|---|---|---|
+| `UI-PSDサンプル.psd` | 800×600, 50 layers, ~2 MB | UI button mock-up. Folder groups, transparent overlays. |
+| `園部由夏_a.psd` | 2500×3500, 28 layers, ~21 MB | Illustration. PASS_THROUGH groups, Unicode layer names (luni records). |
+
+Place them at the repo root (the conftest.py also checks `tests/data/` first). They are listed in `.gitignore`. If you can't source them, the tests will skip rather than fail.
+
+## tools/psd_export.py
+
+```
+python tools/psd_export.py input.psd [--out-dir DIR] [--mode masked|image|mask]
+```
+
+Outputs `layers.json` (full layer metadata), `merged.png` (composite), and per-layer PNGs.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

psdparse-0.1.0/docs/ARCHITECTURE.md

@@ -0,0 +1,156 @@
+# psdparse Architecture
+
+## Goals (in priority order)
+
+1. **Lazy I/O.** Loading a PSD must not require reading the full file into memory. Only structural metadata (a few hundred KB) is touched during parse. Pixel data is paged in when the user asks for a specific layer.
+2. **Backend-agnostic.** The parser and the image decoder see one I/O abstraction (`IteratorBase`). mmap and arbitrary seekable streams (std::istream, kirikiri `iTJSBinaryStream`, …) all plug into the same code path.
+3. **Round-trip save.** `load(p) -> save(q)` produces a byte-identical PSD. We achieve this by retaining raw-bytes iterators for blocks whose round-trip re-serialization would be painful (layer extra data, global mask info, trailing additional info).
+4. **No Boost. No tp_stub.** Plain C++17 + zlib only.
+
+## Read path
+
+```
+IteratorBase             (psdbase.h, pure virtual)
+├── MemoryReader         (psdparse.h)
+│     base_, [start_, end_), pos_   ← all just offsets into a const uint8_t*
+│     Used for: mmap'd files (PSDFile::load) and contiguous buffers (loadFromMemory)
+│
+└── StreamReader         (psdparse.h)
+      shared_ptr<Source> + 4KB cache + [start_, end_), pos_
+      Used for: any seekable stream
+      └── Source (pure virtual, nested in StreamReader)
+            ├── IStreamSource              ... std::istream wrapper (psdfile.cpp)
+            └── (your backend)             ... e.g. iTJSBinaryStream wrapper
+```
+
+`IteratorBase` exposes a tiny interface:
+
+```cpp
+virtual int  getCh();
+virtual int  getData(void *buffer, int n);
+virtual int16_t getInt16(bool convToNative=true);
+virtual int32_t getInt32(bool convToNative=true);
+virtual int64_t getInt64(bool convToNative=true);
+virtual void getUnicodeString(u16str &out, bool convToNative=true);
+
+virtual void advance(int n);
+virtual void init();          // reset to start of this sub-range
+virtual int  size();          // range length
+virtual int  rest();          // remaining bytes from pos
+virtual bool eoi();
+
+virtual IteratorBase *clone();                       // same pos, same range
+virtual IteratorBase *cloneOffset(int offset);       // pos+offset, end inherited
+virtual IteratorBase *cloneRange(int offset, int len); // [pos+offset, pos+offset+len)
+```
+
+The parser only ever sees `IteratorBase &`. There is no virtual function for "switch backend" because the choice of backend is fixed at construction time and forwarded via the `clone*` operations.
+
+### `cloneRange` is load-bearing
+
+Size-prefixed blocks (image resource entries, layer extra data, global mask info, …) must be parsed inside an `IteratorBase` that is **strictly bounded** to the declared size. Otherwise a corrupt `dataSize` can drive the parser past block boundaries — in the worst case, into an infinite `push_back` loop that allocates gigabytes before being noticed.
+
+The `SubBlock` RAII helper in `psdparse.cpp` wraps this pattern:
+
+```cpp
+SubBlock blk(outerReader, declaredSize);  // bounds sub-reader to declaredSize
+parseInnerStuff(blk.reader());            // sub-parser cannot escape
+// dtor: outerReader.advance(declaredSize) regardless of what sub consumed
+```
+
+### Forward-progress guards
+
+`parseImageResources`, `parseLayerExtraData`, and similar loops must verify that each iteration advances the reader:
+
+```cpp
+while (r.rest() >= MIN_ENTRY) {
+    int posBefore = r.size() - r.rest();
+    if (!parseOneEntry(r, ...)) break;
+    int posAfter = r.size() - r.rest();
+    if (posAfter <= posBefore) break;   // garbage entry; bail
+}
+```
+
+This is the second line of defense for corrupt input.
+
+## Lifetime: who owns the bytes?
+
+The parser stores `IteratorBase*` clones into `psd::Data` fields (`channelImageData`, `imageData`, per-resource `data`, per-layer-channel `imageData`, …). Each clone:
+
+- For `MemoryReader`: holds a `const uint8_t*` into the underlying buffer (mmap or `ownedBuffer_`). The buffer is owned by `PSDFile` via `mapping_` or `ownedBuffer_`.
+- For `StreamReader`: holds a `std::shared_ptr<Source>`. Last clone dies → `Source` dies → backend stream is closed.
+
+`PSDFile::clearData()` drops the iterators in well-defined order. The mmap is unmapped, owned buffer is swapped to empty, owned `istream` is reset. The destructor chains through `~Data` → `clearData()` (virtual; the explicit call in `~PSD()` is intentional and **must not** be removed).
+
+## Write path
+
+`writePSD(WriterBase&, const Data&)` walks the same five PSD top-level sections:
+
+1. **File header** (26 bytes): re-serialized from `data.header` fields.
+2. **Color mode data**: copies `data.colorModeIterator` bytes back.
+3. **Image resources**: re-emits each resource's 8BIM header / Pascal name / size, then dumps `res.data` iterator bytes.
+4. **Layer and mask info**: re-emits the layer info subsection header + per-record metadata, then dumps `data.channelImageData` (all channel data for all layers, in one blob), then dumps `data.globalLayerMaskInfoRaw` and `data.layerAndMaskTrailing` raw bytes for high-fidelity.
+5. **Image data**: dumps `data.imageData` (composite image, including compression word).
+
+### patch-back size headers
+
+Variable-length sections start with a 4-byte size field. The writer uses a placeholder-then-seek-back pattern:
+
+```cpp
+int64_t sizePos = w.tell();
+w.putUint32BE(0);             // placeholder
+int64_t bodyStart = w.tell();
+writeBody(w);
+int64_t bodyEnd = w.tell();
+w.seek(sizePos);              // back-patch
+w.putUint32BE(bodyEnd - bodyStart);
+w.seek(bodyEnd);
+```
+
+`WriterBase` requires `tell()` and `seek()` (pure virtual). `FileWriter` implements them with `_ftelli64` / `_fseeki64`.
+
+### Raw-bytes iterators for round-trip fidelity
+
+Re-serializing the full extra-data block (layer mask: 0 / 20 / 36 / 40 bytes with conditional fields; layer blending ranges; Pascal name with 4-byte padding; nested additional layer info entries) is tedious and error-prone. Instead, the parser captures the entire extra-data block as a raw IteratorBase clone alongside the parsed fields:
+
+```cpp
+// psdparse.cpp parseLayerRecord:
+uint32_t extraSize = r.getInt32(true);
+if (extraSize > 0) lay.extraData.rawBytes = r.cloneRange(0, extraSize);
+SubBlock blk(r, extraSize);
+if (extraSize > 0) parseLayerExtraData(blk.reader(), lay.extraData);
+```
+
+`writeLayerRecord` dumps `lay.extraData.rawBytes` directly. The parsed `LayerMask`, `LayerBlendingRange`, etc. fields are used for read access (`getLayerImage` etc.) but ignored on save.
+
+Same trick for `Data::globalLayerMaskInfoRaw` and `Data::layerAndMaskTrailing`. The latter is the unparsed Lr16/Lr32 secondary layer info — capturing it added 19KB of fidelity to one of the test fixtures.
+
+### Why this matters
+
+The round-trip guarantee assumes the user didn't modify the loaded data. Adding/removing layers or changing names breaks it because:
+
+- `channelImageData` is the **concatenation** of all channel bytes for all layers. Deleting a `LayerInfo` from `layerList` doesn't shrink this blob.
+- `LayerExtraData::rawBytes` doesn't reflect a mutated layer name. Save would write stale bytes.
+
+The roadmap for supporting structural edits is in [ROADMAP.md](ROADMAP.md). Briefly: per-channel save, then field-based extra-data emission, then an RLE encoder for new pixel data.
+
+## File / class index
+
+| File | Role |
+|---|---|
+| `psdparse/psdbase.h` | Endian macros, type atoms (`u16str`), `IteratorBase`, `utf8ToWide` |
+| `psdparse/psddata.h` | `Header`, `LayerInfo`, `ChannelInfo`, `ImageResourceInfo`, `LayerExtraData`, `Data` |
+| `psdparse/psddesc.h` | Photoshop Descriptor data |
+| `psdparse/psdparse.h` | `MemoryReader`, `StreamReader` (+ nested `Source`), `parsePSD` decl |
+| `psdparse/psdparse.cpp` | The parser. `SubBlock` RAII, hand-rolled binary reading, `processParsed` post-parse fixup |
+| `psdparse/psdfile.h` | `PSDFile` (load/save public API) |
+| `psdparse/psdfile.cpp` | `PSDFile` impl, Win32 mmap pimpl, `IStreamSource` adapter |
+| `psdparse/psdimage.cpp` | Per-channel and merged-image decoders (RLE / zip / raw) |
+| `psdparse/psdwrite.h` | `WriterBase`, `FileWriter`, `writePSD` decl |
+| `psdparse/psdwrite.cpp` | Writer implementation with patch-back size handling |
+| `psdparse/psdresource.cpp` | Image resource handlers (slices, grids, color tables, layer comps) |
+| `psdparse/psdlayer.cpp` | Layer-level additional info handlers (luni, lsct, lyid, …) |
+| `psdparse/psddesc.cpp` | Descriptor parser |
+| `psdparse/bmp.cpp` | BMP scratch-buffer helper |
+| `psdparse/psd_cli.cpp` | Smoke-test CLI |
+| `python/psdparse_module.cpp` | pybind11 bindings (PSDFile, LayerInfo, Header, enums) |