editmamei 1.8.0 → 1.9.0

package/dist/backends/gimp/bridge/ops.py

@@ -19,7 +19,9 @@
 
 import math
 import os
+import shutil
 import sys
+import tempfile
 import time
 import traceback
 
@@ -47,7 +49,10 @@ RAW_EXTENSIONS = {'.dng', '.cr2', '.cr3', '.nef', '.arw', '.raf', '.orf', '.rw2'
 
 def _image(args):
     image_id = lib.require(args, 'image')
-    img = Gimp.Image.get_by_id(int(image_id))
+    gid = lib.gimp_id(image_id)
+    if gid is None:
+        raise ValueError('no open image with id %s' % image_id)
+    img = Gimp.Image.get_by_id(gid)
     if img is None or not img.is_valid():
         raise ValueError('no open image with id %s' % image_id)
     # A preview proxy (see PROXIES below) is an internal, filter-free duplicate this bridge made
@@ -77,7 +82,8 @@ def _layer(img, args):
     (possibly closed) image and let an op silently touch the wrong document."""
     layer_id = args.get('layer_id')
     if layer_id is not None:
-        layer = Gimp.Layer.get_by_id(int(layer_id))
+        gid = lib.gimp_id(layer_id)
+        layer = Gimp.Layer.get_by_id(gid) if gid is not None else None
         owner = _owning_image(layer)
         if layer is None or owner is None or owner.get_id() != img.get_id():
             raise ValueError('no layer with id %s on image %s' % (layer_id, img.get_id()))
@@ -560,10 +566,22 @@ def _set_drop_shadow(cfg, params):
     # offset/radius does not grow the layer or canvas (measured at the schema maxima and in
     # combination: no size change), it just gets cut off at the edge like any other
     # DrawableFilter here, so no separate cap against "ballooning" is needed.
-    cfg.set_property('x', params['x'])
-    cfg.set_property('y', params['y'])
-    cfg.set_property('radius', params['radius'])
-    cfg.set_property('opacity', params['opacity'])
+    # outline / outer_glow reuse this operation and record only what they use: no offset
+    # (x, y = 0), no blur for outline (radius = 0), full opacity for outline. They add a grown
+    # core and a color; a drop_shadow record has neither, so it renders as before (no growth,
+    # black).
+    cfg.set_property('x', params.get('x', 0.0))
+    cfg.set_property('y', params.get('y', 0.0))
+    cfg.set_property('radius', params.get('radius', 0.0))
+    cfg.set_property('opacity', params.get('opacity', 1.0))
+    cfg.set_property('grow-shape', 'circle')
+    cfg.set_property('grow-radius', params.get('grow-radius', 0.0))
+    cfg.set_property('color', Gegl.Color.new(params.get('color', '#000000')))
+
+
+def _set_surface_blur(cfg, params):
+    cfg.set_property('blur-radius', params['blur-radius'])
+    cfg.set_property('edge-preservation', params['edge-preservation'] * lib.BILATERAL_EDGE_SCALE)
 
 
 SETTERS = {
@@ -586,6 +604,7 @@ SETTERS = {
     'gegl:focus-blur': _set_lens_blur,
     'gegl:noise-rgb': _set_add_noise,
     'gegl:dropshadow': _set_drop_shadow,
+    'gegl:bilateral-filter': _set_surface_blur,
 }
 
 
@@ -934,7 +953,7 @@ def _filter_record(filters, layer, f):
     rec = filters.get(f.get_name())
     if rec and rec['operation'] == f.get_operation_name():
         source = 'editmamei'
-        type_ = rec.get('type') or lib.OPERATION_TYPES.get(rec['operation'])
+        type_ = lib.record_type(rec)
         mask = rec['params'].get('mask')
         params = lib.user_params(type_, rec['params'])
     else:
@@ -989,7 +1008,17 @@ def op_effect(args):
     lib.reject_foreign_fields(effect_type, args)
     img = _image(args)
     operation = lib.EFFECT_OPERATIONS[effect_type]
-    defaults = _existing_ledger_params(img, args, operation) or lib.EFFECT_CREATE_DEFAULTS[effect_type]
+    if args.get('filter_id') is not None:
+        # drop_shadow, outline and outer_glow are all gegl:dropshadow, which `_existing_filter`'s
+        # operation check cannot tell apart; the ledger's `type` can.
+        rec = _ledger_get(img)[0].get(_existing_filter(img, args, operation).get_name())
+        existing_type = lib.record_type(rec)
+        if existing_type and existing_type != effect_type:
+            raise ValueError('filter %s is %s, not %s' % (args['filter_id'], existing_type, effect_type))
+    # A re-edit merges over the creation defaults, so a field a legacy record never stored (and
+    # the builder reads) falls back to its default instead of raising KeyError.
+    defaults = dict(lib.EFFECT_CREATE_DEFAULTS[effect_type])
+    defaults.update(_existing_ledger_params(img, args, operation) or {})
     params = builder(args, defaults)
     default_name = effect_type.replace('_', ' ').title()
     return _apply_filter(img, args, operation, params, default_name, type_=effect_type)
@@ -1015,7 +1044,7 @@ def _match_select_visible(dup, target):
     mask = target.get_mask()
     if mask is not None:
         dup.select_item(Gimp.ChannelOps.INTERSECT, mask)
-    Gimp.Selection.sharpen(dup)
+    _harden_selection(dup)
 
 
 def _match_render(img, layer, roi, previous_filter_indexes, mode):
@@ -1090,7 +1119,7 @@ def _match_measure_reference(img, layer, roi, previous_filter_indexes, channels,
             visible = Gimp.Selection.save(dup)
             Gimp.Selection.grow(dup, lib.match_scaled_px(opts['surround_px'], factor))
             dup.select_item(Gimp.ChannelOps.SUBTRACT, visible)
-            Gimp.Selection.sharpen(dup)
+            _harden_selection(dup)
             if Gimp.Selection.is_empty(dup):
                 raise ValueError(
                     'there is no canvas around the layer to sample (it fills the canvas); use '
@@ -1329,6 +1358,305 @@ def op_match_layer(args):
     }
 
 
+# ---- retouch ----------------------------------------------------------------------------
+
+# A generated (parametric) round brush: its size and hardness come from the context, so the
+# result does not depend on any brush file.
+_RETOUCH_BRUSH = '2. Hardness 050'
+
+
+def _retouch_marked(layer):
+    """Whether `layer` is a retouch layer this tool made (carries the retouch parasite)."""
+    return not layer.is_group() and layer.get_parasite(lib.RETOUCH_TAG) is not None
+
+
+def _retouch_source_tattoo(layer):
+    """The tattoo of the layer a retouch layer was copied from (stored in its parasite as
+    't:<tattoo>'), or None for a layer without one or with any other marker. A tattoo, unlike a
+    layer id, survives an XCF save and reload, so a checkpoint restore still finds the copy."""
+    para = layer.get_parasite(lib.RETOUCH_TAG)
+    if para is None:
+        return None
+    try:
+        text = bytes(para.get_data()).decode('ascii').strip('\x00')
+    except (TypeError, UnicodeDecodeError):
+        return None
+    if not text.startswith('t:'):
+        return None
+    try:
+        return int(text[2:])
+    except ValueError:
+        return None
+
+
+def _retouch_layer_above(img, layer):
+    """The retouch layer sitting directly above `layer` among its siblings that was made from
+    `layer` itself, or None."""
+    parent = layer.get_parent()
+    idx = _sibling_index(layer, parent)
+    if not idx:
+        return None
+    siblings = list(parent.get_children()) if parent is not None else list(img.get_layers())
+    above = siblings[idx - 1]
+    if _retouch_marked(above) and _retouch_source_tattoo(above) == layer.get_tattoo():
+        return above
+    return None
+
+
+def _retouch_make_layer(img, layer):
+    """A copy of `layer` named 'Retouch', directly above it, marked as ours (the parasite names the
+    source layer) and hidden entirely by a black layer mask: only the footprint of each stroke is
+    later revealed, so the composite outside the painted areas is exactly what it was."""
+    ledgered = _ledgered_filter_names_on(img, [layer])
+    if ledgered:
+        raise ValueError(
+            'cannot retouch %r on a copy: it carries Editmamei filter(s) %s, which a copy cannot '
+            "take along safely. Bake it first (gimp_bake) or use target 'in_place'."
+            % (layer.get_name(), ', '.join(repr(n) for n in sorted(set(ledgered))))
+        )
+    copy = layer.copy()
+    if copy is None:
+        raise lib.OpError('gimp_op_failed', 'GIMP could not duplicate this layer')
+    try:
+        copy.set_name(_unique_layer_name(img, 'Retouch'))
+        parent = layer.get_parent()
+        position = _sibling_index(layer, parent)
+        img.insert_layer(copy, parent, position if position is not None else 0)
+        _assert_layer_attached(img, copy, 'the retouch layer')
+        copy.add_mask(copy.create_mask(Gimp.AddMaskType.BLACK))
+        copy.attach_parasite(Gimp.Parasite.new(
+            lib.RETOUCH_TAG, Gimp.PARASITE_PERSISTENT, ('t:%d' % layer.get_tattoo()).encode('ascii')
+        ))
+    except Exception:
+        _discard_layer(img, copy)
+        raise
+    return copy
+
+
+def _retouch_paint(method, drawable, source, src_x, src_y, strokes, brush_size, hardness):
+    """One heal or clone stroke on `drawable`, sampling `source` from (src_x, src_y) -- image
+    pixels, for the first stroke point (verified live: both calls take image coordinates, not
+    layer ones). method 'reveal' instead paints white along the same strokes with the same brush
+    (on a layer mask: the footprint becomes visible). The context is pushed and popped so brush
+    state never leaks between calls."""
+    brush = Gimp.Brush.get_by_name(_RETOUCH_BRUSH)
+    if brush is None:
+        raise lib.OpError('gimp_op_failed', 'GIMP has no %r brush' % _RETOUCH_BRUSH)
+    flat = [float(v) for p in strokes for v in p]
+    Gimp.context_push()
+    try:
+        Gimp.context_enable_dynamics(False)
+        Gimp.context_set_brush(brush)
+        Gimp.context_set_brush_size(float(brush_size))
+        Gimp.context_set_brush_hardness(float(hardness))
+        Gimp.context_set_brush_angle(0.0)
+        Gimp.context_set_brush_aspect_ratio(0.0)
+        Gimp.context_set_brush_force(1.0)
+        Gimp.context_set_opacity(100.0)
+        Gimp.context_set_paint_mode(Gimp.LayerMode.NORMAL)
+        Gimp.context_set_antialias(True)
+        if method == 'reveal':
+            Gimp.context_set_foreground(Gegl.Color.new('white'))
+            ok = Gimp.paintbrush_default(drawable, flat)
+        elif method == 'clone':
+            ok = Gimp.clone(drawable, source, Gimp.CloneType.IMAGE, float(src_x), float(src_y), flat)
+        else:
+            ok = Gimp.heal(drawable, source, float(src_x), float(src_y), flat)
+    finally:
+        Gimp.context_pop()
+    if not ok:
+        raise lib.OpError('gimp_op_failed', 'GIMP %s did not paint' % method)
+
+
+def _retouch_disc_stats(img, drawable, cx, cy, r, inner=None):
+    """(mean, std, pixel count) of the value channel over a disc of radius `r` at (cx, cy), minus a
+    disc of radius `inner` when given; None when that region holds no pixels. Clobbers the
+    selection (the caller holds it)."""
+    Gimp.context_push()
+    try:
+        Gimp.context_set_feather(False)
+        Gimp.context_set_antialias(False)
+        img.select_ellipse(Gimp.ChannelOps.REPLACE, cx - r, cy - r, 2.0 * r, 2.0 * r)
+        if inner is not None:
+            img.select_ellipse(Gimp.ChannelOps.SUBTRACT, cx - inner, cy - inner, 2.0 * inner, 2.0 * inner)
+        # An empty selection reads as "everything" to the histogram, so refuse to measure it.
+        if Gimp.Selection.is_empty(img):
+            return None
+        mean, std, count = _match_hist(drawable, 'value')
+    finally:
+        Gimp.context_pop()
+    return (mean, std, count) if count > 0 else None
+
+
+def _retouch_pick_source(img, drawable, index, x, y, r, bounds):
+    """(dx, dy, score) of the best source offset for the spot: the candidate disc whose value
+    mean and spread are closest to the ring around the spot."""
+    candidates = lib.spot_candidates(x, y, r, bounds)
+    if not candidates:
+        raise ValueError(
+            'spot %d at (%g, %g) radius %g: no source area of that size fits inside the layer '
+            '(x %d..%d, y %d..%d); use a smaller radius or heal it by hand with a stroke'
+            % (index, x, y, r, bounds[0], bounds[2] - 1, bounds[1], bounds[3] - 1)
+        )
+    ring = _retouch_disc_stats(
+        img, drawable, x, y, max(lib.RETOUCH_SPOT_RING_OUTER * r, r + 3.0), inner=r
+    )
+    if ring is None:
+        raise ValueError('spot %d at (%g, %g): no surrounding pixels to compare against' % (index, x, y))
+    scored = []
+    for dx, dy in candidates:
+        stats = _retouch_disc_stats(img, drawable, x + dx, y + dy, r)
+        if stats is None:
+            continue
+        scored.append((dx, dy, lib.spot_score(stats[0], stats[1], ring[0], ring[1])))
+    best = lib.spot_pick_best(scored)
+    if best is None:
+        raise ValueError('spot %d at (%g, %g): no usable source area' % (index, x, y))
+    return best
+
+
+def op_retouch(args):
+    """Heal, clone or spot-heal pixels with a generated round brush.
+
+    Strokes and sources are image pixels (verified live: Gimp.heal / Gimp.clone take image
+    coordinates for both, whatever the layer offset). `target` 'retouch_layer' paints on a copy
+    named 'Retouch' directly above the layer, hidden by a black layer mask that each stroke then
+    reveals (so nothing outside the painted areas changes in the composite); it is reused on a
+    later call while it stays directly above the layer it was made from, and holds the original
+    pixels, so sampling reads them. 'in_place' paints the layer itself. The user's selection is
+    saved, cleared while painting (it would clip the retouch) and restored. A spot_heal picks every
+    spot's source before painting anything."""
+    img = _image(args)
+    if img.get_base_type() == Gimp.ImageBaseType.INDEXED:
+        raise ValueError('cannot retouch an indexed image: convert it to RGB first (gimp_convert_image_mode)')
+    layer = _layer(img, args)
+    opts = lib.validate_retouch_args(args)
+    if layer.is_group():
+        raise ValueError('cannot retouch a layer group: pick a pixel layer inside it')
+    if layer.is_text_layer():
+        raise ValueError('cannot retouch a text layer: rasterize it first (gimp_bake)')
+    if layer.get_lock_content():
+        raise ValueError('layer %r is locked; unlock it first' % layer.get_name())
+    if not layer.get_visible():
+        raise ValueError('layer %r is hidden; make it visible first' % layer.get_name())
+    method = opts['method']
+    on_copy = opts['target'] == 'retouch_layer' and not _retouch_marked(layer)
+    if on_copy:
+        normal = {Gimp.LayerMode.NORMAL, getattr(Gimp.LayerMode, 'NORMAL_LEGACY', Gimp.LayerMode.NORMAL)}
+        if layer.get_opacity() < 100.0 or layer.get_mode() not in normal:
+            raise ValueError(
+                "layer %r is not Normal mode at 100%% opacity, so a Retouch copy above it would "
+                "change the picture outside the painted areas: use target 'in_place'"
+                % layer.get_name()
+            )
+        if layer.get_mask() is not None:
+            raise ValueError(
+                "layer %r has a layer mask, which a Retouch copy cannot take along: use target "
+                "'in_place'" % layer.get_name()
+            )
+    cw, ch = img.get_width(), img.get_height()
+
+    def bounds_of(item):
+        _ok, ox, oy = item.get_offsets()
+        b = lib.retouch_bounds(ox, oy, item.get_width(), item.get_height(), cw, ch)
+        if b is None:
+            raise ValueError('layer %r is entirely outside the canvas' % item.get_name())
+        return b
+
+    bounds = bounds_of(layer)
+    source_layer = None
+    if method == 'clone' and args.get('source_layer_id') is not None:
+        source_layer = _layer(img, {'layer_id': args['source_layer_id']})
+        if source_layer.is_group():
+            raise ValueError('source_layer_id names a layer group: pick a pixel layer')
+        source_bounds = bounds_of(source_layer)
+    else:
+        source_bounds = bounds
+    if method == 'spot_heal':
+        lib.retouch_check_points([[x, y] for x, y, _r in opts['spots']], bounds, 'spot')
+        for i, (x, y, r) in enumerate(opts['spots']):
+            if not lib.spot_candidates(x, y, r, bounds):
+                raise ValueError(
+                    'spot %d at (%g, %g) radius %g: no source area of that size fits inside the '
+                    'layer (x %d..%d, y %d..%d); use a smaller radius or heal it by hand with a '
+                    'stroke' % (i, x, y, r, bounds[0], bounds[2] - 1, bounds[1], bounds[3] - 1)
+                )
+    else:
+        pts = opts['points']
+        dx, dy = opts['source_offset']
+        lib.retouch_check_points(pts, bounds, 'stroke')
+        lib.retouch_check_points([[x + dx, y + dy] for x, y in pts], source_bounds, 'source')
+
+    created = False
+    paint = layer
+    try:
+        with _PreservedSelection(img):
+            Gimp.Selection.none(img)
+            if on_copy:
+                paint = _retouch_layer_above(img, layer) or layer
+            picks = None
+            if method == 'spot_heal':
+                # Every source is chosen before anything is painted (or the copy made): a spot with
+                # no usable source then fails the whole call with nothing changed.
+                picks = [
+                    _retouch_pick_source(img, paint, i, x, y, r, bounds)
+                    for i, (x, y, r) in enumerate(opts['spots'])
+                ]
+                Gimp.Selection.none(img)  # measuring left a selection; it would clip the heal
+            if on_copy and paint is layer:
+                paint = _retouch_make_layer(img, layer)
+                created = True
+            try:
+                mask = paint.get_mask() if _retouch_marked(paint) else None
+                result = {
+                    'layer_id': paint.get_id(), 'layer_name': paint.get_name(),
+                    'created_layer': created, 'method': method, 'target': opts['target'],
+                }
+                if method == 'spot_heal':
+                    spots, bbox = [], None
+                    for (x, y, r), (dx, dy, score) in zip(opts['spots'], picks):
+                        brush = lib.retouch_spot_brush(r)
+                        stroke = lib.retouch_cover_stroke(x, y, r, brush, bounds)
+                        _retouch_paint(
+                            'heal', paint, paint, stroke[0][0] + dx, stroke[0][1] + dy, stroke,
+                            brush, lib.RETOUCH_SPOT_HARDNESS,
+                        )
+                        if mask is not None:
+                            reach = r + brush / 2.0  # the heal footprint: 2.3 x r unless capped
+                            _retouch_paint(
+                                'reveal', mask, None, 0, 0, [[x, y]], 2.0 * reach,
+                                lib.RETOUCH_REVEAL_HARDNESS,
+                            )
+                        bbox = lib.union_bbox_xywh(bbox, lib.retouch_painted_bbox(stroke, brush, bounds))
+                        spots.append({
+                            'x': x, 'y': y, 'radius': r, 'source_dx': dx, 'source_dy': dy,
+                            'score': round(score, 2),
+                        })
+                    result['spots'] = spots
+                    result['painted_bbox'] = bbox
+                else:
+                    pts = opts['points']
+                    dx, dy = opts['source_offset']
+                    _retouch_paint(
+                        method, paint, source_layer if source_layer is not None else paint,
+                        pts[0][0] + dx, pts[0][1] + dy, pts, opts['brush_size'], opts['hardness'],
+                    )
+                    if mask is not None:
+                        _retouch_paint(
+                            'reveal', mask, None, 0, 0, pts, opts['brush_size'], opts['hardness']
+                        )
+                    result['painted_bbox'] = lib.retouch_painted_bbox(pts, opts['brush_size'], bounds)
+                    result['brush_size'] = opts['brush_size']
+                    result['hardness'] = opts['hardness']
+            except Exception:
+                if created:
+                    _discard_layer(img, paint)
+                raise
+    finally:
+        _drop_proxies(img.get_id())
+    return result
+
+
 def op_filter(args):
     """Stack management: `op` in list | set_visibility | delete. There is deliberately no
     `reorder` -- `Gimp.DrawableFilter` exposes only delete/set_visible/update, and the PDB has no
@@ -1647,6 +1975,17 @@ def _refuse_if_masked_filters(img, op_name, before_hint='Rotate, flip or resize'
 ROTATE_DEPENDENT_OPERATIONS = frozenset({'gegl:vignette', 'gegl:motion-blur-linear', 'gegl:dropshadow'})
 
 
+def _rotation_sensitive(rec):
+    """Whether an arbitrary-angle rotation would misalign this ledger record's filter. A
+    gegl:dropshadow with no offset (outline, outer_glow, or a drop_shadow offset to 0,0) is
+    symmetric about the content, so only the offset ones are."""
+    operation = rec.get('operation')
+    if operation == 'gegl:dropshadow':
+        params = rec.get('params', {})
+        return bool(params.get('x') or params.get('y'))
+    return operation in ROTATE_DEPENDENT_OPERATIONS
+
+
 def _refuse_if_non_right_angle_with_tracked_effects(img, degrees, op_name):
     if lib.is_right_angle_degrees(degrees):
         return
@@ -1654,7 +1993,7 @@ def _refuse_if_non_right_angle_with_tracked_effects(img, degrees, op_name):
     live_names = _live_filter_names(img)
     tracked = sorted(
         name for name, rec in filters.items()
-        if name in live_names and rec.get('operation') in ROTATE_DEPENDENT_OPERATIONS
+        if name in live_names and _rotation_sensitive(rec)
     )
     if tracked:
         raise ValueError(
@@ -1689,18 +2028,21 @@ def _snapshot_effect_transform(img, op_name, transform_fn, layers=None):
     filters, _unknown = _ledger_get(img)
     if not filters:
         return {}
-    snapshot = {name: (rec['operation'], dict(rec['params'])) for name, rec in filters.items()}
+    snapshot = {
+        name: (rec['operation'], dict(rec['params']), lib.record_type(rec))
+        for name, rec in filters.items()
+    }
     planned = {}
     for layer in (layers if layers is not None else _all_layers(img)):
         for f in layer.get_filters():
             entry = snapshot.get(f.get_name())
             if entry is None or entry[0] != f.get_operation_name():
                 continue
-            operation, params = entry
-            new_params = transform_fn(operation, params, layer)
+            operation, params, type_ = entry
+            new_params = lib.clamp_effect_transform(type_, transform_fn(operation, params, layer))
             if new_params == params:
                 continue
-            lib.validate_effect_transform(op_name, operation, f.get_name(), new_params)
+            lib.validate_effect_transform(op_name, operation, f.get_name(), new_params, type_)
             planned[f.get_name()] = (operation, new_params)
     return planned
 
@@ -1973,16 +2315,40 @@ def op_preview(args):
         dup.delete()
 
 
-def _channel_stats_from(dup, layer, channels):
+class _ProxyMaskUnreliable(ValueError):
+    """A downscaled measurement copy cannot measure this mask: it is empty there, or mostly edge
+    pixels. Scaling blurs a thin mask's edges and the pixels under it into their neighbors (a
+    one-pixel line reads as a pale smear), so the caller re-measures at full resolution."""
+
+
+def _channel_stats_from(dup, layer, channels, mask=None, scaled=False):
+    """Per-channel stats of `layer` (in `dup`). With `mask` (a channel name that `dup` carries --
+    every render here is a duplicate of the document, so its channels came along, scaled or
+    cropped with it), only the pixels the channel selects at 50% or more are counted. `scaled`
+    marks a downscaled copy: a mask that is empty or edge-dominated there (see
+    `lib.MASK_EDGE_FRACTION_MAX`) raises `_ProxyMaskUnreliable`, not a plain refusal."""
     w, h = dup.get_width(), dup.get_height()
     buf = layer.get_buffer()
     rect = Gegl.Rectangle.new(0, 0, w, h)
     rgb = buf.get(rect, 1.0, "R'G'B' u8", Gegl.AbyssPolicy.NONE) if set(channels) - {'luminance'} else None
     lum = buf.get(rect, 1.0, "Y' u8", Gegl.AbyssPolicy.NONE) if 'luminance' in channels else None
+    flags = None
+    if mask is not None:
+        ch = _find_channel(dup, mask)
+        if ch is None:
+            raise lib.OpError('gimp_op_failed', 'the render lost the mask channel %r' % mask)
+        raw = bytes(ch.get_buffer().get(rect, 1.0, "Y' u8", Gegl.AbyssPolicy.NONE))
+        flags = lib.mask_flags(raw)
+        if scaled and not lib.mask_is_proxy_reliable(raw):
+            raise _ProxyMaskUnreliable('mask %r is too thin to measure on a downscaled copy' % mask)
+        if not any(flags):
+            raise ValueError('mask %r selects no pixels in the measured area' % mask)
     out = {}
     for ch in channels:
-        out[ch] = lib.channel_stats(lum if ch == 'luminance' else rgb[('red', 'green', 'blue').index(ch)::3])
-    return w, h, out
+        data = lum if ch == 'luminance' else rgb[('red', 'green', 'blue').index(ch)::3]
+        out[ch] = lib.channel_stats(lib.select_masked(data, flags) if flags is not None else data)
+    selected = flags.count(1) if flags is not None else w * h
+    return w, h, out, selected
 
 
 def op_histogram(args):
@@ -1991,13 +2357,22 @@ def op_histogram(args):
     filters). `region`: computed on the (mirrored) proxy when the region maps to at least
     `lib.MIN_PROXY_REGION_PX` on a side there, else a full-res crop -- same "too few proxy
     samples to mean anything" reasoning as `lib.MIN_PROXY_REGION_PX`'s own docstring; exact=True
-    always forces the full-res crop regardless of size."""
+    always forces the full-res crop regardless of size.
+
+    `mask` (a channel name): only the pixels that channel selects at 50% or more (an unweighted,
+    thresholded count -- no partial credit for feathered edges) enter the stats, and `pixels` is
+    that count. The channel travels with the measurement copy, so it is read at the copy's scale."""
     img = _image(args)
     channels = args.get('channels') or list(lib.HIST_CHANNELS)
     bad = [c for c in channels if c not in lib.HIST_CHANNELS]
     if bad:
         raise ValueError('channels must be drawn from %s, got %s' % (list(lib.HIST_CHANNELS), bad))
     exact = bool(args.get('exact', False))
+    mask = args.get('mask')
+    if mask is not None:
+        if not isinstance(mask, str) or not mask:
+            raise ValueError('mask must be a channel name')
+        _require_channel(img, mask)
     region = args.get('region')
     if region:
         lib.validate_region(region, img.get_width(), img.get_height())
@@ -2015,27 +2390,36 @@ def op_histogram(args):
                 ph = min(ph, dup.get_height() - py)
                 dup.crop(pw, ph, px, py)
                 layer = dup.flatten()
-                w, h, out = _channel_stats_from(dup, layer, channels)
+                w, h, out, selected = _channel_stats_from(dup, layer, channels, mask, scaled=True)
+                return {'exact': False, 'width': w, 'height': h, 'pixels': selected, 'channels': out,
+                        'unmirrored_filters': unmirrored, 'mask': mask}
+            except _ProxyMaskUnreliable:
+                pass  # the mask is finer than the proxy allows: measure the full-res crop below
             finally:
                 dup.delete()
-            return {'exact': False, 'width': w, 'height': h, 'pixels': w * h, 'channels': out,
-                    'unmirrored_filters': unmirrored}
         region = dict(region)  # fall through to the full-res path below
         exact = True
 
     unmirrored = []
-    if region:
-        dup, layer = _region_full_res(img, region)
-    elif exact:
-        dup, layer = _composite(img)
-    else:
+    if not region and not exact:
         dup, unmirrored = _proxy_render(img, 1024)
         layer = dup.get_layers()[0]
-    try:
-        w, h, out = _channel_stats_from(dup, layer, channels)
-    finally:
-        dup.delete()
-    result = {'exact': exact, 'width': w, 'height': h, 'pixels': w * h, 'channels': out}
+        try:
+            w, h, out, selected = _channel_stats_from(dup, layer, channels, mask, scaled=True)
+        except _ProxyMaskUnreliable:
+            exact = True  # a hairline mask lost to the scale-down: measure at full resolution
+        finally:
+            dup.delete()
+    if region or exact:
+        if region:
+            dup, layer = _region_full_res(img, region)
+        else:
+            dup, layer = _composite(img)
+        try:
+            w, h, out, selected = _channel_stats_from(dup, layer, channels, mask)
+        finally:
+            dup.delete()
+    result = {'exact': exact, 'width': w, 'height': h, 'pixels': selected, 'channels': out, 'mask': mask}
     if not region and not exact:
         result['unmirrored_filters'] = unmirrored
     return result
@@ -2079,8 +2463,8 @@ def op_compare(args):
                     h = min(ph, dup.get_height() - y)
                     dup.crop(w, h, x, y)
             base_layer, after_layer = base.flatten(), after.flatten()
-            _bw, _bh, before_stats = _channel_stats_from(base, base_layer, channels)
-            _aw, _ah, after_stats = _channel_stats_from(after, after_layer, channels)
+            _bw, _bh, before_stats, _bn = _channel_stats_from(base, base_layer, channels)
+            _aw, _ah, after_stats, _an = _channel_stats_from(after, after_layer, channels)
             deltas = {}
             for ch in channels:
                 b, a = before_stats[ch], after_stats[ch]
@@ -2109,12 +2493,12 @@ def op_compare(args):
             raise ValueError('regions mode needs both region_a and region_b')
         dup_a, layer_a = _region_full_res(img, region_a)
         try:
-            _wa, _ha, stats_a = _channel_stats_from(dup_a, layer_a, channels)
+            _wa, _ha, stats_a, _na = _channel_stats_from(dup_a, layer_a, channels)
         finally:
             dup_a.delete()
         dup_b, layer_b = _region_full_res(img, region_b)
         try:
-            _wb, _hb, stats_b = _channel_stats_from(dup_b, layer_b, channels)
+            _wb, _hb, stats_b, _nb = _channel_stats_from(dup_b, layer_b, channels)
         finally:
             dup_b.delete()
         return {'region_a': stats_a, 'region_b': stats_b, 'proxy': False}
@@ -2161,15 +2545,7 @@ def _export_stripped(dup, path, options=None):
         raise ValueError(
             'export path must end in .jpg, .jpeg, .png, .webp, .tif, or .tiff (got %r)' % ext
         )
-    if fmt in ('png', 'tiff'):
-        bit_depth = lib.validate_choice('bit_depth', options.get('bit_depth', 8), lib.BIT_DEPTHS)
-    else:
-        bit_depth = 8
-    target_precision = (
-        Gimp.Precision.U16_NON_LINEAR if bit_depth == 16 else Gimp.Precision.U8_NON_LINEAR
-    )
-    if dup.get_precision() != target_precision:
-        dup.convert_precision(target_precision)
+    _export_precision(dup, options if fmt in ('png', 'tiff') else {})
     try:
         dup.set_metadata(Gimp.Metadata.new())
     except Exception:
@@ -2201,6 +2577,68 @@ def _export_stripped(dup, path, options=None):
     cfg.set_property('image', dup)
     cfg.set_property('file', Gio.File.new_for_path(path))
     _strip_metadata(cfg, fmt)
+    if _has_editors_profile(dup):
+        cfg.set_property('include-color-profile', False)
+    _run_export(proc, cfg, path)
+
+
+def _has_editors_profile(img):
+    """Whether `img` carries the editor's built-in color profile (or none of its own), which
+    exports leave out: see `lib.profile_is_editors_own`."""
+    profile = img.get_color_profile()
+    if profile is None:
+        return lib.profile_is_editors_own(None)
+    texts = []
+    for getter in ('get_description', 'get_manufacturer', 'get_model', 'get_copyright'):
+        try:
+            texts.append(getattr(profile, getter)())
+        except Exception:
+            pass
+    return lib.profile_is_editors_own(texts)
+
+
+def _drop_psd_resource(path, resource_id):
+    """Rewrite the PSD at `path` without image resource `resource_id`. Only the header and the
+    resource section are read into memory; the layer and image data are copied through as they
+    are, to a temporary file in the same folder that then replaces the original."""
+    # Dot-prefixed, so nothing that lists the folder for files to serve can pick up a leftover.
+    fd, tmp = tempfile.mkstemp(dir=os.path.dirname(path) or '.', prefix='.', suffix='.tmp')
+    try:
+        with os.fdopen(fd, 'wb') as dst, open(path, 'rb') as src:
+            head = src.read(26)
+            color_len = src.read(4)
+            color = src.read(int.from_bytes(color_len, 'big'))
+            res_len = int.from_bytes(src.read(4), 'big')
+            section = src.read(res_len)
+            try:
+                if head[:4] != b'8BPS' or len(section) != res_len:
+                    raise ValueError('truncated header')
+                kept = lib.psd_resources_without(section, resource_id)
+            except ValueError:
+                raise lib.OpError('gimp_op_failed', 'could not finish %s' % os.path.basename(path))
+            dst.write(head + color_len + color + len(kept).to_bytes(4, 'big') + kept)
+            shutil.copyfileobj(src, dst, 1 << 20)
+        shutil.copymode(path, tmp)  # mkstemp's 0600 would otherwise replace the export's own mode
+        os.replace(tmp, path)
+    except BaseException:
+        try:
+            os.remove(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def _export_precision(img, options):
+    """Convert `img` to the requested 8/16-bit non-linear precision before it is written, so a
+    16/32-bit `precision` promotion at open time never leaks into an export that didn't ask for
+    it."""
+    bit_depth = lib.validate_choice('bit_depth', options.get('bit_depth', 8), lib.BIT_DEPTHS)
+    target = Gimp.Precision.U16_NON_LINEAR if bit_depth == 16 else Gimp.Precision.U8_NON_LINEAR
+    if img.get_precision() != target:
+        img.convert_precision(target)
+
+
+def _run_export(proc, cfg, path):
     # A failed write does not raise: run() returns an EXECUTION_ERROR status with GIMP's message
     # as the second value (verified live, GIMP 3.2.6, writing into a missing directory).
     result = proc.run(cfg)
@@ -2215,18 +2653,96 @@ def _export_stripped(dup, path, options=None):
         raise lib.OpError('gimp_op_failed', 'could not write %s: %s' % (name, detail))
 
 
+def _export_layered(img, path, options):
+    """Write `img` to a layered .psd, from a duplicate so the live document is never touched.
+
+    PSD has no live filters, so on the duplicate: hidden filters are deleted (they render nothing),
+    every other layer's filters are baked in place, and a group carrying its own filter is merged
+    into one raster layer (`lib.layered_bake_plan`; the exporter silently drops a group's filter,
+    verified live on GIMP 3.2.6). Layer masks, opacity, blend modes, visibility and the other
+    groups survive the round trip. Text layers are written as pixels: GIMP's PSD exporter has no
+    text-layer support.
+
+    Photoshop blends layers in gamma space while GIMP blends most modes in linear light, so a
+    layer below 100% opacity, or with a mode other than normal, can look different there
+    (measured: a 60% normal layer drifted ~22 levels on average; multiply ~4; screen and overlay
+    0). Those layers are listed in the result rather than silently "fixed", since no PSD setting
+    can carry GIMP's blend space.
+
+    Metadata: same rule as `_export_stripped` -- the duplicate's `Gimp.Metadata` is cleared and
+    file-psd-export's own include-exif/xmp/iptc/thumbnail switches are turned off (verified live
+    that with them off the file has no EXIF (1058) or XMP (1060) image resource)."""
+    lib.validate_choice('bit_depth', options.get('bit_depth', 8), lib.BIT_DEPTHS)
+    dup = img.duplicate()
+    try:
+        layers = _all_layers(dup)
+        rasterized_text = [l.get_name() for l in layers if l.is_text_layer()]
+        for layer in layers:
+            for f in layer.get_filters():
+                if not f.get_visible():
+                    f.delete()
+        nodes = []
+        for layer in layers:
+            parent = layer.get_parent()
+            nodes.append((layer.get_id(), parent.get_id() if parent else None, layer.is_group(),
+                          bool(layer.get_filters())))
+        merge_groups, bake_layers = lib.layered_bake_plan(nodes)
+        for layer_id in bake_layers:
+            _bake_one(Gimp.Layer.get_by_id(layer_id))
+        merged_groups = []
+        for group_id in merge_groups:
+            group = Gimp.Layer.get_by_id(group_id)
+            merged_groups.append(group.get_name())
+            group.merge()
+        _export_precision(dup, options)
+        try:
+            dup.set_metadata(Gimp.Metadata.new())
+        except Exception:
+            pass
+
+        proc = Gimp.get_pdb().lookup_procedure('file-psd-export')
+        cfg = proc.create_config()
+        cfg.set_property('image', dup)
+        cfg.set_property('file', Gio.File.new_for_path(path))
+        _strip_metadata(cfg, 'psd')
+        _run_export(proc, cfg, path)
+        # file-psd-export writes the profile whatever include-color-profile says (verified live,
+        # GIMP 3.2.6), so the editor's own is taken out of the written file instead.
+        if _has_editors_profile(dup):
+            _drop_psd_resource(path, lib.PSD_ICC_RESOURCE)
+
+        final = _all_layers(dup)
+        may_blend_differently = [
+            l.get_name() for l in final
+            if l.get_visible() and (l.get_opacity() < 100.0 or l.get_mode() != Gimp.LayerMode.NORMAL)
+        ]
+        return {
+            'layers': len(final),
+            'merged_groups': merged_groups,
+            'rasterized_text': rasterized_text,
+            'may_blend_differently': may_blend_differently,
+        }
+    finally:
+        dup.delete()
+
+
 def op_export(args):
-    """Writes path by extension: .xcf saves the live document, anything else exports a flattened
-    copy via `_export_stripped` (metadata stripped; jpeg quality 1-100 default 90; png compression
-    0-9 default 3 -- GIMP's own default of 9 measured far slower for negligible size gain; webp
-    quality 0-100 default 90 + lossless; tiff compression, default 'none'; png/tiff bit_depth 8 or
-    16, default 8).
+    """Writes path by extension: .xcf saves the live document, .psd writes a layered copy via
+    `_export_layered` (filters baked, metadata stripped, bit_depth 8 or 16, default 8), anything
+    else exports a flattened copy via `_export_stripped` (metadata stripped; jpeg quality 1-100
+    default 90; png compression 0-9 default 3 -- GIMP's own default of 9 measured far slower for
+    negligible size gain; webp quality 0-100 default 90 + lossless; tiff compression, default
+    'none'; png/tiff bit_depth 8 or 16, default 8).
+
+    `keep_alpha` (png / webp only) merges the visible layers onto a transparent canvas instead of
+    flattening onto the background color, so the file keeps its transparency.
 
     Flat exports flatten a duplicate first and save that. Handing the live document to
     file_save lets the exporter render the filters itself, which measured 9.3 s for a 24 MP
     JPEG with three curves; flatten (3.0 s) + save of the flat copy (1.0 s) gives the same pixels."""
     img = _image(args)
     path = lib.require(args, 'path')
+    keep_alpha = lib.validate_keep_alpha(args, path)
     if path.lower().endswith('.xcf'):
         # file_save reports a failed write by returning False, not by raising (verified live).
         if not Gimp.file_save(Gimp.RunMode.NONINTERACTIVE, img, Gio.File.new_for_path(path), None):
@@ -2235,8 +2751,19 @@ def op_export(args):
                 'could not save %s (check that the folder exists and is writable)'
                 % os.path.basename(path),
             )
+    elif os.path.splitext(path)[1].lower() in lib.LAYERED_EXPORT_FORMATS:
+        report = _export_layered(img, path, args)
+        return dict({'path': path, 'bytes': os.path.getsize(path)}, **report)
     else:
-        dup, _flat = _composite(img)
+        if keep_alpha:
+            dup = img.duplicate()
+            try:
+                _merge_visible_onto_transparent(dup)
+            except Exception:
+                dup.delete()
+                raise
+        else:
+            dup, _flat = _composite(img)
         try:
             _export_stripped(dup, path, args)
         finally:
@@ -2244,6 +2771,85 @@ def op_export(args):
     return {'path': path, 'bytes': os.path.getsize(path)}
 
 
+def _merge_visible_onto_transparent(dup):
+    """Merge `dup`'s visible layers onto a transparent canvas-sized layer, in place, and return the
+    one resulting RGBA layer (canvas-sized, at 0,0). Unlike `flatten`, nothing is composited onto the
+    context background, so empty areas stay transparent. An indexed or grayscale `dup` is converted
+    to RGB first."""
+    if dup.get_base_type() != Gimp.ImageBaseType.RGB:
+        dup.convert_rgb()
+    if not any(item.get_visible() for item in dup.get_layers()):
+        raise ValueError('the image has no visible layer to render')
+    w, h = dup.get_width(), dup.get_height()
+    bg = Gimp.Layer.new(dup, 'alpha-base', w, h, Gimp.ImageType.RGBA_IMAGE, 100.0, Gimp.LayerMode.NORMAL)
+    dup.insert_layer(bg, None, len(dup.get_layers()))
+    bg.fill(Gimp.FillType.TRANSPARENT)
+    return dup.merge_visible_layers(Gimp.MergeType.CLIP_TO_IMAGE)
+
+
+_INVERT_BYTES = bytes(255 - i for i in range(256))
+
+
+def op_render_region(args):
+    """Bridge-only (no tool): the pixels of `box` [x, y, w, h] (image pixels, clamped to the canvas)
+    as an 8-bit sRGB RGBA PNG at `out_path`, at full resolution, never downscaled. The source is the visible composite, or with `layer` / `layer_id` that one
+    layer rendered as if fully visible at 100% opacity in Normal mode (its mask and filters included,
+    as `render_layer` does). `hole_channel` names a channel whose value becomes transparency: output
+    alpha is multiplied by 255 - value, so the channel's selected pixels turn transparent. Works on a
+    temporary image that is always deleted; refuses a box past 4096 px a side or 16 megapixels."""
+    img = _image(args)
+    x, y, w, h = lib.validate_render_box(args.get('box'), img.get_width(), img.get_height())
+    out_path = lib.require(args, 'out_path')
+    if os.path.splitext(out_path)[1].lower() != '.png':
+        raise ValueError('out_path must end in .png')
+    hole_alpha = None
+    if args.get('hole_channel') is not None:
+        channel = _require_channel(img, args['hole_channel'])
+        hole = channel.get_buffer().get(Gegl.Rectangle.new(x, y, w, h), 1.0, "Y' u8", Gegl.AbyssPolicy.NONE)
+        hole_alpha = bytes(hole).translate(_INVERT_BYTES)
+
+    use_layer = args.get('layer_id') is not None or bool(args.get('layer'))
+    if use_layer:
+        layer = _layer(img, args)
+        if layer.is_group():
+            raise ValueError('cannot render a layer group: pick a pixel layer')
+        tmp = Gimp.Image.new(w, h, Gimp.ImageBaseType.RGB)
+    else:
+        tmp = img.duplicate()
+    try:
+        if use_layer:
+            nl = Gimp.Layer.new_from_drawable(layer, tmp)
+            tmp.insert_layer(nl, None, 0)
+            _ok, ox, oy = layer.get_offsets()
+            nl.set_offsets(ox - x, oy - y)
+            nl.set_visible(True)
+            nl.set_opacity(100.0)
+            nl.set_mode(Gimp.LayerMode.NORMAL)
+        else:
+            tmp.crop(w, h, x, y)
+        merged = _merge_visible_onto_transparent(tmp)
+        if tmp.get_color_profile() is not None:
+            tmp.convert_color_profile(
+                Gimp.ColorProfile.new_rgb_srgb(), Gimp.ColorRenderingIntent.RELATIVE_COLORIMETRIC, True
+            )
+        if tmp.get_width() != w or tmp.get_height() != h or merged.get_width() != w or merged.get_height() != h:
+            raise lib.OpError('gimp_op_failed', 'the rendered region came out the wrong size')
+        if hole_alpha is not None:
+            mask = merged.create_mask(Gimp.AddMaskType.WHITE)
+            merged.add_mask(mask)
+            buf = mask.get_buffer()
+            # "Y u8" (linear): a mask multiplies alpha by its linear value, so 255 - v lands on
+            # alpha as exactly (255 - v) / 255 -- the primed format would apply a gamma curve.
+            buf.set(Gegl.Rectangle.new(0, 0, w, h), "Y u8", hole_alpha)
+            buf.flush()
+            mask.update(0, 0, w, h)
+            merged.remove_mask(Gimp.MaskApplyMode.APPLY)
+        _export_stripped(tmp, out_path)
+        return {'path': out_path, 'width': w, 'height': h, 'box': [x, y, w, h]}
+    finally:
+        tmp.delete()
+
+
 def _replace_named_channel(img, name, w, h):
     """Remove any existing channel called `name` and insert a fresh, black-filled one of the
     image's own size -- `op_create_mask`'s replace-by-name semantics. Restores the image's
@@ -2680,7 +3286,8 @@ def _resolve_parent_group(img, args):
     parent_id = args.get('parent_group')
     if parent_id is None:
         return None
-    parent = Gimp.Layer.get_by_id(int(parent_id))
+    gid = lib.gimp_id(parent_id)
+    parent = Gimp.Layer.get_by_id(gid) if gid is not None else None
     owner = _owning_image(parent)
     if parent is None or owner is None or owner.get_id() != img.get_id():
         raise ValueError('no layer with id %s on image %s' % (parent_id, img.get_id()))
@@ -2785,7 +3392,7 @@ _LAYER_CAPABLE_BASE_TYPES = {
 }
 
 
-def _layer_type_for(img):
+def _layer_type_for(img, tool='gimp_layer op=create'):
     """The `Gimp.ImageType` a new layer should use so it matches `img`'s own color model instead
     of relying on GIMP's own silent coercion (verified live: an RGBA layer inserted into a
     grayscale image is quietly converted to GRAYA on insert -- this asks for the right type up
@@ -2794,7 +3401,7 @@ def _layer_type_for(img):
     layer_type = _LAYER_CAPABLE_BASE_TYPES.get(base)
     if layer_type is None:
         raise ValueError(
-            'gimp_layer op=create does not support %s images -- only RGB and grayscale' % base.value_nick
+            '%s does not support %s images -- only RGB and grayscale' % (tool, base.value_nick)
         )
     return layer_type
 
@@ -3285,6 +3892,171 @@ def _resolved_font(fonts, font_name):
     return fonts[name]
 
 
+def _text_extents(font, size_px, text):
+    """GIMP's own dynamic-mode layout extents of `text` at `size_px`."""
+    return Gimp.text_get_extents_font(text, size_px, font)
+
+
+def _text_line_metrics(layer):
+    """(single_line_height, pitch) in px for the layer's font and size: the pitch is the line
+    height plus the layer's line spacing, measured from GIMP's extents of one line and of a
+    block of `TEXT_LINE_PITCH_SAMPLE_LINES` (averaged, so a fractional line height does not
+    round into a whole-pixel error that grows with the line count)."""
+    font, size_px = layer.get_font(), _text_size_px(layer)
+    n = lib.TEXT_LINE_PITCH_SAMPLE_LINES
+    one = float(_text_extents(font, size_px, 'Ag').height)
+    many = float(_text_extents(font, size_px, '\n'.join(['Ag'] * n)).height)
+    return one, max(1.0, (many - one) / (n - 1) + layer.get_line_spacing())
+
+
+def _text_ink_extent(layer):
+    """(index of the last layer row holding any ink, -1 for a blank layer; whether the last
+    column holds any ink)."""
+    w, h = layer.get_width(), layer.get_height()
+    data = bytes(layer.get_buffer().get(Gegl.Rectangle.new(0, 0, w, h), 1.0, 'A u8', Gegl.AbyssPolicy.NONE))
+    trimmed = data.rstrip(b'\x00')
+    bottom = (len(trimmed) - 1) // w if trimmed else -1
+    return bottom, any(data[w - 1::w])
+
+
+def _text_set_box(layer, width, height):
+    """Switch the layer to GIMP's fixed box mode at `width` x `height` (`TextLayer.resize`;
+    verified live on 3.2.6: the text wraps at the box width and clips at its height, and the box
+    survives later text / font / size changes)."""
+    if not layer.resize(width, height):
+        raise lib.OpError('gimp_op_failed', 'GIMP could not set the text box to %dx%d' % (width, height))
+
+
+def _text_is_boxed(layer):
+    """Whether this tool put the layer in a fixed box (`lib.TEXT_BOX_TAG`; GIMP cannot report it)."""
+    return layer.get_parasite(lib.TEXT_BOX_TAG) is not None
+
+
+def _text_enforce_box(layer):
+    """For a layer tagged as boxed, put it in box mode at its current size again and return True;
+    False for an untagged layer. The tag is what exempts an edit from the pre-render size
+    estimate, and it outlives a switch back to dynamic text (in the GIMP UI, or in a file made
+    elsewhere), so an edit that relies on it re-asserts the box it stands for. One render, at a
+    size the layer already has."""
+    if not _text_is_boxed(layer):
+        return False
+    _text_set_box(layer, layer.get_width(), layer.get_height())
+    return True
+
+
+def _text_mark_boxed(layer):
+    layer.attach_parasite(Gimp.Parasite.new(lib.TEXT_BOX_TAG, Gimp.PARASITE_PERSISTENT, b'1'))
+
+
+def _text_layout_height(single, pitch, lines):
+    return single + (lines - 1) * pitch
+
+
+def _text_wrapped_lines(layer, width, precision, limit_h=None):
+    """How many lines the layer's text wraps to in a box `width` wide, read from a real render:
+    the box is made tall enough that nothing clips and the last inked row gives the line count
+    (GIMP renders text synchronously, so the pixels are current right after the resize). With
+    `limit_h` the box is only a little taller than that limit, enough to tell whether the text
+    fits; a probe cut short by the scan cap, a glyph inked in the last column, or text that
+    renders blank (a glyph wider than the box), reports `lib.TEXT_OVERFLOW_LINES` (the caller
+    probes with left alignment, so only a glyph that does not fit reaches the last column).
+    Leaves the layer's box at the probe height; callers set the final box."""
+    single, pitch = _text_line_metrics(layer)
+    text = layer.get_text()
+    explicit = text.count('\n') + 1
+    cap = lib.text_scan_cap(width, precision)
+    if limit_h is not None:
+        scan_h, clamped = lib.fit_probe_plan(width, limit_h, pitch, precision)
+    else:
+        unwrapped = float(_text_extents(layer.get_font(), _text_size_px(layer), text).width)
+        scan_h = min(cap, int(math.ceil((explicit + 2 * math.ceil(unwrapped / width) + 1) * pitch)))
+    while True:
+        _text_set_box(layer, width, scan_h)
+        bottom, right_ink = _text_ink_extent(layer)
+        if limit_h is not None:
+            blank = bottom < 0 and bool(text.strip())  # GIMP draws nothing when no glyph fits
+            if right_ink or blank or lib.fit_probe_overflows(bottom, scan_h, clamped):
+                return lib.TEXT_OVERFLOW_LINES
+            return lib.wrapped_line_count(bottom, pitch, explicit)
+        # Ink on the probe's last row means it may be clipped: the probe grows until the text
+        # clears it.
+        if bottom < scan_h - 1:
+            return lib.wrapped_line_count(bottom, pitch, explicit)
+        if scan_h >= cap:
+            raise ValueError(
+                'the text wraps to more than %d px tall at box width %d; use a wider box, a '
+                'smaller font_size or less text' % (cap, width)
+            )
+        scan_h = min(cap, scan_h * 2)
+
+
+def _text_grow_box(layer, width, precision):
+    """Set the box to `width` wide and as tall as the wrapped text needs."""
+    lines = _text_wrapped_lines(layer, width, precision)
+    single, pitch = _text_line_metrics(layer)
+    height = max(1, int(math.ceil(_text_layout_height(single, pitch, lines))))
+    lib.check_text_layer_size(width, height)
+    lib.check_text_box_area(width, height, precision)
+    _text_set_box(layer, width, height)
+
+
+def _text_fit(layer, width, height, max_px, min_px, precision):
+    """Find approximately the largest size in [min_px, max_px] at which the wrapped text fits
+    `width` x `height` (`lib.fit_font_size`, whole pixels, bounded probes) and leave it applied in
+    that box. Returns (fitted, probes).
+
+    Probes run left-aligned: right, centered and filled lines legitimately end at the box's right
+    edge, which would read as overflow, and alignment does not change where lines break."""
+    def fits(size):
+        layer.set_font_size(size, Gimp.Unit.pixel())
+        single, pitch = _text_line_metrics(layer)
+        lines = _text_wrapped_lines(layer, width, precision, limit_h=height)
+        return _text_layout_height(single, pitch, lines) <= height
+
+    justification = layer.get_justification()
+    left = Gimp.TextJustification.LEFT
+    if justification != left:
+        layer.set_justification(left)
+    try:
+        size, fitted, probes = lib.fit_font_size(max_px, min_px, fits)
+    finally:
+        if justification != left:
+            layer.set_justification(justification)
+    layer.set_font_size(size, Gimp.Unit.pixel())
+    _text_set_box(layer, width, height)
+    return fitted, probes
+
+
+def _text_apply_box(layer, box, fit, min_px, max_px, precision):
+    """Put `layer` in a fixed box (`box` = (width, height or None)); with `fit`, also find the
+    largest font size that fits. Returns the extra result fields."""
+    width, height = box
+    extra = {}
+    if fit:
+        t0 = time.time()
+        fitted, probes = _text_fit(layer, width, height, max_px, min_px, precision)
+        extra = {'fitted': fitted, 'fit_probes': probes, 'fit_seconds': round(time.time() - t0, 3)}
+    elif height is None:
+        _text_grow_box(layer, width, precision)
+    else:
+        lib.check_text_layer_size(width, height)
+        _text_set_box(layer, width, height)
+    return extra
+
+
+def _text_check_box_request(box, fit, precision):
+    """Refusals that need no render: the box area cap, and fit's probe-size limit."""
+    lib.check_text_box_area(box[0], box[1] or 1, precision)
+    if fit:
+        lib.check_text_fit_box(box[0], box[1], precision)
+
+
+def _text_box_fields(layer, extra):
+    fields = {'box': {'width': layer.get_width(), 'height': layer.get_height()}}
+    fields.update(extra)
+    return fields
+
+
 def _op_text_create(img, args):
     text = lib.validate_text_content(lib.require(args, 'text'))
     size_pt = lib.validate_font_size_pt(args.get('font_size', lib.TEXT_DEFAULT_FONT_PT))
@@ -3292,14 +4064,26 @@ def _op_text_create(img, args):
     y = int(args.get('y', 100))
     _validated_move_offset(img, x, y)
     rgb = lib.validate_text_rgb(args)
+    box = lib.validate_text_box(args['box']) if args.get('box') is not None else None
+    fit, min_px = lib.validate_text_fit(args, box)
     justification = None
     if args.get('alignment') is not None:
         justification = _JUSTIFICATIONS[lib.justification_nick(args['alignment'])]
     _layer_type_for(img)  # refuses image modes a text layer cannot be added to (indexed)
     font = _resolved_font(_font_list(), args.get('font_name'))
     size_px = lib.pt_to_px(size_pt, _image_ppi(img))
-    _check_estimated_text_size(text, font, size_px, img)
-    layer = Gimp.TextLayer.new(img, text, font, size_px, Gimp.Unit.pixel())
+    precision = _transform_layer_precision(img)
+    if box is None:
+        _check_estimated_text_size(text, font, size_px, img)
+        create_px = size_px
+    else:
+        # In a box the layer is bounded by the box, not by the unwrapped text, so there is no
+        # unwrapped-size estimate to take: the layer starts small and is boxed before it is
+        # given its size.
+        lib.check_text_layer_size(box[0], box[1] or 1)
+        _text_check_box_request(box, fit, precision)
+        create_px = min(size_px, _TEXT_PROBE_PX)
+    layer = Gimp.TextLayer.new(img, text, font, create_px, Gimp.Unit.pixel())
     if layer is None:
         raise lib.OpError('gimp_op_failed', 'GIMP could not create the text layer')
     try:
@@ -3310,9 +4094,17 @@ def _op_text_create(img, args):
             _set_text_color(layer, rgb)
         if justification is not None:
             layer.set_justification(justification)
+        extra = {}
+        if box is not None:
+            _text_set_box(layer, box[0], box[1] or max(1, int(math.ceil(create_px))))
+            _text_mark_boxed(layer)
+            layer.set_font_size(size_px, Gimp.Unit.pixel())
+            extra = _text_apply_box(layer, box, fit, min_px, size_px, precision)
         lib.check_text_layer_size(layer.get_width(), layer.get_height())
         layer.set_offsets(x, y)
         record = _text_record(layer)
+        if box is not None:
+            record.update(_text_box_fields(layer, extra))
     except Exception:
         _discard_layer(img, layer)
         raise
@@ -3357,9 +4149,10 @@ def _op_text_edit(img, args, apply_fn, precheck_fn=None):
 
 def _op_text_set_content(img, args):
     text = lib.validate_text_content(lib.require(args, 'text'))
+    # A boxed layer is bounded by its box, so there is no unwrapped-size estimate to take.
     return _op_text_edit(
         img, args, lambda layer: layer.set_text(text),
-        precheck_fn=lambda layer: _check_estimated_text_size(
+        precheck_fn=lambda layer: None if _text_enforce_box(layer) else _check_estimated_text_size(
             text, layer.get_font(), _text_size_px(layer), img, layer),
     )
 
@@ -3371,6 +4164,8 @@ def _op_text_set_font(img, args):
     new_size_px = lib.pt_to_px(size_pt, _image_ppi(img)) if size_pt is not None else None
 
     def precheck_fn(layer):
+        if _text_enforce_box(layer):
+            return
         size_px = new_size_px if new_size_px is not None else _text_size_px(layer)
         _check_estimated_text_size(layer.get_text(), font, size_px, img, layer)
 
@@ -3399,12 +4194,85 @@ def _op_text_set_alignment(img, args):
     return _op_text_edit(img, args, lambda layer: layer.set_justification(justification))
 
 
+def _text_trial_layout(layer, box, fit, min_px, size_px, precision):
+    """Dry-run a box (and fit) for a layer GIMP has no way to take back out of box mode: the
+    same text, font, spacing and size on a throwaway layer in a scratch image, so a refusal or
+    failure leaves the real layer untouched. Returns (final size px, width, height, extra)."""
+    font = layer.get_font() or _resolved_font(_font_list(), None)
+    tmp = Gimp.Image.new(1, 1, Gimp.ImageBaseType.RGB)
+    try:
+        trial = Gimp.TextLayer.new(tmp, layer.get_text(), font, _TEXT_PROBE_PX, Gimp.Unit.pixel())
+        if trial is None:
+            raise lib.OpError('gimp_op_failed', 'GIMP could not lay out the text to fit the box')
+        tmp.insert_layer(trial, None, 0)
+        trial.set_justification(layer.get_justification())
+        trial.set_letter_spacing(layer.get_letter_spacing())
+        trial.set_line_spacing(layer.get_line_spacing())
+        trial.set_indent(layer.get_indent())
+        trial.set_kerning(layer.get_kerning())
+        _text_set_box(trial, box[0], max(1, int(math.ceil(_TEXT_PROBE_PX))))
+        trial.set_font_size(size_px, Gimp.Unit.pixel())
+        extra = _text_apply_box(trial, box, fit, min_px, size_px, precision)
+        width, height = trial.get_width(), trial.get_height()
+        lib.check_text_layer_size(width, height)
+        return _text_size_px(trial), width, height, extra
+    finally:
+        tmp.delete()
+
+
+def _op_text_set_box(img, args):
+    """Put an existing text layer in a fixed box (re-wrapping its text), optionally fitting the
+    size. `font_size` (points) sets the size to start from; default is the layer's current size.
+    A layer not yet boxed is laid out on a throwaway layer first (GIMP cannot take a layer back
+    out of box mode, and changing its size unboxed would re-render the unwrapped text); a boxed
+    one is changed in place and rolled back to its previous box on failure."""
+    box = lib.validate_text_box(lib.require(args, 'box'))
+    fit, min_px = lib.validate_text_fit(args, box)
+    size_pt = lib.validate_font_size_pt(args['font_size']) if args.get('font_size') is not None else None
+    layer = _text_target(img, args)
+    precision = _transform_layer_precision(img)
+    _text_check_box_request(box, fit, precision)
+    start_px = lib.pt_to_px(size_pt, _image_ppi(img)) if size_pt is not None else _text_size_px(layer)
+    state = _text_state(layer)
+    prev_box = (layer.get_width(), layer.get_height())
+    was_boxed = _text_enforce_box(layer)
+    try:
+        if was_boxed:
+            if size_pt is not None:
+                layer.set_font_size(start_px, Gimp.Unit.pixel())
+            extra = _text_apply_box(layer, box, fit, min_px, _text_size_px(layer), precision)
+        else:
+            final_px, width, height, extra = _text_trial_layout(
+                layer, box, fit, min_px, start_px, precision)
+            # Boxed (and so bounded) before its size changes.
+            _text_set_box(layer, box[0], max(1, int(math.ceil(_TEXT_PROBE_PX))))
+            _text_mark_boxed(layer)
+            if fit or size_pt is not None:
+                layer.set_font_size(final_px, Gimp.Unit.pixel())
+            _text_set_box(layer, width, height)
+        lib.check_text_layer_size(layer.get_width(), layer.get_height())
+    except Exception:
+        _text_restore(layer, state)
+        if was_boxed:
+            try:
+                layer.resize(prev_box[0], prev_box[1])
+            except Exception:
+                pass
+        raise
+    finally:
+        _drop_proxies(img.get_id())
+    record = _text_record(layer)
+    record.update(_text_box_fields(layer, extra))
+    return record
+
+
 TEXT_OPS = {
     'create': _op_text_create,
     'set_content': _op_text_set_content,
     'set_font': _op_text_set_font,
     'set_color': _op_text_set_color,
     'set_alignment': _op_text_set_alignment,
+    'set_box': _op_text_set_box,
 }
 
 
@@ -3998,7 +4866,7 @@ def _ensure_layer_alpha(layer):
     return True
 
 
-def _tracked_effect_names_on(img, layer):
+def _tracked_effect_names_on(img, layer, rotation_only=False):
     """Live, ledgered position/direction-dependent EFFECT filter names (vignette, motion_blur,
     drop_shadow -- `ROTATE_DEPENDENT_OPERATIONS`) anywhere in `layer`'s own subtree (itself, or
     every descendant for a group target) -- NOT its ancestors: an ancestor group's own filter is
@@ -4008,6 +4876,8 @@ def _tracked_effect_names_on(img, layer):
     subtree = _layer_subtree(layer)
     live_names = {f.get_name() for l in subtree for f in l.get_filters()}
     filters, _unknown = _ledger_get(img)
+    if rotation_only:  # an offset-free dropshadow (outline, outer_glow) survives any angle
+        return sorted(name for name in live_names if _rotation_sensitive(filters.get(name, {})))
     return sorted(
         name for name in live_names
         if filters.get(name, {}).get('operation') in ROTATE_DEPENDENT_OPERATIONS
@@ -4027,7 +4897,7 @@ def _refuse_if_tracked_effects_on(img, op_name, layer, reason):
 def _refuse_if_non_right_angle_tracked_effects_on(img, degrees, op_name, layer):
     if lib.is_right_angle_degrees(degrees):
         return
-    tracked = _tracked_effect_names_on(img, layer)
+    tracked = _tracked_effect_names_on(img, layer, rotation_only=True)
     if tracked:
         raise ValueError(
             '%s cannot use an arbitrary angle (%.4g°) while effect filter(s) %s are present on '
@@ -4397,6 +5267,29 @@ def _capture_selection(img, w, h, scratch):
     scratch.update(0, 0, w, h)
 
 
+def _harden_selection(img):
+    """Re-threshold the active selection at 50%: what GIMP's `Selection.sharpen` does, done on the
+    mask's own bytes instead. On macOS GIMP 3.2.6 `Selection.sharpen` leaves the selection empty
+    (a fully selected pixel reads 0 afterwards), while reading and writing the mask buffer works
+    on every platform. Banded, so a very large mask is never held twice in memory."""
+    if Gimp.Selection.is_empty(img):
+        return
+    w, h = img.get_width(), img.get_height()
+    source = img.get_selection().get_buffer()
+
+    def _fill(scratch):
+        out = scratch.get_buffer()
+        for y in range(0, h, lib.HARDEN_BAND_ROWS):
+            rect = Gegl.Rectangle.new(0, y, w, min(lib.HARDEN_BAND_ROWS, h - y))
+            band = source.get(rect, 1.0, "Y' u8", Gegl.AbyssPolicy.NONE)
+            out.set(rect, "Y' u8", lib.harden_mask_bytes(band))
+        out.flush()
+        scratch.update(0, 0, w, h)
+        img.select_item(Gimp.ChannelOps.REPLACE, scratch)
+
+    _with_scratch_channel(img, w, h, _fill)
+
+
 def _shrink_edge_locked(img, px):
     """`Gimp.Selection.shrink` that does not erode from the canvas edge. GIMP's own shrink treats
     the area outside the canvas as unselected (its PDB call hardcodes edge-lock off), so a
@@ -4618,14 +5511,14 @@ def op_modify_mask(args):
         elif how == 'invert':
             Gimp.Selection.invert(img)
         elif how == 'harden':
-            Gimp.Selection.sharpen(img)
+            _harden_selection(img)
         elif how == 'smooth':
             # Round off jaggies: feather, then re-threshold at 50%. `px` is optional here (unlike
             # the four ops above) -- a plain smoothing pass with no caller-chosen radius is still
             # meaningful, so it floors at 1.0 rather than requiring one.
             px = lib.validate_range('px', args.get('px', 0), 0, lib.MAX_FEATHER_PX)
             Gimp.Selection.feather(img, max(px, 1.0))
-            Gimp.Selection.sharpen(img)
+            _harden_selection(img)
         else:
             raise ValueError('unknown op %r' % how)
         return _selection_to_channel(img, out)
@@ -4692,6 +5585,125 @@ def op_layer_mask(args):
             'has_mask': layer.get_mask() is not None}
 
 
+def _fill_color(rgb, alpha=1.0):
+    return Gegl.Color.new('#%02x%02x%02x%02x' % (rgb[0], rgb[1], rgb[2], int(round(alpha * 255))))
+
+
+def _build_fill_gradient(stops):
+    """A temporary custom gradient through `stops`: one linear segment between each pair of
+    neighbors of `lib.gradient_ramp`. The caller deletes it (`Gimp.Gradient` is a resource that
+    would otherwise outlive the call)."""
+    ramp = lib.gradient_ramp(stops)
+    count = len(ramp) - 1
+    gradient = Gimp.Gradient.new('editmamei-fill-tmp')
+    try:
+        # GIMP clamps a segment's new right edge between its own middle and the next segment's
+        # middle, so edges cannot be placed after a uniform split (a stop at 0.1 would land on
+        # the first middle). Instead, grow one segment at a time: split the last segment, park
+        # the two halves' middles at their outer edges, then set the edge, which can now go
+        # anywhere in [previous stop, 1]. Equal offsets give a zero-width segment, a hard edge.
+        for i in range(count - 1):
+            gradient.segment_range_split_midpoint(i, i)
+            gradient.segment_set_middle_pos(i, gradient.segment_get_left_pos(i)[-1])
+            gradient.segment_set_middle_pos(i + 1, gradient.segment_get_right_pos(i + 1)[-1])
+            gradient.segment_set_right_pos(i, ramp[i + 1][0])
+        for i in range(count):
+            (_lo, lrgb, la), (_hi, rrgb, ra) = ramp[i], ramp[i + 1]
+            gradient.segment_set_left_color(i, _fill_color(lrgb, la))
+            gradient.segment_set_right_color(i, _fill_color(rrgb, ra))
+        gradient.segment_range_set_blending_function(0, count - 1, Gimp.GradientSegmentType.LINEAR)
+        gradient.segment_range_set_coloring_type(0, count - 1, Gimp.GradientSegmentColor.RGB)
+        # Segment midpoints (the blend's bias) are re-centered last: moving an edge leaves them where they were.
+        for i in range(count):
+            lo, hi = gradient.segment_get_left_pos(i)[-1], gradient.segment_get_right_pos(i)[-1]
+            gradient.segment_set_middle_pos(i, (lo + hi) / 2.0)
+    except Exception:
+        gradient.delete()
+        raise
+    return gradient
+
+
+def op_fill(args):
+    """Add a new canvas-sized layer filled with a solid color or a linear/radial gradient.
+
+    The layer goes directly above the target layer (`layer` / `layer_id`, else the selected one),
+    inside its group. A gradient is rendered by GIMP's own gradient engine through a temporary
+    custom gradient (one linear RGB segment per pair of stops, interpolated in perceptual sRGB
+    -- see the context set-up below) that is deleted again; the gradient context is pushed and
+    popped. The selection is saved, cleared while painting (it would clip the fill) and restored.
+    `mask` names a channel that becomes the new layer's layer mask (white where selected)."""
+    img = _image(args)
+    if img.get_base_type() == Gimp.ImageBaseType.INDEXED:
+        raise ValueError('cannot fill on an indexed image: convert it to RGB first (gimp_convert_image_mode)')
+    layer_type = _layer_type_for(img, 'gimp_fill')
+    # The new layer is canvas-sized: held to the same precision-aware cap as a new document.
+    width, height = lib.validate_document_dims(img.get_width(), img.get_height(), _transform_layer_precision(img))
+    opts = lib.validate_fill_args(args, width, height)
+    mask_channel = _require_channel(img, opts['mask']) if opts['mask'] is not None else None
+    layers = img.get_layers()
+    if layers:
+        target = _layer(img, args)
+        parent = target.get_parent()
+        position = _sibling_index(target, parent)
+    else:
+        parent, position = None, 0
+    name = _unique_layer_name(img, opts['name'])
+    layer = Gimp.Layer.new(img, name, width, height, layer_type, 100.0, Gimp.LayerMode.NORMAL)
+    gradient = None
+    try:
+        img.insert_layer(layer, parent, position or 0)
+        _assert_layer_attached(img, layer, 'the fill layer')
+        with _PreservedSelection(img):
+            Gimp.Selection.none(img)
+            if opts['op'] == 'solid':
+                Gimp.context_push()
+                try:
+                    Gimp.context_set_foreground(_fill_color(opts['color']))
+                    ok = layer.fill(Gimp.FillType.FOREGROUND)
+                finally:
+                    Gimp.context_pop()
+                if not ok:
+                    raise lib.OpError('gimp_op_failed', 'GIMP could not fill the new layer')
+            else:
+                layer.fill(Gimp.FillType.TRANSPARENT)
+                gradient = _build_fill_gradient(opts['stops'])
+                if opts['op'] == 'linear_gradient':
+                    (x1, y1), (x2, y2) = opts['start'], opts['end']
+                    gtype = Gimp.GradientType.LINEAR
+                else:
+                    x1, y1 = opts['center']
+                    x2, y2 = x1 + opts['radius'], y1
+                    gtype = Gimp.GradientType.RADIAL
+                Gimp.context_push()
+                try:
+                    Gimp.context_set_gradient(gradient)
+                    Gimp.context_set_gradient_reverse(False)
+                    Gimp.context_set_gradient_repeat_mode(Gimp.RepeatMode.NONE)
+                    Gimp.context_set_gradient_blend_color_space(Gimp.GradientBlendColorSpace.RGB_PERCEPTUAL)
+                    Gimp.context_set_paint_mode(Gimp.LayerMode.NORMAL)
+                    Gimp.context_set_opacity(100.0)
+                    layer.edit_gradient_fill(gtype, 0.0, False, 1, 0, False, x1, y1, x2, y2)
+                finally:
+                    Gimp.context_pop()
+            if mask_channel is not None:
+                img.select_item(Gimp.ChannelOps.REPLACE, mask_channel)
+                mask = layer.create_mask(Gimp.AddMaskType.SELECTION)
+                if not layer.add_mask(mask):
+                    mask.delete()  # never attached, so nothing else would free it
+                    raise lib.OpError('gimp_op_failed', 'GIMP could not attach the mask to the new layer')
+        layer.set_mode(getattr(Gimp.LayerMode, lib.FILL_MODES[opts['mode']]))
+        layer.set_opacity(opts['opacity'])
+    except Exception:
+        _discard_layer(img, layer)
+        raise
+    finally:
+        if gradient is not None:
+            gradient.delete()
+        _drop_proxies(img.get_id())
+    return {'layer_id': layer.get_id(), 'layer_name': layer.get_name(), 'op': opts['op'],
+            'mode': opts['mode'], 'opacity': opts['opacity'], 'masked': mask_channel is not None}
+
+
 def _gray_bytes_image(data, w, h):
     """A new GRAY image carrying `data` as its one layer's pixels. Caller deletes it. `tmp` is torn
     down on any failure after its own creation (layer build, insert, or buffer write) -- otherwise
@@ -4899,7 +5911,7 @@ OPS = {
     'select': op_select, 'modify_mask': op_modify_mask, 'layer_mask': op_layer_mask,
     'mask_preview': op_mask_preview, 'load_mask': op_load_mask, 'render_layer': op_render_layer,
     'transform_layer': op_transform_layer,
-    'match_layer': op_match_layer,
+    'match_layer': op_match_layer, 'retouch': op_retouch, 'fill': op_fill, 'render_region': op_render_region,
 }