psdparse 0.5.0__tar.gz → 0.7.0__tar.gz

{psdparse-0.5.0 → psdparse-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: psdparse
-Version: 0.5.0
+Version: 0.7.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>
@@ -45,7 +45,8 @@ Pure C++17 PSD (Photoshop) reader/writer library, with pybind11-based Python bin
 
 - 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)`.
+- **Edit & save**: add / delete / reorder / duplicate layers, copy layers between files, replace layer & mask pixels, edit parameters / names / masks / fill opacity, edit layer-effect (`lfx2`) values and text content, or build a PSD from scratch — all with byte-exact re-serialization of the parts you touch (unedited layers stay byte-identical).
+- Python wrapper: `import psdparse` → `PSDFile.load(path) / layer_image(i) / merged_image() / save(path)` plus the editing API.
 
 The library was extracted from the [psdfile](https://github.com/wamsoft/psdfile) kirikiri plugin in 2026. psdfile now consumes this library as a submodule.
 
@@ -131,11 +132,29 @@ layer_bgra = p.layer_image(0, "masked") # bytes, BGRA, 4*w*h
 p.save(r"out.psd")              # byte-identical round-trip
 ```
 
+Editing (8-bit RGB), re-serialized on save — unedited layers stay byte-identical:
+
+```python
+p.layers[0].opacity = 128                       # parameters
+p.layers[0].name_unicode = "背景"               # rename
+p.delete_layer(3); p.move_layer(1, 4)           # structure
+p.set_layer_pixels(0, bgra_bytes, w, h)         # replace pixels
+p.set_layer_mask_pixels(0, gray, 0, 0, w, h)    # mask pixels + geometry
+p.set_effects(0, {"masterFXSwitch": False})     # layer-effect values
+p.set_text(2, "新しいテキスト")                 # text content
+p.save(r"edited.psd")
+
+q = psdparse.PSDFile()                           # or build one from scratch
+q.create_blank(1024, 768)
+q.add_layer("bg", 0, 0, bgra_bytes, 1024, 768)
+q.save(r"new.psd")
+```
+
 Full API reference: [docs/PYTHON_API.md](docs/PYTHON_API.md).
 
 ## PSD feature coverage
 
-What psdparse can and cannot read, at a glance:
+What psdparse can and cannot read **and edit**, at a glance:
 [docs/SUPPORT.md](docs/SUPPORT.md) (対応状況マトリクス).
 
 ## Tests

{psdparse-0.5.0 → psdparse-0.7.0}/README.md

@@ -4,7 +4,8 @@ Pure C++17 PSD (Photoshop) reader/writer library, with pybind11-based Python bin
 
 - 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)`.
+- **Edit & save**: add / delete / reorder / duplicate layers, copy layers between files, replace layer & mask pixels, edit parameters / names / masks / fill opacity, edit layer-effect (`lfx2`) values and text content, or build a PSD from scratch — all with byte-exact re-serialization of the parts you touch (unedited layers stay byte-identical).
+- Python wrapper: `import psdparse` → `PSDFile.load(path) / layer_image(i) / merged_image() / save(path)` plus the editing API.
 
 The library was extracted from the [psdfile](https://github.com/wamsoft/psdfile) kirikiri plugin in 2026. psdfile now consumes this library as a submodule.
 
@@ -90,11 +91,29 @@ layer_bgra = p.layer_image(0, "masked") # bytes, BGRA, 4*w*h
 p.save(r"out.psd")              # byte-identical round-trip
 ```
 
+Editing (8-bit RGB), re-serialized on save — unedited layers stay byte-identical:
+
+```python
+p.layers[0].opacity = 128                       # parameters
+p.layers[0].name_unicode = "背景"               # rename
+p.delete_layer(3); p.move_layer(1, 4)           # structure
+p.set_layer_pixels(0, bgra_bytes, w, h)         # replace pixels
+p.set_layer_mask_pixels(0, gray, 0, 0, w, h)    # mask pixels + geometry
+p.set_effects(0, {"masterFXSwitch": False})     # layer-effect values
+p.set_text(2, "新しいテキスト")                 # text content
+p.save(r"edited.psd")
+
+q = psdparse.PSDFile()                           # or build one from scratch
+q.create_blank(1024, 768)
+q.add_layer("bg", 0, 0, bgra_bytes, 1024, 768)
+q.save(r"new.psd")
+```
+
 Full API reference: [docs/PYTHON_API.md](docs/PYTHON_API.md).
 
 ## PSD feature coverage
 
-What psdparse can and cannot read, at a glance:
+What psdparse can and cannot read **and edit**, at a glance:
 [docs/SUPPORT.md](docs/SUPPORT.md) (対応状況マトリクス).
 
 ## Tests

{psdparse-0.5.0 → psdparse-0.7.0}/docs/PYTHON_API.md

@@ -42,7 +42,11 @@ Open `path` as a `std::ifstream` and parse via `StreamReader`. Functionally equi
 p.save(path: str) -> bool
 ```
 
-Save the currently loaded data back to disk as PSD. **The current implementation is round-trip-only**: `p.load(a); p.save(b)` produces a byte-identical copy. Modifying `layers` after load and then saving is not yet supported (see [ROADMAP.md](ROADMAP.md) for the per-channel / RLE-encoder work needed for that).
+Save the currently loaded (and optionally edited) data back to disk as PSD.
+An **unmodified** file round-trips byte-identically (`p.load(a); p.save(b)`),
+and edits are re-serialized on save — see [Editing & saving](#editing--saving).
+Do not save over a file that is currently loaded (returns `False`; see
+[Saving](#saving)).
 
 ### Header
 
@@ -92,7 +96,7 @@ Read-only view of one layer.
 | `top, left, bottom, right` | `int` | layer bounding box on canvas |
 | `width, height` | `int` | derived from bbox |
 | `opacity` | `int` | 0..255 |
-| `fill_opacity` | `int` | 0..255 |
+| `fill_opacity` | `int` | 0..255. **Writable** (the `iOpa` block) |
 | `clipping` | `int` | 0=base, 1=non-base |
 | `blend_mode_key` | `int` | raw 4cc value (e.g. `'norm'` as int) |
 | `blend_mode` | `BlendMode` enum | parsed blend mode |
@@ -100,13 +104,14 @@ Read-only view of one layer.
 | `layer_id` | `int` | -1 if unset |
 | `channels` | `list[ChannelInfo]` | per-channel id+length |
 | `name` | `str` | raw Pascal-string name (CP932 etc on Japanese PSDs — pybind11 may raise UnicodeDecodeError when read) |
-| `name_unicode` | `str` | UTF-16 Unicode name from `luni` record (preferred) |
+| `name_unicode` | `str` | UTF-16 Unicode name from `luni` record (preferred). **Writable** — assigning renames the layer (see [Editing](#editing--saving)) |
 | `parent_index` | `int` | index into `PSDFile.layers` of the enclosing folder, or `-1` for top level — see [Layer hierarchy](#layer-hierarchy) |
 | `text` | `dict` \| `None` | text-layer content & style (`None` for non-text layers) — see below |
 | `mask` | `dict` \| `None` | layer mask geometry & flags (`None` when the layer has no mask) — see below |
 | `blending_ranges` | `dict` \| `None` | "Blend If" ranges (`None` when absent) — see below |
 | `effects` | `dict` \| `None` | layer effects (`lfx2`) as a descriptor dict — see [Descriptor blocks](#descriptor-blocks) |
 | `fill` | `dict` \| `None` | fill-layer content (solid/gradient/pattern) — see [Descriptor blocks](#descriptor-blocks) |
+| `sheet_color` | `dict` \| `None` | layer-panel color label (`lclr`): `{"index", "name"}` — `None` when no `lclr` block |
 | `info_keys` | `list[str]` | 4cc keys of every additional-layer-info block on this layer |
 | `visible` | `bool` | flag bit 1 inverted |
 | `transparency_protected` | `bool` | flag bit 0 |
@@ -175,16 +180,24 @@ for layer in p.layers:
   "disabled": False,         # bit1: mask disabled
   "inverted": False,         # bit2: invert (obsolete)
   "from_render": False,      # bit3: mask from rendering other data
-  "has_parameters": False,   # bit4: density/feather present (not decoded yet)
+  "has_parameters": True,    # bit4: density/feather block present
+  "user_density": 128,       # 0..255, or None if not stored
+  "user_feather": 2.5,       # feather radius (px), or None
+  "vector_density": None,    # 0..255, or None
+  "vector_feather": None,    # feather radius (px), or None
   "real": None,              # or a nested dict (below) for a real/user mask
 }
 ```
 
-When the record carries a *real* (user + vector combined) mask, `real` is a dict
-with `flags`, `background`, and the enclosing `top/left/bottom/right`. The mask
-**pixels** are unchanged from before — fetch them with
+When the record carries a *real* (user + vector combined) mask (block size ≥ 36),
+`real` is a dict with `flags`, `background`, and the enclosing
+`top/left/bottom/right`. The mask **pixels** are unchanged — fetch them with
 `p.layer_image(i, "mask")`.
 
+`user_density`/`user_feather`/`vector_density`/`vector_feather` are only non-`None`
+when `has_parameters` is set and the corresponding value was stored. (Fixed in
+0.6.0: the real-mask section was previously decoded one byte off.)
+
 ### `layer.blending_ranges` — "Blend If" ranges
 
 `None` when absent. `gray` is the composite range; `channels` has one entry per
@@ -214,6 +227,226 @@ for i, l in enumerate(p.layers):
 `FOLDER` marks a group's start and the matching `HIDDEN` layer marks its end
 (these are Photoshop's `lsct` section dividers).
 
+## Editing & saving
+
+psdparse can edit a loaded PSD (or build one from scratch) and save the result.
+Editable: layer **parameters** (opacity/visibility/clipping/blend/fill-opacity),
+**names**, **structure** (delete/move/duplicate/cross-file copy), **pixels** and
+**masks**, layer-**effect values**, and **text content** — plus `create_blank`
+for new documents.
+
+The model is *lazy*: edits only touch in-memory fields/references — nothing is
+re-encoded until `save()`, which re-serializes just the parts you changed. The
+original file is never touched (`load()` mmaps it read-only; `save()` writes a
+new path), and an **unmodified** file still round-trips byte-identically — the
+re-serialization only kicks in for layers you actually edited. Byte-exact
+serializers back the effect (`lfx2`) and text (EngineData) editing, so unedited
+descriptors reproduce their original bytes exactly.
+
+Quick map of the API (details in the subsections below):
+
+| Want to… | Use |
+|---|---|
+| change opacity / visibility / blend / clipping | `layer.opacity = …`, `layer.visible = …`, `layer.set_blend_mode("mul ")` |
+| rename a layer | `layer.name_unicode = …` / `p.set_layer_name(i, …)` |
+| change fill opacity | `layer.fill_opacity = …` |
+| delete / move / duplicate | `p.delete_layer(i)` / `p.move_layer(a,b)` / `p.duplicate_layer(i)` |
+| copy a layer from another file | `p.copy_layer_from(src, j)` |
+| replace layer pixels / add an image layer | `p.set_layer_pixels(...)` / `p.add_layer(...)` |
+| set mask pixels + geometry / mask values | `p.set_layer_mask_pixels(...)` / `p.set_layer_mask(...)` |
+| edit effect / descriptor values | `p.set_effects(i, changes)` / `p.set_layer_descriptor(...)` |
+| edit text content | `p.set_text(i, str)` |
+| edit a text run's style | `p.set_run_style(i, run, size_px=…, color=…, …)` |
+| build a new PSD | `p.create_blank(w, h)` then `add_layer(...)` |
+
+**8-bit RGB only** for the pixel/mask/new-document operations. The stored
+composite image is **not** re-rendered after edits (see [Saving](#saving)).
+
+### Parameter edits (writable properties)
+
+```python
+p = psdparse.PSDFile(); p.load("in.psd")
+p.layers[3].opacity = 128          # 0..255
+p.layers[3].visible = False
+p.layers[3].clipping = 1
+p.layers[3].set_blend_mode("mul ") # 4-char key; note trailing space on 3-letter keys
+p.layers[3].name_unicode = "新しい名前"   # rename (also: p.set_layer_name(3, "..."))
+p.save("out.psd")
+```
+
+`opacity` / `clipping` / `visible` / `blend_mode_key` are record-level fields,
+re-serialized directly. The rest edit the **extra-data block**, which is
+reconstructed on save (the layer mask and blending ranges are copied through
+byte-for-byte unless you edit the mask itself):
+
+```python
+p.layers[3].name_unicode = "新しい名前"      # rename (or p.set_layer_name(3, ...))
+p.layers[3].fill_opacity = 128               # 0..255 (the 'iOpa' block)
+
+# edit an existing mask's values (the layer must already have a mask;
+# the mask rectangle and pixels are unchanged):
+p.set_layer_mask(3, disabled=True, density=200, feather=2.5, default_color=0)
+```
+
+`set_layer_mask` takes any subset of `disabled` (bool), `density` (0..255),
+`feather` (px), `default_color` (0..255). To change the mask **geometry**
+(rectangle) or its pixels, use `set_layer_mask_pixels(...)`
+(see [Mask pixels & geometry](#mask-pixels--geometry)).
+
+### Effect / descriptor values (E3)
+
+Layer effects (`lfx2`) and descriptor-based fill layers are edited by passing a
+**partial** dict of changes, shaped like `layer.effects` (see
+[Descriptor blocks](#descriptor-blocks)). Only the leaf values you include are
+overwritten; structure, class IDs, types and every untouched value are preserved
+(the descriptor is re-serialized byte-for-byte apart from your edits).
+
+```python
+# drop-shadow opacity 100 -> 50 %, turn all effects off:
+p.set_effects(i, {
+    "patternFill": {"Opct": {"value": 50.0}, "enab": False},
+    "masterFXSwitch": False,
+})
+
+# generic form for any descriptor key (fill layers etc.):
+p.set_layer_descriptor(i, "SoCo", {"Clr ": {"Rd  ": 255.0, "Grn ": 0.0, "Bl  ": 0.0}})
+```
+
+Value mapping when merging: numbers → Integer/Double; `{"value": ..}` (or a bare
+number) → UnitFloat; bool → Boolean; str → String; `{"value": ..}` or str →
+Enumerated; nested dict → sub-descriptor (recurse); list → per-index. Unknown
+keys are ignored, and only *existing* keys are edited (you cannot add new effect
+fields this way). `layer.descriptor_bytes(key)` returns a block's raw bytes for
+inspection.
+
+### Structural edits (methods on `PSDFile`)
+
+```python
+p.delete_layer(i)                  # remove layer i
+p.move_layer(from_i, to_i)         # reorder (to_i = index in the post-removal list)
+new_i = p.duplicate_layer(i)       # copy layer i, inserted right after it
+new_i = p.copy_layer_from(src, j, dest_index=-1)  # copy layer j from another PSDFile
+```
+
+Notes:
+- `delete_layer` / `duplicate_layer` on a single layer are exact. Deleting **one
+  half of a group's FOLDER/HIDDEN divider pair unbalances the group** — delete
+  whole groups (both dividers + contents) for clean nesting. (Unbalanced results
+  still load; the hierarchy just looks odd.)
+- **`copy_layer_from` copies across files.** The copied layer references the
+  *source's* pixel/extra bytes lazily, so **the source `PSDFile` must stay open
+  until the destination is saved** (and, in fact, until it is garbage-collected).
+  psdparse keeps a reference to the source automatically, so simply saving before
+  discarding both is enough. Source and destination must share color mode and bit
+  depth.
+- **New-from-scratch** documents (`create_blank`) and **text content** editing
+  (`set_text`) are covered in their own subsections below.
+- The stored **composite (merged) image is not regenerated** after edits — it
+  stays as it was until Photoshop (or another editor) recomposites on open.
+
+### Pixel edits (E4)
+
+Replace an existing layer's pixels, or add a whole new image layer, from BGRA
+bytes (the same interleave `layer_image` returns). **8-bit RGB documents only.**
+
+```python
+# replace layer i's pixels (left/top kept; width/height updated)
+p.set_layer_pixels(i, bgra_bytes, width, height)
+
+# add a new image layer; returns its index
+new_i = p.add_layer("name", left, top, bgra_bytes, width, height,
+                    blend_mode="norm", opacity=255, dest_index=-1)
+```
+
+- `bgra_bytes` must be exactly `width*height*4` bytes (B, G, R, A per pixel).
+- Channels are PackBits(RLE)-encoded on `save()`; decode round-trips exactly.
+- `add_layer` writes the name as both a Pascal string and a Unicode `luni`
+  block, so non-ASCII names (incl. emoji) survive.
+- `set_layer_pixels` keeps an existing **mask channel** intact (only the colour
+  channels are rebuilt). Replacing a *masked* layer at a different size leaves a
+  stale mask rectangle, though — prefer same-size replacement, or follow with
+  `set_layer_mask_pixels` to reset the mask.
+
+### Mask pixels & geometry
+
+```python
+# set/replace the mask with a grayscale buffer (0 = hidden, 255 = shown),
+# positioned at (left, top). Creates the mask if the layer had none:
+p.set_layer_mask_pixels(i, gray_bytes, top, left, width, height)
+```
+
+- `gray_bytes` is `width*height` bytes (one per pixel). This sets both the mask
+  pixels **and** the mask rectangle (geometry). Colour channels are preserved.
+- Mask **value** attributes (disabled / density / feather / default colour) are
+  edited separately with `set_layer_mask(...)`. 8-bit documents only.
+
+### Text content (E6)
+
+Replace a text layer's body text. This rewrites the embedded Adobe *EngineData*
+(re-serialized byte-for-byte in Photoshop's format) plus the `Txt ` descriptor
+string, and re-serializes the `TySh` block keeping the warp/bounds intact.
+
+```python
+p.set_text(i, "新しいテキスト\r二行目")     # \r separates lines
+p.save("out.psd")
+```
+
+- Non-ASCII and emoji are supported (stored as UTF-16 in EngineData).
+- A trailing newline (`\r`) is added if missing (Photoshop's convention).
+- **`set_text` collapses styling to the first run's style** (single style run
+  over the new text). To keep per-run styling, edit runs individually with
+  `set_run_style` (below) instead of changing the text.
+- Only the *content* changes; the layer's transform, font set and bounds are
+  kept. Raises for non-text layers.
+
+Edit an existing run's style in place (text and run lengths unchanged):
+
+```python
+# run indices match layer.text["runs"]
+p.set_run_style(i, run=0, size_px=48.0, color=(1.0, 0.0, 0.0))   # 48px, red
+p.set_run_style(i, run=1, tracking=100, bold=True, underline=True)
+```
+
+- Any subset of: `size_px` (float), `color` ((r,g,b) or (r,g,b,a), each 0..1),
+  `tracking` / `kerning` (int), `bold` / `italic` / `underline` (bool).
+- Keys are added to the run if it inherited them from the default style sheet.
+- **Changing the font by name is not supported** (would require editing the
+  document's font set); re-splitting text into new runs isn't either.
+
+### New from scratch (E5)
+
+Build a PSD without loading one first:
+
+```python
+p = psdparse.PSDFile()
+p.create_blank(1024, 768)                       # blank 8-bit RGB, white composite
+p.add_layer("background", 0, 0, bg_bgra, 1024, 768)
+p.add_layer("sprite", 100, 100, sprite_bgra, 200, 150, "norm", 255)
+p.save("new.psd")
+```
+
+- `create_blank(width, height, mode=COLOR_MODE_RGB)` — 8-bit RGB only. Resets the
+  object to an empty document with a white stored composite.
+- Add content with `add_layer(...)`; a document with zero layers is also valid.
+- As with edited files, the stored composite is **not** rendered from the layers
+  — it stays white until an editor recomposites on open.
+
+### Saving
+
+`save(path)` returns `True`/`False`. **Do not save over a file that is currently
+loaded** (by this or any live `PSDFile`): `load()` memory-maps the file
+read-only, so the write is refused and `save()` returns `False` (the original is
+never corrupted). Always save to a fresh path, then swap the files yourself if
+you want to replace the original.
+
+```python
+# Merge one layer from file B into file A, on top:
+a = psdparse.PSDFile(); a.load("A.psd")
+b = psdparse.PSDFile(); b.load("B.psd")
+a.copy_layer_from(b, 0)            # append B's layer 0
+a.save("merged.psd")              # b is kept alive until here
+```
+
 ## Document resources
 
 Read-only accessors on `PSDFile` for whole-document metadata. Each returns
@@ -224,6 +457,7 @@ p.guides        # dict|None : {"horizontal_grid", "vertical_grid", "guides":[{"l
 p.slices        # dict|None : {"group_name", "bounding":{...}, "slices":[{...}]}
 p.layer_comps   # list[dict]: [{"id","name","comment","record_visibility","record_position","record_appearance"}]
 p.color_table   # dict|None : {"colors":[(r,g,b,a)], "valid_count", "transparency_index"} for indexed-color PSDs
+p.global_layer_mask  # dict|None : {"overlay_color_space", "color":(c1,c2,c3,c4), "opacity", "kind"}
 ```
 
 ### Image resources (raw)
@@ -305,9 +539,12 @@ Notes:
 - `layer.effects` is `lfx2` (object-based, Photoshop 6+). The older binary
   `lrFX` block is **not** a descriptor and returns `None` via `descriptor()`.
 - `descriptor(key, skip)` is the generic escape hatch: `skip` is the number of
-  version-prefix bytes before the descriptor (`-1` auto-detects for `lfx2` = 8
-  and `SoCo`/`GdFl`/`PtFl` = 4, otherwise 0). Use `info_keys` to discover which
-  blocks a layer carries.
+  version-prefix bytes before the descriptor (`-1` auto-detects for the known
+  descriptor keys: `lfx2` = 8, `SoCo`/`GdFl`/`PtFl`/`vstk`/`CgEd` = 4,
+  `vscg`/`vogk` = 8, `SoLd` = 12, otherwise 0). Use `info_keys` to discover which
+  blocks a layer carries. The smart-object/vector defaults (`SoLd`/`vstk`/`vscg`/
+  `vogk`) are set from the psd-tools layouts but not yet verified against a real
+  smart-object sample — override `skip` if a parse looks wrong.
 - Decoding is **lazy** — the descriptor is parsed from the block's raw bytes on
   each access, so cache the result if you read it repeatedly.
 
@@ -342,6 +579,12 @@ psdparse.LAYER_TYPE_NORMAL, LAYER_TYPE_HIDDEN, LAYER_TYPE_FOLDER,
 LAYER_TYPE_ADJUST, LAYER_TYPE_FILL
 ```
 
+Pixel extraction (`merged_image()` / `layer_image()`) supports Bitmap, Grayscale,
+RGB, Indexed, CMYK (→RGB), **Duotone** (rendered as grayscale) and **Lab**
+(standard D65 CIELAB→sRGB approximation — Photoshop uses D50, so highly saturated
+colors differ slightly). **Multichannel** has no canonical RGB mapping and is not
+rendered.
+
 ## Pixel format
 
 All `*_image()` methods return interleaved BGRA in little-endian byte order:

psdparse-0.7.0/docs/ROADMAP.md

@@ -0,0 +1,107 @@
+# psdparse Roadmap
+
+For a feature-by-feature account of what is and isn't supported today, see
+[SUPPORT.md](SUPPORT.md). This file tracks planned work.
+
+## Current state (2026-08-02, v0.7.0)
+
+- ✅ Pure C++17 parser (no Boost)
+- ✅ mmap + StreamReader / Source abstraction
+- ✅ Python bindings (pybind11)
+- ✅ pytest regression suite (121 tests)
+- ✅ Round-trip PSD save (byte-identical)
+- ✅ Edit & save: structure / pixels / mask / parameters / effects / text / new-from-scratch (E1–E6, byte-exact re-serialization)
+- ✅ UTF-8 path I/F (Win32 conversion internal only)
+
+## Save: from round-trip to edit-and-save
+
+The `save()` path started as round-trip-only (correct only when the loaded `Data` is unmodified). Structural editing is being added incrementally. The編集 API is split into phases E1–E6; each builds on the last.
+
+- ✅ **E1 — parameter edits.** *Done 2026-08-02 (0.7.0).* Record-level fields are re-serialized from the struct, so `layer.opacity` / `layer.clipping` / `layer.visible` are writable properties and `layer.set_blend_mode("mul ")` / `layer.blend_mode_key` set the blend mode. No file-format work was needed — `writeLayerRecord` already emitted these from fields.
+- ✅ **E2 — delete / move / duplicate / cross-file copy.** *Done 2026-08-02 (0.7.0).* `writeLayerInfo` now serializes channel data **per-layer/per-channel** (bounded `copyNFrom`) when the layer list is dirty, instead of dumping the original concatenated blob — so `PSDFile.delete_layer` / `move_layer` / `duplicate_layer` / `copy_layer_from(src, i)` all produce correct pixel data. A `Data::layersDirty` flag keeps unmodified files on the exact-blob path so byte-identical round-trip is preserved. Cross-file copy holds the source alive via pybind11 `keep_alive`. Also fixed a **pre-existing crash**: the group-linking loop in `processParsed` under-flowed its `parent` stack on unbalanced FOLDER/HIDDEN dividers (now guarded) — exposed by deleting one half of a divider pair. Validated against psd-tools (all edited files open + composite) — see `tests/test_edit.py`.
+
+- ✅ **E4 — RLE encoder + pixel replacement + new image layers.** *Done 2026-08-02 (0.7.0).* A PackBits(RLE) encoder (`psdimage.cpp`, the exact inverse of `decodePackBits`) plus an owning `VectorReader` (a `MemoryReader` that keeps its bytes alive via `shared_ptr`) back two new APIs: `PSDFile.set_layer_pixels(i, bgra, w, h)` replaces a layer's channels, and `PSDFile.add_layer(name, l, t, bgra, w, h, blend, opacity)` builds a whole new RGBA layer — channels in `(-1,0,1,2)` order and a minimal extra-data block (empty mask/ranges + Pascal name + `luni` Unicode name + `lyid`). 8-bit RGB only. Encoder round-trip is pixel-exact across edge cases (1×1, constant, runs, 128/129/255 widths); the Unicode name (incl. emoji) and all output files were cross-checked against psd-tools (`composite()`), see `tests/test_edit_pixels.py`. Also surfaced (and documented) that saving over an mmap'd path returns `False` rather than corrupting.
+
+- ✅ **E5 — new-from-scratch PSD construction.** *Done 2026-08-02 (0.7.0).* `PSDFile.create_blank(width, height, mode=RGB)` fills a minimal valid skeleton — header (v1, 3ch, 8-bit RGB), empty color-mode/resources, empty dirty layer list, and a white raw composite (`VectorReader`) — so you can `create_blank()` → `add_layer()` → `save()` with no source file. Validated empty and multi-layer, cross-checked with psd-tools `composite()` — see `tests/test_create.py`.
+
+- ✅ **E3b — effect / descriptor value editing + Descriptor serializer.** *Done 2026-08-02 (0.7.0).* A full **Photoshop descriptor serializer** (`writeDescriptorBody`/`writeDescriptorItem` in `psdwrite.cpp`, the exact inverse of `psddesc`'s loader, incl. references) plus a `MemoryWriter`. `Descriptor` now records `keyOrder` so re-serialization reproduces the on-disk key order, and descriptor data is padded to 4 bytes — together these make round-trip **byte-exact** (verified: `set_effects(i, {})` then save yields a byte-identical file). `PSDFile.set_effects(i, changes)` / `set_layer_descriptor(i, key, changes)` merge a partial dict onto the parsed typed descriptor (only leaf values overwritten; classIDs/types/order preserved) and swap the re-serialized block into the extra data. `layer.descriptor_bytes(key)` exposes raw block bytes. Validated against psd-tools — see `tests/test_edit_effects.py`. **This serializer is the shared foundation E6 (text editing) needs.**
+- ✅ **E3 — extra-data field edits (rename + mask + fill opacity).** *Done 2026-08-02 (0.7.0).* Editing of extra-data-resident fields, via a per-layer `LayerExtraData::useRawBytes=false` flag that routes save through `writeLayerExtraFromFields` (reconstruct from fields) instead of the raw-bytes passthrough:
+  - **Rename** — `layer.name_unicode = "..."` / `set_layer_name(i, name)` (Pascal + `luni`).
+  - **Fill opacity** — `layer.fill_opacity = ...` (the `iOpa` block; written as the 1-byte value + 3 filler to match Photoshop / psd-tools' `B3x` reader).
+  - **Mask values** — `set_layer_mask(i, disabled=, density=, feather=, default_color=)`; a `LayerMask::edited` flag makes the mask sub-block re-serialize from fields (`serializeLayerMask`), matching `parseLayerMask` exactly (real section gated on size≥36, params on flags bit4).
+
+  The layer mask & blending ranges are otherwise copied through byte-for-byte from `maskRaw`/`blendRaw` (captured at parse). Unmodified layers keep the exact-bytes path so round-trip identity is untouched. Learned the hard way that **layer-record tagged blocks use `padding=1` (no 4-byte alignment)** — only the *global* additional info and the Pascal name pad to 4. Validated with psd-tools reading back disabled/density/feather/bg/fill-opacity and no alignment warnings — see `tests/test_edit_name.py`, `tests/test_edit_mask.py`. **Still to do in E3:** mask *geometry* (rectangle) edits (effect value edits are done — see E3b above).
+
+- ✅ **E6b — per-run text style editing.** *Done 2026-08-02 (0.7.0).* `PSDFile.set_run_style(i, run, size_px=/color=/tracking=/kerning=/bold=/italic=/underline=)` edits an existing style run's `StyleSheetData` values in the embedded EngineData (adding keys the run inherited), leaving text, run lengths and other runs untouched. Reuses the byte-exact EngineData serializer + the shared `editTextLayer` TySh flow. Validated with psd-tools — see `tests/test_edit_run_style.py`. **Not covered:** changing a run's font by name (needs FontSet editing) or re-splitting text into new runs.
+- 🟡 **E6 — text-layer content editing.** *Text content done 2026-08-02 (0.7.0).* A **byte-exact Adobe EngineData serializer** (`psdengine.cpp`, the inverse of the parser — replicating psd-tools/Photoshop formatting: tab indentation by depth, `%.8f` float trimming with `0.`→`.`, inline-vs-multiline arrays, `(BOM …)` string escaping, and `Node.keyOrder`/`isInt` to preserve dict order and int-vs-float). Verified byte-exact on all 6 sample text layers. `PSDFile.set_text(i, str)` rewrites `EngineDict/Editor/Text` + collapses run-length arrays to a single run, updates the `Txt ` descriptor string, and re-serializes the `TySh` block (reusing the E3b descriptor serializer) with the version/transform prefix and warp/bounds suffix preserved verbatim. psd-tools reads the new text (incl. emoji) with no warnings — see `tests/test_edit_text.py`. **Still to do in E6:** per-run style editing (font/size/colour per range) — currently `set_text` collapses to the first run's style.
+
+- ✅ **Mask pixels & geometry editing.** *Done 2026-08-02 (0.7.0).* `PSDFile.set_layer_mask_pixels(i, gray, top, left, w, h)` RLE-encodes a grayscale buffer into the layer's user-mask channel (`-2`) and sets the mask rectangle (creating the mask if absent), so mask geometry is editable together with its pixels. Also fixed `set_layer_pixels` to **preserve** an existing mask channel instead of dropping it. Cross-checked mask pixels + rectangle with psd-tools — see `tests/test_edit_mask_pixels.py`.
+
+The image- and text-layer editing suite (E1–E6) is now feature-complete for the
+common cases. Remaining niche gaps are noted per-phase above (font-by-name and
+run re-splitting in text; composite re-rendering; smart-object embedded data).
+
+### Phase E3 (was 4c) — extra data field re-serialization (enables rename, blend-mode change)
+
+**Problem:** `LayerExtraData::rawBytes` is the raw bytes of the entire extra-data block (layer mask, blending range, Pascal name, additional info entries). Changing `lay.extraData.layerName` doesn't update `rawBytes`. Save would emit the stale name.
+
+**Approach:**
+- Add `writeLayerExtraDataFromFields(WriterBase&, const LayerExtraData&)` that re-serializes each field:
+  - `LayerMask` (0 / 20 / 36 / 40 byte variants — store a "size" hint or detect from presence of `enclosing*` fields)
+  - `LayerBlendingRange` (gray + per-channel)
+  - Pascal-string `layerName` with 4-byte padding
+  - Each `AdditionalLayerInfo`: 8BIM/8B64 + key + size + data (the inner `data` iterator can still be reused for entries we don't intend to modify, e.g. shmd, lsct)
+- Add a per-layer flag `LayerExtraData::useRawBytes` (default true). When the user mutates a field, drop to false; `writeLayerRecord` picks the reconstruction path.
+- For `luni` (Unicode name) records specifically, expose a setter that updates `layerNameUnicode` AND drops `rawBytes`-based emission.
+
+**Estimated size:** ~300 lines + tests for rename / mask edit. (Blend mode, opacity and clipping already land via E1's record-level setters, so E3 is specifically the *extra-data*-resident fields: Unicode name, mask geometry/params, fill opacity, effects.)
+
+### Phase E4 (was 4d) — RLE encoder + new layer / pixel replacement
+
+**Problem:** No way to construct new channel data. Existing layers' `channel.imageData` iterators point into the loaded file; we have no encoder that takes raw BGRA in and produces RLE-compressed channel bytes.
+
+**Approach:**
+- Implement a PackBits / RLE encoder (Photoshop's per-row variant with 16-bit row-length table).
+- Add a `psd::PSDFile::set_layer_pixels(int idx, const uint8_t *bgra, int w, int h)` API that:
+  1. Splits BGRA into B / G / R / A planes,
+  2. RLE-compresses each plane,
+  3. Replaces `channel.imageData` with a fresh in-memory `MemoryReader` over the compressed bytes.
+- Add `psd::PSDFile::add_layer(...)` for fully-synthesized layers (caller supplies bbox, name, blend mode, BGRA pixels).
+- Python: `p.replace_layer_image(idx, image_bytes, w, h)` and `p.add_layer(name, bbox, image_bytes, blend_mode=...)`.
+
+**Estimated size:** ~500 lines (mostly encoder) + a fixture-based round-trip test (encode, then decode through `getLayerImage`, then compare with input).
+
+### Phase E5 (was 4e) — new-from-scratch PSD construction
+
+Once E4 lands, the user can do:
+
+```python
+p = psdparse.PSDFile.create_blank(width=1024, height=768, mode=psdparse.COLOR_MODE_RGB)
+p.add_layer("background", bbox=(0, 0, 1024, 768), pixels=bg_bgra)
+p.add_layer("character", bbox=(100, 100, 800, 700), pixels=char_bgra)
+p.save("out.psd")
+```
+
+This is mostly a constructor that fills `Data` with a minimal-but-valid skeleton (default header, empty image resources, empty color mode data, sentinel `channelImageData`, etc.).
+
+### Phase E6 — text-layer editing
+
+Editing text content/style means writing the `TySh` block back: re-serializing the type-tool **descriptor** (currently read-only in `psddesc.*`) and, harder, re-emitting the embedded Adobe **EngineData** mini-language (`psdengine.cpp` only parses it). Needs a Descriptor serializer + an EngineData writer. Deferred until the image-layer editing set (E3–E5) is complete, per the stated priority (image first, then text).
+
+## Other future work
+
+- ✅ **Text layer content extraction (`TySh` type-tool additional info).** *Done 2026-07-27.* `lay.text` returns `{"text", "orientation", "justification", "transform", "runs":[{"length","font","size_px","color","tracking","kerning","auto_kerning"}]}` (or `None` for non-text layers). Implementation: `psddesc` now reads `tdta` raw data (length-prefixed), `loadLayerTypeTool` (`psdlayer.cpp`) parses the `TySh` header + text descriptor, and `psdengine.cpp` parses the embedded Adobe *EngineData* mini-language (FontSet / StyleRun / ParagraphRun) into per-run styling. Validated against `tests/data/fontsample.psd` (multi-font/size/color, **vertical**, emoji, tracking) — see `tests/test_text.py`.
+
+  **Deferred (need targeted sample PSDs, next turn):**
+  - **Non-RGB `FillColor`** — only `/Type 1` (RGB) decoded today; grayscale-mode / CMYK-mode text needs a sample to confirm `/Type` + `/Values` layout.
+  - **Warp text** — lives in the `TySh` *warp* descriptor (currently skipped, not in EngineData); needs samples with each warp style + non-zero bend/distortion.
+  - **Area (paragraph) vs point text / text box bounds** and **text-on-path** — need samples.
+  - **Leading / faux bold-italic / underline / strikethrough / paragraph indent+spacing** — keys exist in EngineData but are default-valued in the current sample, so per-run extraction can't be verified yet; needs a sample authored with non-default values.
+- ✅ **Tier-1 reference metadata exposed to Python.** *Done 2026-08-02 (0.3.0).* Data the C++ core already parsed but Python couldn't reach is now bound: `layer.parent_index` (folder hierarchy), `layer.mask` (bbox / flags / real-mask dict), `layer.blending_ranges`, and document-level `PSDFile.guides` / `.slices` / `.layer_comps` / `.color_table`. All dict-shaped, matching the existing `layer.text` style. Validated against `config.psd` / `system.psd` (hierarchy, blend ranges, guides, slices) and a psd-tools-synthesized `masktest.psd` (mask bbox/flags cross-checked) — see `tests/test_metadata.py`.
+- ✅ **Tier-2 generic Descriptor → dict bridge.** *Done 2026-08-02 (0.4.0).* `layer.effects` (`lfx2`), `layer.fill` (`SoCo`/`GdFl`/`PtFl`), `layer.info_keys`, and a generic `layer.descriptor(key, skip)` escape hatch route previously-skipped tagged blocks through the existing complete descriptor parser (`psddesc.*`). A `Descriptor → py::dict` converter in the binding (dynamic_cast dispatch; UnitFloat→`{value,unit}`, Enumerated→`{type,value}`, nested Descriptor→dict, List→list, tdta→bytes) means no per-feature decoders were needed. Decoding is lazy: each access clones the block's reader (`clone()`+`init()`) and re-parses, so `save()` round-trips remain byte-identical. Cross-checked value-for-value against psd-tools 1.17 on `config.psd`'s PatternOverlay (opacity/scale/angle/blend/pattern-name all matched) — see `tests/test_descriptors.py`. **Deferred:** typed high-level effect/fill objects, smart-object `SoLd`/`lnkD` (embedded-file extraction), and binary adjustment layers (`levl`/`curv`) all still need work — the raw descriptor dict is the current interface.
+- ✅ **Image-resource raw bytes exposed.** *Done 2026-08-02 (0.5.0).* `PSDFile.image_resource(id)` / `.image_resource_ids` plus typed shortcuts `.icc_profile` (1039), `.exif` (1058), `.xmp` (1060, UTF-8 str) and `.thumbnail` (1036/1033 → dict with JPEG bytes + dimensions). Raw bytes only — decoding EXIF tags / rendering the thumbnail is left to the caller. EXIF and ICC bytes cross-checked byte-identical against psd-tools 1.17; thumbnail JPEG verified decodable with Pillow — see `tests/test_resources.py`. **Still raw-only / unexposed:** higher-level decode of these (parsed EXIF, ICC transform) and the structured `GlobalLayerMaskInfo`.
+- ✅ **Mask parameters + color label + global mask + Lab/Duotone pixels.** *Done 2026-08-02 (0.6.0).* A batch of the remaining reference gaps: `layer.mask` now decodes the density/feather `MaskParameters` (`user_density`/`user_feather`/`vector_density`/`vector_feather`) and the real/user-mask section is byte-correct again (the old parser had an off-by-one that shifted the enclosing rect — no filler byte follows `flags`, and the real section is gated on size≥36, matching psd-tools). `layer.sheet_color` exposes the `lclr` layer-panel color label (index+name). `PSDFile.global_layer_mask` exposes the document overlay color/opacity/kind. `getLayerImage`/`getMergedImage` now render **Lab** (standard D65 CIELAB→sRGB approximation; Photoshop uses D50 so saturated colors differ slightly) and **Duotone** (as grayscale per the Adobe spec). The generic `descriptor()` escape hatch gained known default skips for `SoLd`/`vstk`/`vscg`/`vogk`/`CgEd`. Validated against psd-tools-authored fixtures (`maskparams.psd`: real+params mask & lclr; `labsample.psd`: neutral/red swatches; `duosample.psd` vs `graysample.psd`) — see `tests/test_mask_extras.py` and `tests/test_colormodes.py`. **Still open:** Multichannel pixels (no canonical RGB), smart-object embedded-file extraction (`lnkD`), and the SoLd/vector default skips remain unverified against a real smart-object sample.
+- 16-bit (`Lr16`) and 32-bit-float (`Lr32`) layer data: currently captured in `layerAndMaskTrailing` for round-trip but not exposed as decoded pixels.
+- Layer mask re-emission for masks > 20 bytes (the field-based save path; round-trip already preserves them via raw bytes).
+- Multichannel color extraction in `getLayerImage` (no canonical RGB representation); smart-object embedded file (`lnkD`) extraction.
+- Linux / macOS testing. mmap path uses POSIX `mmap` but hasn't been built / tested there.