editmamei 1.7.1 → 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()))
@@ -423,6 +429,16 @@ _TRANSFER_MODE_ENUM = {
     'highlights': Gimp.TransferMode.HIGHLIGHTS,
 }
 
+# gimp_transform_layer's `interpolation` choices, keyed the same way lib.TRANSFORM_LAYER_
+# INTERPOLATIONS validates them against.
+_INTERPOLATION_ENUM = {
+    'none': Gimp.InterpolationType.NONE,
+    'linear': Gimp.InterpolationType.LINEAR,
+    'cubic': Gimp.InterpolationType.CUBIC,
+    'nohalo': Gimp.InterpolationType.NOHALO,
+    'lohalo': Gimp.InterpolationType.LOHALO,
+}
+
 
 def _set_exposure(cfg, params):
     cfg.set_property('exposure', params['exposure'])
@@ -550,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 = {
@@ -576,16 +604,10 @@ SETTERS = {
     'gegl:focus-blur': _set_lens_blur,
     'gegl:noise-rgb': _set_add_noise,
     'gegl:dropshadow': _set_drop_shadow,
+    'gegl:bilateral-filter': _set_surface_blur,
 }
 
 
-def _channel_by_name(img, name):
-    for ch in img.get_channels():
-        if ch.get_name() == name:
-            return ch
-    raise ValueError('no mask channel named %r (create one with create_mask)' % name)
-
-
 def _append_masked(img, layer, f, mask):
     """Append f, confined to channel `mask` if given. A filter appended while a selection is
     active keeps that selection as its own mask, which persists after the selection is
@@ -610,7 +632,7 @@ def _append_masked(img, layer, f, mask):
     runs before raising either way, so a refused filter that never actually attached to anything
     doesn't linger as an orphaned DrawableFilter object."""
     if mask:
-        img.select_item(Gimp.ChannelOps.REPLACE, _channel_by_name(img, mask))
+        img.select_item(Gimp.ChannelOps.REPLACE, _require_channel(img, mask))
     else:
         Gimp.Selection.none(img)
     try:
@@ -635,12 +657,14 @@ def _append_masked(img, layer, f, mask):
             Gimp.Selection.none(img)
 
 
-def _apply_filter(img, args, operation, params, default_name, type_=None):
+def _apply_filter(img, args, operation, params, default_name, type_=None, tag=None):
     """Create (or, with filter_id, update in place) a filter and record it in the ledger.
     A new filter may be confined to a mask channel (`mask`); a re-edit keeps the mask the
     filter was created with. `type_` is the user-facing adjust `type` (e.g. "shadows_highlights")
     recorded alongside `operation` (the GEGL op name) so a filter listing can report what the
-    model asked for, not just the GEGL internals."""
+    model asked for, not just the GEGL internals. `tag`, when given, marks the record as made by
+    another op (`lib.MATCH_TAG`) so that op can find its own filters later; a re-edit keeps the
+    tag the record already had."""
     filters, unknown = _ledger_get(img)
     if args.get('filter_id') is not None:
         f = _existing_filter(img, args, operation)
@@ -655,17 +679,28 @@ def _apply_filter(img, args, operation, params, default_name, type_=None):
         SETTERS[operation](f.get_config(), params)
         params['mask'] = args.get('mask')
         _append_masked(img, layer, f, params['mask'])
-    filters[f.get_name()] = {'operation': operation, 'type': type_, 'params': params}
+    record = {'operation': operation, 'type': type_, 'params': params}
+    tag = tag or filters.get(f.get_name(), {}).get('tag')
+    if tag:
+        record['tag'] = tag
+    filters[f.get_name()] = record
     _ledger_put(img, filters, unknown)
     return {'filter_id': f.get_id(), 'name': f.get_name(), 'type': type_, 'mask': params['mask']}
 
 
 # ---- operations -------------------------------------------------------------------------
 
+def _document_ids():
+    """Ids of the open documents. The preview proxies in `PROXIES` are real GIMP images but belong
+    to the bridge, so they are never listed."""
+    hidden = [p.get_id() for p in PROXIES.values() if p.is_valid()]
+    return lib.visible_image_ids([i.get_id() for i in Gimp.get_images()], hidden)
+
+
 def op_ping(args):
     major, minor, micro = lib.parse_gimp_version(Gimp.version())
     return {'major': major, 'minor': minor, 'micro': micro,
-            'images': [i.get_id() for i in Gimp.get_images()]}
+            'images': _document_ids()}
 
 
 # `precision` open-time promotion, using the enum names GIMP 3 actually exposes (verified live).
@@ -678,6 +713,67 @@ _PRECISION_ENUM = {
 }
 
 
+# Rotation/flip steps (`lib.EXIF_ORIENTATION_STEPS`) as GIMP calls. The image variants act on a
+# whole image; the layer variants on one (possibly unattached) layer.
+_ORIENTATION_IMAGE_STEPS = {
+    'cw90': lambda img: img.rotate(Gimp.RotationType.DEGREES90),
+    'cw180': lambda img: img.rotate(Gimp.RotationType.DEGREES180),
+    'cw270': lambda img: img.rotate(Gimp.RotationType.DEGREES270),
+    'flip_h': lambda img: img.flip(Gimp.OrientationType.HORIZONTAL),
+    'flip_v': lambda img: img.flip(Gimp.OrientationType.VERTICAL),
+}
+_ORIENTATION_LAYER_STEPS = {
+    'cw90': lambda layer: layer.transform_rotate_simple(Gimp.RotationType.DEGREES90, True, 0, 0),
+    'cw180': lambda layer: layer.transform_rotate_simple(Gimp.RotationType.DEGREES180, True, 0, 0),
+    'cw270': lambda layer: layer.transform_rotate_simple(Gimp.RotationType.DEGREES270, True, 0, 0),
+    'flip_h': lambda layer: layer.transform_flip_simple(Gimp.OrientationType.HORIZONTAL, True, 0),
+    'flip_v': lambda layer: layer.transform_flip_simple(Gimp.OrientationType.VERTICAL, True, 0),
+}
+
+# Formats whose loader leaves EXIF orientation unapplied in a non-interactive load. Only JPEG is
+# rotated here: other loaders apply their own orientation (HEIF's container rotation, TIFF's
+# orientation tag, raw-develop plug-ins), and `.xcf` stores upright pixels, so rotating them
+# again would turn them twice.
+_ORIENTATION_EXTENSIONS = {'.jpg', '.jpeg', '.jpe', '.jfif'}
+
+
+def _file_orientation(path, ext):
+    """(orientation, metadata) from the source file at `path`: the EXIF Orientation (2-8) and the
+    file's own metadata object, or (None, None) when the tag is missing, normal (1), unreadable,
+    or the format is not one this bridge orients. Read from the file itself: the metadata a load
+    attaches to the image is not a reliable source (it can carry another file's tags)."""
+    if ext not in _ORIENTATION_EXTENSIONS:
+        return None, None
+    try:
+        md = Gimp.Metadata.load_from_file(Gio.File.new_for_path(path))
+    except Exception:
+        return None, None
+    orientation = lib.read_exif_orientation(md)
+    if orientation is None or orientation == 1:
+        return None, None
+    return orientation, md
+
+
+def _upright_open_image(img, orientation, md):
+    """Turns a freshly loaded image upright for the EXIF `orientation` (2-8) and gives it the
+    source file's own metadata with the orientation tag dropped (absent means normal; a tag SET
+    to 1 does not reliably stick), so a viewer of a later copy cannot rotate it again."""
+    for step in lib.exif_orientation_steps(orientation):
+        _ORIENTATION_IMAGE_STEPS[step](img)
+    # The pixels are already upright; metadata is a courtesy to later copies and never fails an open.
+    try:
+        if lib.clear_exif_orientation(md):
+            img.set_metadata(md)
+    except Exception:
+        pass
+
+
+def _upright_placed_layer(layer, orientation):
+    """Turns a freshly loaded, unattached layer upright for the EXIF `orientation` (2-8)."""
+    for step in lib.exif_orientation_steps(orientation):
+        _ORIENTATION_LAYER_STEPS[step](layer)
+
+
 def op_open(args):
     path = lib.require(args, 'path')
     if not os.path.exists(path):
@@ -712,6 +808,9 @@ def op_open(args):
         # op here works on the whole canvas, and a transform with a selection active moves only
         # the selected pixels (leaving a floating selection), so it is cleared on the way in.
         Gimp.Selection.none(img)
+        orientation_applied, source_md = _file_orientation(path, ext)
+        if orientation_applied is not None:
+            _upright_open_image(img, orientation_applied, source_md)
         if precision != 'keep':
             # `convert_precision` does NOT raise on failure -- verified live that it returns
             # plain `False` (GIMP logs a "Calling error" to stderr, e.g. "must not be of type
@@ -735,7 +834,10 @@ def op_open(args):
     except Exception:
         img.delete()
         raise
-    return _describe(img)
+    result = _describe(img)
+    if orientation_applied is not None:
+        result['orientation_applied'] = orientation_applied
+    return result
 
 
 def _existing_ledger_params(img, args, operation):
@@ -851,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:
@@ -906,12 +1008,655 @@ 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)
 
 
+# ---- match_layer ------------------------------------------------------------------------
+
+def _match_hist(drawable, channel):
+    """(mean, std_dev, pixel count) of `channel` over `drawable` under the image's current
+    selection, in 0-255. A selection-aware read (verified live): with no selection it covers the
+    whole drawable, so callers refuse an EMPTY selection before asking. GIMP reports the mean and
+    spread in 0-255 for 8-bit images and in 0-1 for every higher precision (verified live)."""
+    ok, mean, std_dev, _median, _pixels, count, _pct = drawable.histogram(CHANNELS[channel], 0.0, 1.0)
+    if not ok:
+        raise lib.OpError('gimp_op_failed', 'GIMP could not read the %s histogram' % channel)
+    scale = lib.histogram_scale(drawable.get_image().get_precision().value_nick)
+    return mean * scale, std_dev * scale, int(round(count))
+
+
+def _match_select_visible(dup, target):
+    """Select what `target` shows: its alpha (hardened to 50%) intersected with its layer mask."""
+    dup.select_item(Gimp.ChannelOps.REPLACE, target)
+    mask = target.get_mask()
+    if mask is not None:
+        dup.select_item(Gimp.ChannelOps.INTERSECT, mask)
+    _harden_selection(dup)
+
+
+def _match_render(img, layer, roi, previous_filter_indexes, mode):
+    """A throwaway duplicate of `img`, cropped to `roi` (x, y, w, h), scaled down by
+    `lib.match_measure_scale`, with the layer's previous match filters removed. `mode` 'source'
+    keeps only the layer (and its groups) visible; 'below' hides it and everything above it.
+    Returns (dup, target, factor); the caller selects, flattens, and deletes `dup`."""
+    all_ids = [l.get_id() for l in _all_layers(img)]
+    dup = img.duplicate()
+    try:
+        dup_layers = _all_layers(dup)
+        if len(dup_layers) != len(all_ids):
+            raise lib.OpError('gimp_op_failed', 'could not duplicate the layer stack for measuring')
+        target = dup_layers[all_ids.index(layer.get_id())]
+        ancestors = {a.get_id() for a in _layer_ancestors(target)}
+        x, y, w, h = roi
+        if (w, h) != (img.get_width(), img.get_height()):
+            dup.crop(w, h, x, y)
+        factor = lib.match_measure_scale(w, h)
+        if factor < 1.0:
+            dup.scale(max(1, int(round(w * factor))), max(1, int(round(h * factor))))
+        target_filters = target.get_filters()
+        for i in previous_filter_indexes:
+            target_filters[i].delete()
+        if mode == 'source':
+            for l in dup_layers:
+                l.set_visible(l.get_id() == target.get_id() or l.get_id() in ancestors)
+            target.set_opacity(100.0)
+            target.set_mode(Gimp.LayerMode.NORMAL)
+        else:
+            index = dup_layers.index(target)
+            above_or_self = {l.get_id() for l in dup_layers[:index + 1]} - ancestors
+            for l in dup_layers:
+                if l.get_id() in above_or_self:
+                    l.set_visible(False)
+            if not any(l.get_visible() and not l.is_group() for l in dup_layers):
+                raise ValueError('there are no visible layers below this layer to match against')
+        return dup, target, factor
+    except Exception:
+        dup.delete()
+        raise
+
+
+def _match_stats(flat, channels, factor):
+    """Per-channel (mean, std_dev, full-resolution pixel count) on a measuring copy."""
+    out = {}
+    for c in channels:
+        mean, std, count = _match_hist(flat, c)
+        out[c] = (mean, std, lib.match_full_res_count(count, factor))
+    return out
+
+
+def _match_measure_source(img, layer, roi, previous_filter_indexes, channels):
+    dup, target, factor = _match_render(img, layer, roi, previous_filter_indexes, 'source')
+    try:
+        _match_select_visible(dup, target)
+        if Gimp.Selection.is_empty(dup):
+            raise ValueError('the layer has no visible pixels to measure')
+        flat = dup.flatten()
+        return _match_stats(flat, channels, factor)
+    finally:
+        dup.delete()
+
+
+def _match_measure_reference(img, layer, roi, previous_filter_indexes, channels, opts):
+    dup, target, factor = _match_render(img, layer, roi, previous_filter_indexes, 'below')
+    try:
+        if opts['reference'] == 'surround':
+            _match_select_visible(dup, target)
+            if Gimp.Selection.is_empty(dup):
+                raise ValueError('the layer has no visible pixels to measure')
+            visible = Gimp.Selection.save(dup)
+            Gimp.Selection.grow(dup, lib.match_scaled_px(opts['surround_px'], factor))
+            dup.select_item(Gimp.ChannelOps.SUBTRACT, visible)
+            _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 '
+                    "reference 'below'"
+                )
+        else:
+            _ok, ox, oy = target.get_offsets()
+            dup.select_rectangle(Gimp.ChannelOps.REPLACE, ox, oy, target.get_width(), target.get_height())
+            if Gimp.Selection.is_empty(dup):
+                raise ValueError('the layer has no visible pixels to measure')
+        flat = dup.flatten()
+        return _match_stats(flat, channels, factor)
+    finally:
+        dup.delete()
+
+
+def _delete_filters(img, created):
+    """Remove filters this call just made (by id) and their ledger records; never raises."""
+    names = set()
+    for c in created:
+        try:
+            _layer, f = _find_filter(img, c['filter_id'])
+            names.add(f.get_name())
+            f.delete()
+        except Exception:
+            pass
+    if names:
+        try:
+            filters, unknown = _ledger_get(img)
+            for name in names:
+                filters.pop(name, None)
+            _ledger_put(img, filters, unknown, removed=names)
+        except Exception:
+            pass
+
+
+class _PreservedSelection(object):
+    """Keeps the user's selection across ops that clear or replace it: the selection is saved to
+    a temporary channel on entry and restored (or cleared, if there was none) on exit, whichever
+    way the body ends."""
+
+    def __init__(self, img):
+        self.img = img
+        self.saved = None
+
+    def __enter__(self):
+        if not Gimp.Selection.is_empty(self.img):
+            self.saved = Gimp.Selection.save(self.img)
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        try:
+            if self.saved is not None:
+                self.img.select_item(Gimp.ChannelOps.REPLACE, self.saved)
+            else:
+                Gimp.Selection.none(self.img)
+        finally:
+            if self.saved is not None:
+                self.img.remove_channel(self.saved)
+        return False
+
+
+def _match_refine_edges(img, layer, contract_px, feather_px):
+    """Contract then feather the layer's mask (one made from its alpha when it has none). Only
+    the part of the mask on the canvas is rewritten; alpha is never touched. The caller holds the
+    selection (`_PreservedSelection`). Returns whether a mask was created."""
+    created = False
+    mask = layer.get_mask()
+    if mask is None:
+        mask = layer.create_mask(Gimp.AddMaskType.ALPHA)
+        layer.add_mask(mask)
+        created = True
+    try:
+        img.select_item(Gimp.ChannelOps.REPLACE, mask)
+        if contract_px:
+            _shrink_edge_locked(img, contract_px)
+        if feather_px:
+            Gimp.Selection.feather(img, feather_px)
+        _ok, ox, oy = layer.get_offsets()
+        cw, ch = img.get_width(), img.get_height()
+        x0, y0 = max(0, ox), max(0, oy)
+        x1, y1 = min(cw, ox + layer.get_width()), min(ch, oy + layer.get_height())
+        if x1 > x0 and y1 > y0:
+            data = img.get_selection().get_buffer().get(
+                Gegl.Rectangle.new(x0, y0, x1 - x0, y1 - y0), 1.0, "Y' u8", Gegl.AbyssPolicy.NONE
+            )
+            buf = mask.get_buffer()
+            buf.set(Gegl.Rectangle.new(x0 - ox, y0 - oy, x1 - x0, y1 - y0), "Y' u8", data)
+            buf.flush()
+            mask.update(x0 - ox, y0 - oy, x1 - x0, y1 - y0)
+    except Exception:
+        if created:
+            try:
+                layer.remove_mask(Gimp.MaskApplyMode.DISCARD)
+            except Exception:
+                pass
+        raise
+    return created
+
+
+def op_match_layer(args):
+    """Pull a pasted layer's colour and tone toward what surrounds it, as live curves filters.
+
+    Measure (on throwaway duplicates cropped to the layer's box grown by the surround, deleted on
+    every path -- the document, its selection and its visibility are not touched while
+    measuring): the layer's visible pixels (alpha AND layer mask, its own non-match filters
+    rendered) against the reference -- a ring of canvas around the visible area ('surround'), or
+    the whole composite of everything below under the layer's box ('below'). Per channel,
+    `lib.match_transfer` gives the linear map and `lib.match_curve_points` its curve.
+
+    'both' and 'color' write red/green/blue curves (matching each channel's mean and spread
+    already matches tone, so 'both' adds no value curve on top); 'tone' writes one value curve
+    from the VALUE (max of R,G,B) statistics. Each curve is a `gimp:curves` filter named 'Match
+    <channel>', ledgered with `lib.MATCH_TAG`; a repeat call deletes the layer's previous tagged
+    filters and writes fresh ones. The edge options then refine the layer mask."""
+    img = _image(args)
+    layer = _layer(img, args)
+    if layer.is_group():
+        raise ValueError(
+            'cannot match a layer group: it has no pixels of its own; match a layer inside it'
+        )
+    if layer.is_text_layer():
+        raise ValueError('cannot match a text layer: bake it to pixels first (gimp_bake)')
+    if layer.get_lock_content():
+        raise ValueError('layer %r is locked; unlock it first' % layer.get_name())
+    if lib.is_linear_precision(img.get_precision().value_nick):
+        raise ValueError(
+            'this image stores linear light (%s); convert it to a non-linear precision first'
+            % img.get_precision().value_nick
+        )
+    lw, lh = layer.get_width(), layer.get_height()
+    opts = lib.validate_match_args(args, lw, lh)
+    if opts['match'] != 'tone' and img.get_base_type() != Gimp.ImageBaseType.RGB:
+        raise ValueError("this image is not RGB; use match 'tone' (or convert it to RGB first)")
+    _ok, ox, oy = layer.get_offsets()
+    pad = opts['surround_px'] if opts['reference'] == 'surround' else 0
+    roi = lib.match_roi(ox, oy, lw, lh, img.get_width(), img.get_height(), pad)
+    if roi is None:
+        raise ValueError('the layer is entirely outside the canvas')
+
+    ledger, _unknown = _ledger_get(img)
+    previous = [
+        (i, f) for i, f in enumerate(layer.get_filters())
+        if ledger.get(f.get_name(), {}).get('tag') == lib.MATCH_TAG
+        and ledger[f.get_name()].get('operation') == f.get_operation_name()
+    ]
+    previous_indexes = [i for i, _f in previous]
+    channels = ['value'] if opts['match'] == 'tone' else ['red', 'green', 'blue']
+
+    source = _match_measure_source(img, layer, roi, previous_indexes, channels)
+    reference = _match_measure_reference(img, layer, roi, previous_indexes, channels, opts)
+    source_pixels = min(count for _m, _s, count in source.values())
+    reference_pixels = min(count for _m, _s, count in reference.values())
+    if source_pixels < lib.MATCH_MIN_PIXELS:
+        raise ValueError(
+            'the layer has only %d visible pixels to measure (need at least %d)'
+            % (source_pixels, lib.MATCH_MIN_PIXELS)
+        )
+    if reference_pixels < lib.MATCH_MIN_PIXELS:
+        raise ValueError(
+            'only %d reference pixels were found around the layer (need at least %d); raise '
+            "surround_px or use reference 'below'" % (reference_pixels, lib.MATCH_MIN_PIXELS)
+        )
+
+    plans = []
+    for channel in channels:
+        mu_s, sd_s, _n = source[channel]
+        mu_r, sd_r, _n = reference[channel]
+        t = lib.match_transfer(mu_s, sd_s, mu_r, sd_r, opts['s'])
+        points = lib.match_curve_points(mu_s, t['gain'], t['shift'])
+        plans.append((channel, mu_s, sd_s, mu_r, sd_r, t, points))
+
+    created, replaced, edge = [], [], None
+    try:
+        with _PreservedSelection(img):
+            # Replace, don't stack: this layer's previous match filters go first.
+            if previous:
+                names = set()
+                for _i, f in previous:
+                    names.add(f.get_name())
+                    replaced.append(f.get_id())
+                    f.delete()
+                filters, unknown = _ledger_get(img)
+                for name in names:
+                    filters.pop(name, None)
+                _ledger_put(img, filters, unknown, removed=names)
+            # All or nothing: a partial set would leave a colour cast.
+            try:
+                for channel, _ms, _ss, _mr, _sr, _t, points in plans:
+                    created.append(_apply_filter(
+                        img, {'layer_id': layer.get_id(), 'name': 'Match %s' % channel},
+                        'gimp:curves', {'channel': channel, 'points': points}, 'Match %s' % channel,
+                        type_='curves', tag=lib.MATCH_TAG,
+                    ))
+            except Exception:
+                _delete_filters(img, created)
+                raise
+            if opts['edge_contract_px'] or opts['edge_feather_px']:
+                mask_created = _match_refine_edges(
+                    img, layer, opts['edge_contract_px'], opts['edge_feather_px']
+                )
+                edge = {
+                    'contract_px': opts['edge_contract_px'],
+                    'feather_px': opts['edge_feather_px'],
+                    'mask_created': mask_created,
+                }
+    finally:
+        _drop_proxies(img.get_id())
+
+    def stat(mean, std):
+        return {'mean': round(mean, 2), 'std': round(std, 2)}
+
+    return {
+        'layer': layer.get_name(),
+        'layer_id': layer.get_id(),
+        'match': opts['match'],
+        'reference': opts['reference'],
+        'strength': opts['strength'],
+        'surround_px': opts['surround_px'] if opts['reference'] == 'surround' else None,
+        'filters': [
+            {'filter_id': c['filter_id'], 'name': c['name'], 'channel': p[0]}
+            for c, p in zip(created, plans)
+        ],
+        'replaced_filter_ids': replaced,
+        'measured': {'layer_pixels': source_pixels, 'reference_pixels': reference_pixels},
+        'channels': {
+            channel: {
+                'before': stat(mu_s, sd_s),
+                'after': stat(t['mean_after'], t['std_after']),
+                'reference': stat(mu_r, sd_r),
+                'gain': round(t['gain'], 3),
+            }
+            for channel, mu_s, sd_s, mu_r, sd_r, t, _pts in plans
+        },
+        'edge': edge,
+    }
+
+
+# ---- 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
@@ -969,7 +1714,7 @@ def _layer_node_shallow(layer):
     `get_children()`, but is still checked rather than trusted blindly -- offsets fall back to
     null rather than reporting a wrong position."""
     ok, off_x, off_y = layer.get_offsets()
-    return {
+    node = {
         'layer_id': layer.get_id(),
         'name': layer.get_name(),
         'opacity': layer.get_opacity(),
@@ -981,6 +1726,14 @@ def _layer_node_shallow(layer):
         'is_text_layer': layer.is_text_layer(),
         'children': [],
     }
+    if node['is_text_layer']:
+        # A text layer this engine can't read (an odd unit, a missing font) still describes as
+        # a text layer; it never fails the whole document.
+        try:
+            node.update(_text_fields(layer))
+        except Exception:
+            pass
+    return node
 
 
 def _build_layer_tree(top_layers, max_nodes=MAX_DESCRIBE_LAYER_NODES):
@@ -1222,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
@@ -1229,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(
@@ -1240,7 +2004,7 @@ def _refuse_if_non_right_angle_with_tracked_effects(img, degrees, op_name):
         )
 
 
-def _snapshot_effect_transform(img, op_name, transform_fn):
+def _snapshot_effect_transform(img, op_name, transform_fn, layers=None):
     """Precompute every ledgered effect filter's new params from a SNAPSHOT of the current
     ledger, validate each against this bridge's own field ranges, and raise -- refusing `op_name`
     outright -- if anything would land out of range, ALL BEFORE anything is mutated. Working from
@@ -1255,22 +2019,30 @@ def _snapshot_effect_transform(img, op_name, transform_fn):
     actually changed -- callers apply these with `_apply_planned_effect_transform` AFTER the
     geometry mutation itself. A filter transform_fn has nothing to change for (black_white,
     add_noise, and every gimp_add_adjustment type -- out of scope for this table, see lib.py's own
-    comment) comes back with the SAME values (by `==`) and is simply absent from the result."""
+    comment) comes back with the SAME values (by `==`) and is simply absent from the result.
+
+    `layers`, when given, scopes the walk to exactly those layers instead of the whole image --
+    `gimp_transform_layer`'s own use, scoped to the target's subtree (`_layer_subtree`), since
+    that op only ever transforms one layer (or, for a group, its own descendants), never every
+    layer in the image the way the whole-canvas geometry ops below do."""
     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 _all_layers(img):
+    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
 
@@ -1543,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):
@@ -1561,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())
@@ -1585,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
@@ -1649,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]
@@ -1679,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}
@@ -1731,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:
@@ -1771,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)
@@ -1785,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):
@@ -1805,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:
@@ -1814,14 +2771,99 @@ def op_export(args):
     return {'path': path, 'bytes': os.path.getsize(path)}
 
 
-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."""
-    for existing in img.get_channels():
-        if existing.get_name() == name:
-            img.remove_channel(existing)
-    ch = Gimp.Channel.new(img, name, w, h, 50.0, Gegl.Color.new('black'))
+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
+    selected layers afterward: `insert_channel` changes them as a side effect (verified live, the
+    same class of surprise `op_place_image`'s own comment documents for `insert_layer`), which
+    would otherwise silently retarget a later layer-defaulting call (e.g. `gimp_add_adjustment`
+    with no `layer`) at whatever layer a channel happened to insert next to."""
+    original_selection = img.get_selected_layers()
+    for existing in img.get_channels():
+        if existing.get_name() == name:
+            img.remove_channel(existing)
+    ch = Gimp.Channel.new(img, name, w, h, 50.0, Gegl.Color.new('black'))
     img.insert_channel(ch, None, 0)
+    img.set_selected_layers(original_selection)
     return ch
 
 
@@ -1856,6 +2898,31 @@ def _mask_name_in_use(img, name):
     return any(rec.get('params', {}).get('mask') == name for rec in filters.values())
 
 
+def _refuse_mask_in_use(img, name):
+    if _mask_name_in_use(img, name):
+        raise ValueError(
+            'mask %r is already used by an existing filter; delete that filter or use a '
+            'different name' % name
+        )
+
+
+def _find_channel(img, name):
+    for ch in img.get_channels():
+        if ch.get_name() == name:
+            return ch
+    return None
+
+
+def _require_channel(img, name):
+    """`_find_channel`, refusing a miss with the one neutral message every caller (the filter
+    mask lookup and every gimp_select-family channel reference) shares -- a channel can come from
+    gimp_select, gimp_layer_mask op=create, or load_mask, so no single tool name belongs here."""
+    ch = _find_channel(img, name)
+    if ch is None:
+        raise ValueError('no channel named %r' % name)
+    return ch
+
+
 def op_create_mask(args):
     """Geometric mask -> a named channel (replacing any same-named channel not already in use as
     a filter's mask -- see `_mask_name_in_use`), leaving the selection cleared afterward.
@@ -1873,15 +2940,14 @@ def op_create_mask(args):
     of how this function exits, rather than manually saving and restoring each property by hand.
     The gradient blend color space is explicitly set to RGB_PERCEPTUAL, but verified live that this
     has NO effect on a Channel fill's actual output either way: forcing RGB_PERCEPTUAL, forcing
-    RGB_LINEAR, and leaving the context at whatever it already was all produced byte-identical
-    output (an exact linear ramp -- x=128 reads 128) once read back correctly. What DOES control
-    the crossing point is the buffer format every reader of this channel (`_channel_coverage`,
-    and the selection copy above) uses -- `"Y' u8"` (perceptual/gamma-encoded, matching the
-    channel's own storage), not `'Y u8'` (linear light, which compresses the readback toward black,
-    e.g. the geometric midpoint reading ~55 instead of ~128; this is what an earlier, incorrect
-    version of this comment blamed on the blend color space instead). RGB_PERCEPTUAL is kept set
-    here anyway as the explicit, correct-if-it-ever-starts-mattering choice for a caller who thinks
-    in 0-255 terms, not because it changes anything measured today.
+    RGB_LINEAR, and leaving the context at whatever it already was all produce the same
+    byte-identical ramp (an exact linear ramp -- x=128 reads 128) when read back with `"Y' u8"`.
+    What DOES control the crossing point is the buffer format every reader of this channel
+    (`_channel_coverage`, and the selection copy above) uses -- `"Y' u8"` (perceptual/gamma-encoded,
+    matching the channel's own storage), not `'Y u8'` (linear light, which compresses the readback
+    toward black, e.g. the geometric midpoint reading ~55 instead of ~128). RGB_PERCEPTUAL is kept
+    set here anyway as the explicit, correct-if-it-ever-starts-mattering choice for a caller who
+    thinks in 0-255 terms, not because it changes anything measured today.
 
     `feather_px` has no effect here (a gradient is already a continuous ramp, nothing to feather);
     `invert` swaps which end is black vs white."""
@@ -1890,74 +2956,98 @@ def op_create_mask(args):
     if type_ not in lib.MASK_TYPES:
         raise ValueError('type must be one of %s' % sorted(lib.MASK_TYPES))
     name = args.get('name', 'Mask')
-    if _mask_name_in_use(img, name):
-        raise ValueError(
-            'mask %r is already used by an existing filter; delete that filter or use a '
-            'different name' % name
-        )
+    _refuse_mask_in_use(img, name)
     invert = bool(args.get('invert', False))
     feather_px = lib.validate_feather_px(args.get('feather_px', 0))
     w, h = img.get_width(), img.get_height()
 
-    if type_ in ('rectangle', 'ellipse'):
-        x, y = float(lib.require(args, 'x')), float(lib.require(args, 'y'))
-        width, height = float(lib.require(args, 'width')), float(lib.require(args, 'height'))
-        if type_ == 'rectangle':
-            img.select_rectangle(Gimp.ChannelOps.REPLACE, x, y, width, height)
-        else:
-            img.select_ellipse(Gimp.ChannelOps.REPLACE, x, y, width, height)
-        if invert:
-            Gimp.Selection.invert(img)
-        if feather_px > 0:
-            Gimp.Selection.feather(img, feather_px)
-        ch = _replace_named_channel(img, name, w, h)
-        # "Y' u8" (perceptual), not "Y u8" (linear) -- see `_channel_coverage`'s comment. A hard
-        # selection is 0/255 either way, but a FEATHERED one has a real falloff whose shape this
-        # format choice controls.
-        sel_data = img.get_selection().get_buffer().get(
-            Gegl.Rectangle.new(0, 0, w, h), 1.0, "Y' u8", Gegl.AbyssPolicy.NONE
-        )
-        ch_buf = ch.get_buffer()
-        ch_buf.set(Gegl.Rectangle.new(0, 0, w, h), "Y' u8", sel_data)
-        ch_buf.flush()
-        ch.update(0, 0, w, h)
-    else:
-        ch = _replace_named_channel(img, name, w, h)
-        black, white = ('white', 'black') if invert else ('black', 'white')
-        # A gradient fill paints `start_color` at (x1,y1) and `end_color` at (x2,y2). For
-        # gradient_linear those points are the caller's own start/end -- black-at-x1 ramps
-        # toward white-at-x2 exactly as given (verified live). For gradient_radial (x1,y1) is
-        # always the CENTER and (x2,y2) the radius edge, and the intuitive reading of a radial
-        # mask is a spotlight -- full effect (white) at the center, fading to none (black) at
-        # the edge -- so the two colors are swapped relative to the linear case.
-        if type_ == 'gradient_linear':
-            start_color, end_color = black, white
-            x1, y1 = float(args.get('x1', 0)), float(args.get('y1', 0))
-            x2, y2 = float(args.get('x2', w)), float(args.get('y2', 0))
-            gtype = Gimp.GradientType.LINEAR
+    try:
+        if type_ in ('rectangle', 'ellipse'):
+            x, y = float(lib.require(args, 'x')), float(lib.require(args, 'y'))
+            width, height = float(lib.require(args, 'width')), float(lib.require(args, 'height'))
+            if type_ == 'rectangle':
+                img.select_rectangle(Gimp.ChannelOps.REPLACE, x, y, width, height)
+            else:
+                img.select_ellipse(Gimp.ChannelOps.REPLACE, x, y, width, height)
+            if invert:
+                Gimp.Selection.invert(img)
+            if feather_px > 0:
+                Gimp.Selection.feather(img, feather_px)
+            ch = _replace_named_channel(img, name, w, h)
+            # "Y' u8" (perceptual), not "Y u8" (linear) -- see `_channel_coverage`'s comment. A
+            # hard selection is 0/255 either way, but a FEATHERED one has a real falloff whose
+            # shape this format choice controls.
+            sel_data = img.get_selection().get_buffer().get(
+                Gegl.Rectangle.new(0, 0, w, h), 1.0, "Y' u8", Gegl.AbyssPolicy.NONE
+            )
+            ch_buf = ch.get_buffer()
+            ch_buf.set(Gegl.Rectangle.new(0, 0, w, h), "Y' u8", sel_data)
+            ch_buf.flush()
+            ch.update(0, 0, w, h)
         else:
-            start_color, end_color = white, black
-            cx, cy = float(args.get('cx', w / 2.0)), float(args.get('cy', h / 2.0))
-            radius = float(args.get('radius', min(w, h) / 2.0))
-            x1, y1, x2, y2 = cx, cy, cx + radius, cy
-            gtype = Gimp.GradientType.RADIAL
-        Gimp.context_push()
-        try:
-            Gimp.context_set_foreground(Gegl.Color.new(start_color))
-            Gimp.context_set_background(Gegl.Color.new(end_color))
-            Gimp.context_set_gradient_fg_bg_rgb()
-            Gimp.context_set_gradient_blend_color_space(Gimp.GradientBlendColorSpace.RGB_PERCEPTUAL)
-            ch.edit_gradient_fill(gtype, 0.0, False, 1, 0, False, x1, y1, x2, y2)
-        finally:
-            Gimp.context_pop()
-    Gimp.Selection.none(img)  # a mask is referenced by NAME at filter-creation time, not by
-    # staying the active selection -- leaving it selected let the NEXT unmasked filter silently
-    # inherit it (`_append_masked` also clears defensively, but the fix belongs here too).
+            ch = _replace_named_channel(img, name, w, h)
+            _paint_gradient_mask(ch, type_, invert, args, w, h)
+    finally:
+        Gimp.Selection.none(img)  # a mask is referenced by NAME at filter-creation time, not by
+        # staying the active selection -- leaving it selected let the NEXT unmasked filter
+        # silently inherit it (`_append_masked` also clears defensively, but the fix belongs
+        # here too).
     _drop_proxies(img.get_id())
     selected, fraction = _channel_coverage(ch, w, h)
     return {'channel': name, 'selected_pixels': selected, 'fraction': fraction}
 
 
+def _paint_gradient_mask(ch, type_, invert, args, w, h):
+    """Paint a `type_` ('gradient_linear' | 'gradient_radial') black-to-white ramp directly into
+    channel `ch`. `gegl:linear-gradient`/`gegl:radial-gradient` are NOT usable as drawable filters
+    (verified live: their pspecs return None, `DrawableFilter.new` fails) -- the working route is
+    `Drawable.edit_gradient_fill` (verified live). `Gimp.context_push`/`context_pop` bracket every
+    context change (foreground/background/gradient/blend space) so the session's ambient context
+    -- which the user's own GUI or a later call might depend on -- is restored exactly regardless
+    of how this function exits, rather than manually saving and restoring each property by hand.
+    The gradient blend color space is explicitly set to RGB_PERCEPTUAL, but verified live that this
+    has NO effect on a Channel fill's actual output either way: forcing RGB_PERCEPTUAL, forcing
+    RGB_LINEAR, and leaving the context at whatever it already was all produce the same
+    byte-identical ramp (an exact linear ramp -- x=128 reads 128) when read back with `"Y' u8"`.
+    What DOES control the crossing point is the buffer format every reader of this channel
+    (`_channel_coverage`) uses -- `"Y' u8"` (perceptual/gamma-encoded, matching the channel's own
+    storage), not `'Y u8'` (linear light, which compresses the readback toward black, e.g. the
+    geometric midpoint reading ~55 instead of ~128). RGB_PERCEPTUAL is kept set here anyway as the
+    explicit, correct-if-it-ever-starts-mattering choice for a caller who thinks in 0-255 terms, not
+    because it changes anything measured today.
+
+    No feather here (a gradient is already a continuous ramp, nothing to feather); `invert` swaps
+    which end is black vs white. Shared by `op_create_mask` and `op_select`'s own gradient_linear/
+    gradient_radial modes."""
+    black, white = ('white', 'black') if invert else ('black', 'white')
+    # A gradient fill paints `start_color` at (x1,y1) and `end_color` at (x2,y2). For
+    # gradient_linear those points are the caller's own start/end -- black-at-x1 ramps toward
+    # white-at-x2 exactly as given (verified live). For gradient_radial (x1,y1) is always the
+    # CENTER and (x2,y2) the radius edge, and the intuitive reading of a radial mask is a
+    # spotlight -- full effect (white) at the center, fading to none (black) at the edge -- so the
+    # two colors are swapped relative to the linear case.
+    if type_ == 'gradient_linear':
+        start_color, end_color = black, white
+        x1, y1 = float(args.get('x1', 0)), float(args.get('y1', 0))
+        x2, y2 = float(args.get('x2', w)), float(args.get('y2', 0))
+        gtype = Gimp.GradientType.LINEAR
+    else:
+        start_color, end_color = white, black
+        cx, cy = float(args.get('cx', w / 2.0)), float(args.get('cy', h / 2.0))
+        radius = float(args.get('radius', min(w, h) / 2.0))
+        x1, y1, x2, y2 = cx, cy, cx + radius, cy
+        gtype = Gimp.GradientType.RADIAL
+    Gimp.context_push()
+    try:
+        Gimp.context_set_foreground(Gegl.Color.new(start_color))
+        Gimp.context_set_background(Gegl.Color.new(end_color))
+        Gimp.context_set_gradient_fg_bg_rgb()
+        Gimp.context_set_gradient_blend_color_space(Gimp.GradientBlendColorSpace.RGB_PERCEPTUAL)
+        ch.edit_gradient_fill(gtype, 0.0, False, 1, 0, False, x1, y1, x2, y2)
+    finally:
+        Gimp.context_pop()
+
+
 def op_describe_operation(args):
     """Probe: `list_properties()` (name, type, min, max, default) for a named GEGL/GIMP
     operation, via a transient `DrawableFilter` on a throwaway 1x1 image that is never applied
@@ -2119,9 +3209,9 @@ def _layer_ancestors(layer):
 
 def _refuse_if_masked_filters_on(img, op_name, layer):
     """The same refuse-rather-than-corrupt check as `_refuse_if_masked_filters`, scoped to `layer`
-    itself, its own subtree (`_layer_subtree` -- moving a group takes its children with it), and
-    its containing groups (`_layer_ancestors`) -- moving `layer` cannot misalign a masked filter
-    that lives on some OTHER, unrelated part of the image.
+    itself, its own subtree (`_layer_subtree` -- transforming a group takes its children with
+    it), and its containing groups (`_layer_ancestors`) -- transforming `layer` cannot misalign a
+    masked filter that lives on some OTHER, unrelated part of the image.
 
     Duplicate-name classification runs over the WHOLE image's live filters, not just this scope: a
     name is ambiguous the moment it appears on more than one live filter ANYWHERE in the image,
@@ -2129,7 +3219,7 @@ def _refuse_if_masked_filters_on(img, op_name, layer):
     elsewhere hiding behind an unmasked one's ledger record in this scope (or the reverse) would
     otherwise slip through unnoticed. The refusal itself still only fires for a name that actually
     appears in `layer`'s own scope, so a masked filter on a completely unrelated layer never blocks
-    this move."""
+    this transform."""
     scope = set(_layer_subtree(layer)) | set(_layer_ancestors(layer))
     scoped_names = {f.get_name() for l in scope for f in l.get_filters()}
     filters = _prune_stale_ledger_records(img)
@@ -2157,8 +3247,8 @@ def _refuse_if_masked_filters_on(img, op_name, layer):
             reasons.append(
                 'filter(s) %s on this layer, or a group containing it, were not created by '
                 'Editmamei (no matching ledger record for their name and operation), so whether '
-                'they are masked cannot be checked -- delete them first, or move the layer before '
-                'adding them'
+                'they are masked cannot be checked -- delete them first, or transform the layer '
+                'before adding them'
                 % ', '.join(repr(n) for n in unrecognized)
             )
         if duplicated:
@@ -2182,8 +3272,8 @@ def _refuse_if_masked_filters_on(img, op_name, layer):
         raise ValueError(
             '%s would misalign the masked adjustment(s) %s: a filter\'s mask does not travel with '
             'content that moves beneath it, whether the filter is on this layer or a group that '
-            'contains it. Move the layer before adding masked adjustments, or delete those filters '
-            'first and re-create them afterwards.'
+            'contains it. Transform the layer before adding masked adjustments, or delete those '
+            'filters first and re-create them afterwards.'
             % (op_name, ', '.join(repr(n) for n in masked))
         )
 
@@ -2196,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()))
@@ -2301,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
@@ -2310,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
 
@@ -2479,19 +3570,6 @@ def _op_layer_set(img, args):
     return {'layer_id': layer.get_id(), 'name': layer.get_name(), **changed}
 
 
-def _op_layer_move(img, args):
-    layer = _layer(img, args)
-    _refuse_if_masked_filters_on(img, 'move', layer)
-    x, y = int(lib.require(args, 'x')), int(lib.require(args, 'y'))
-    _validated_move_offset(img, x, y)
-    try:
-        layer.set_offsets(x, y)
-    finally:
-        _drop_proxies(img.get_id())
-    ok, off_x, off_y = layer.get_offsets()
-    return {'layer_id': layer.get_id(), 'x': off_x if ok else None, 'y': off_y if ok else None}
-
-
 def _op_layer_reorder(img, args):
     layer = _layer(img, args)
     parent = _resolve_parent_group(img, args) if 'parent_group' in args else layer.get_parent()
@@ -2604,7 +3682,6 @@ LAYER_OPS = {
     'duplicate': _op_layer_duplicate,
     'select': _op_layer_select,
     'set': _op_layer_set,
-    'move': _op_layer_move,
     'reorder': _op_layer_reorder,
     'merge_down': _op_layer_merge_down,
     'flatten': _op_layer_flatten,
@@ -2620,6 +3697,594 @@ def op_layer(args):
     return fn(img, args)
 
 
+# ---- gimp_text / gimp_inspect what=fonts ------------------------------------------------------
+#
+# A text layer stays a live Gimp.TextLayer: text, font, size, colour and justification are
+# properties of the layer, re-rendered by GIMP on every change. Sizes are exchanged in points and
+# stored in pixels (pt * the image's vertical resolution / 72). A rendered layer past the engine's
+# size cap is refused: a new layer is discarded, an edit is rolled back to the previous values.
+
+_JUSTIFICATIONS = {
+    'left': Gimp.TextJustification.LEFT,
+    'right': Gimp.TextJustification.RIGHT,
+    'center': Gimp.TextJustification.CENTER,
+    'fill': Gimp.TextJustification.FILL,
+}
+
+
+def _font_list():
+    """Every installed font as `{name: Gimp.Font}`. A freshly started GIMP can report an empty
+    list while its font cache is still loading, so an empty result is retried briefly."""
+    for _ in range(20):
+        fonts = Gimp.fonts_get_list('')
+        if fonts:
+            return {f.get_name(): f for f in fonts}
+        time.sleep(0.25)
+    raise lib.OpError('gimp_op_failed', 'GIMP reports no installed fonts (the font list is empty)')
+
+
+def op_fonts(args):
+    """`gimp_inspect what=fonts`: installed font names, sorted, optionally narrowed by a
+    case-insensitive substring `filter`, capped (`total` counts every match)."""
+    flt = args.get('filter')
+    if flt is not None and not isinstance(flt, str):
+        raise ValueError('filter must be a string')
+    installed = list(_font_list())
+    names, total = lib.list_fonts(installed, flt)
+    return {'fonts': names, 'total': total, 'returned': len(names), 'truncated': len(names) < total,
+            'default': lib.pick_default_font(installed)}
+
+
+def _image_ppi(img):
+    ok, _xres, yres = img.get_resolution()
+    return yres if ok else None
+
+
+def _text_font_size_pt(layer):
+    size, unit = layer.get_font_size()
+    return lib.unit_size_to_pt(
+        size, unit.get_id() == Gimp.Unit.pixel().get_id(), unit.get_factor(),
+        _image_ppi(layer.get_image()),
+    )
+
+
+def _text_color_rgb(layer):
+    r, g, b, _a = layer.get_color().get_rgba()
+    return {'red': lib.linear_to_srgb_u8(r), 'green': lib.linear_to_srgb_u8(g),
+            'blue': lib.linear_to_srgb_u8(b)}
+
+
+def _has_markup(layer):
+    """Whether the layer's text is stored as markup (per-character styling from the GUI), in
+    which case it has no plain text."""
+    return bool(layer.get_markup())
+
+
+def _text_fields(layer):
+    """A text layer's own state, in gimp_text's units (points, 0-255 colour, ps_text-style
+    alignment names). Shared by `describe`'s layer nodes and gimp_text's results. The text is
+    capped for reporting (`text_length` is the full length); a markup layer reports '' with
+    `has_markup`."""
+    font = layer.get_font()
+    has_markup = _has_markup(layer)
+    text, length, truncated = lib.text_for_report('' if has_markup else layer.get_text())
+    return {
+        'text': text,
+        'text_length': length,
+        'text_truncated': truncated,
+        'has_markup': has_markup,
+        'font': font.get_name() if font is not None else None,
+        'font_size': _text_font_size_pt(layer),
+        'color': _text_color_rgb(layer),
+        'alignment': lib.alignment_name(layer.get_justification().value_nick),
+    }
+
+
+def _text_record(layer):
+    ok, off_x, off_y = layer.get_offsets()
+    record = {'layer_id': layer.get_id(), 'name': layer.get_name()}
+    record.update(_text_fields(layer))
+    ppi = _image_ppi(layer.get_image())
+    record['ppi'] = ppi
+    record['font_size_px'] = round(_text_size_px(layer), 1)
+    record['bounds'] = {
+        'x': off_x if ok else None, 'y': off_y if ok else None,
+        'width': layer.get_width(), 'height': layer.get_height(),
+    }
+    return record
+
+
+def _set_text_color(layer, rgb):
+    color = Gegl.Color.new('black')
+    color.set_rgba(lib.srgb_u8_to_linear(rgb[0]), lib.srgb_u8_to_linear(rgb[1]),
+                   lib.srgb_u8_to_linear(rgb[2]), 1.0)
+    layer.set_color(color)
+
+
+_TEXT_PROBE_PX = 8.0
+
+
+def _check_estimated_text_size(text, font, size_px, img, layer=None):
+    """Refuse text that would render past the size cap BEFORE rendering it at full size: lay it
+    out once on a throwaway layer at a tiny size and scale the measured extent up (with headroom,
+    plus `layer`'s own letter/line spacing and indent, which do not scale), so an absurd request
+    never makes GIMP allocate and draw an enormous layer just to be refused. Fails closed: when
+    no estimate can be made, the request is refused."""
+    if font is None:
+        font = _resolved_font(_font_list(), None)
+    probe = Gimp.TextLayer.new(img, text, font, _TEXT_PROBE_PX, Gimp.Unit.pixel())
+    if probe is None:
+        raise lib.OpError('gimp_op_failed', 'GIMP could not lay out the text to check its size')
+    try:
+        spacing = {}
+        if layer is not None:
+            spacing = {
+                'letter_spacing': layer.get_letter_spacing(),
+                'line_spacing': layer.get_line_spacing(),
+                'indent': layer.get_indent(),
+            }
+        width, height = lib.estimate_text_extent(
+            probe.get_width(), probe.get_height(), _TEXT_PROBE_PX, size_px,
+            chars=len(text), lines=text.count('\n') + 1, **spacing
+        )
+    finally:
+        probe.delete()
+    lib.check_estimated_text_size(width, height)
+
+
+def _text_size_px(layer):
+    """The layer's font size in pixels, whichever unit it is stored in."""
+    size, unit = layer.get_font_size()
+    if unit.get_id() == Gimp.Unit.pixel().get_id():
+        return size
+    return lib.pt_to_px(_text_font_size_pt(layer), _image_ppi(layer.get_image()))
+
+
+def _text_state(layer):
+    return {
+        'text': layer.get_text(), 'font': layer.get_font(), 'size': layer.get_font_size(),
+        'color': layer.get_color(), 'justification': layer.get_justification(),
+    }
+
+
+def _same_size(a, b):
+    return a[0] == b[0] and a[1].get_id() == b[1].get_id()
+
+
+def _text_restore(layer, state):
+    """Best-effort rollback to a `_text_state` snapshot, touching only what changed (each setter
+    re-renders the layer). When the size grew it is restored first, so the font and text go back
+    at the smaller size. Never raises (it runs while the original failure is propagating)."""
+    try:
+        current_font = layer.get_font()
+        size_changed = not _same_size(layer.get_font_size(), state['size'])
+        shrink_first = size_changed and _text_size_px(layer) > _size_px_of(layer, state['size'])
+        if shrink_first:
+            layer.set_font_size(state['size'][0], state['size'][1])
+        if state['font'] is not None and (
+            current_font is None or current_font.get_name() != state['font'].get_name()
+        ):
+            layer.set_font(state['font'])
+        if state['text'] is not None and layer.get_text() != state['text']:
+            layer.set_text(state['text'])
+        if size_changed and not shrink_first:
+            layer.set_font_size(state['size'][0], state['size'][1])
+        layer.set_color(state['color'])
+        if layer.get_justification() != state['justification']:
+            layer.set_justification(state['justification'])
+    except Exception:
+        pass
+
+
+def _size_px_of(layer, size):
+    """A stored (value, unit) font size in pixels."""
+    value, unit = size
+    if unit.get_id() == Gimp.Unit.pixel().get_id():
+        return value
+    pt = lib.unit_size_to_pt(value, False, unit.get_factor(), _image_ppi(layer.get_image()))
+    return lib.pt_to_px(pt, _image_ppi(layer.get_image()))
+
+
+def _resolved_font(fonts, font_name):
+    if font_name is None:
+        return fonts[lib.pick_default_font(list(fonts))]
+    name, _how = lib.resolve_font(font_name, list(fonts))
+    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))
+    x = int(args.get('x', 100))
+    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))
+    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:
+        img.insert_layer(layer, None, 0)
+        _assert_layer_attached(img, layer, 'the new text layer')
+        # Colour and justification only take effect once the layer is in the image.
+        if rgb is not None:
+            _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
+    finally:
+        _drop_proxies(img.get_id())
+    return record
+
+
+def _text_target(img, args):
+    layer = _layer(img, args)
+    if not layer.is_text_layer():
+        raise ValueError(
+            'layer %r is not a text layer; address a text layer by layer_id (gimp_inspect '
+            'what=layers flags them with is_text_layer)' % layer.get_name()
+        )
+    if _has_markup(layer):
+        raise ValueError(
+            'layer %r has per-character styling (markup), which gimp_text cannot edit without '
+            'losing it; create a new text layer instead' % layer.get_name()
+        )
+    return layer
+
+
+def _op_text_edit(img, args, apply_fn, precheck_fn=None):
+    """Run `apply_fn(layer)` on the targeted text layer. `precheck_fn(layer)` runs first, before
+    anything changes, so a refusal there costs no re-render. On any failure in `apply_fn`, or if
+    the re-rendered layer is past the size cap, restore the previous values and re-raise."""
+    layer = _text_target(img, args)
+    if precheck_fn is not None:
+        precheck_fn(layer)
+    state = _text_state(layer)
+    try:
+        apply_fn(layer)
+        lib.check_text_layer_size(layer.get_width(), layer.get_height())
+    except Exception:
+        _text_restore(layer, state)
+        raise
+    finally:
+        _drop_proxies(img.get_id())
+    return _text_record(layer)
+
+
+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: None if _text_enforce_box(layer) else _check_estimated_text_size(
+            text, layer.get_font(), _text_size_px(layer), img, layer),
+    )
+
+
+def _op_text_set_font(img, args):
+    font_name = lib.require(args, 'font_name')
+    size_pt = lib.validate_font_size_pt(args['font_size']) if args.get('font_size') is not None else None
+    font = _resolved_font(_font_list(), font_name)
+    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)
+
+    def apply_fn(layer):
+        # Shrinking: size first, so the new font never renders at the larger old size.
+        if new_size_px is not None and new_size_px < _text_size_px(layer):
+            layer.set_font_size(new_size_px, Gimp.Unit.pixel())
+            layer.set_font(font)
+        else:
+            layer.set_font(font)
+            if new_size_px is not None:
+                layer.set_font_size(new_size_px, Gimp.Unit.pixel())
+
+    return _op_text_edit(img, args, apply_fn, precheck_fn=precheck_fn)
+
+
+def _op_text_set_color(img, args):
+    rgb = lib.validate_text_rgb(args)
+    if rgb is None:
+        raise ValueError('red, green and blue are required')
+    return _op_text_edit(img, args, lambda layer: _set_text_color(layer, rgb))
+
+
+def _op_text_set_alignment(img, args):
+    justification = _JUSTIFICATIONS[lib.justification_nick(lib.require(args, 'alignment'))]
+    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,
+}
+
+
+def op_text(args):
+    img = _image(args)
+    top = args.get('op')
+    fn = TEXT_OPS.get(top)
+    if fn is None:
+        raise ValueError('op must be one of %s' % sorted(TEXT_OPS))
+    return fn(img, args)
+
+
 # ---- gimp_bake --------------------------------------------------------------------------------
 
 
@@ -2732,8 +4397,9 @@ def op_bake(args):
 #   - `Item.scale(width, height, local_origin)` resizes just that one layer; called here while its
 #     offset is still whatever `file_load_layer` gave it (verified: local_origin's own effect on
 #     the resulting offset only matters when the pre-scale offset is non-zero), and the caller's
-#     `x`/`y` are applied afterward via the same absolute `set_offsets` `gimp_layer op=move` uses --
-#     so the requested position is always exact regardless of local_origin's own math. Both
+#     `x`/`y` are applied afterward via the same absolute `set_offsets` call every layer-move op
+#     in this bridge uses -- so the requested position is always exact regardless of
+#     local_origin's own math. Both
 #     `Drawable.scale()` and `Drawable.fill()` report failure by returning `False` rather than
 #     raising (the same class `op_open`'s own `convert_precision` comment documents) -- checked
 #     everywhere this file calls either, including the pre-existing `_fill_new_layer` shared with
@@ -2846,8 +4512,13 @@ def op_place_image(args):
     original_selection = img.get_selected_layers()
     baked_filters = []
     try:
+        # The DoS floor applies to the SOURCE file's own size too; checked before any rotation
+        # (it is symmetric in width and height, so the upright size passes or fails alike).
+        lib.validate_resize_dims(loaded.get_width(), loaded.get_height())
+        orientation_applied, _md = _file_orientation(path, ext)
+        if orientation_applied is not None:
+            _upright_placed_layer(loaded, orientation_applied)
         w0, h0 = loaded.get_width(), loaded.get_height()
-        lib.validate_resize_dims(w0, h0)  # the DoS floor applies to the SOURCE file's own size too
 
         width, height = args.get('width'), args.get('height')
         if width is not None or height is not None:
@@ -2912,6 +4583,8 @@ def op_place_image(args):
     }
     if baked_filters:
         result['baked_filters'] = baked_filters
+    if orientation_applied is not None:
+        result['orientation_applied'] = orientation_applied
     return result
 
 
@@ -3045,11 +4718,1178 @@ def op_convert_image_mode(args):
     return {'mode': mode, 'converted': True}
 
 
+# ---- gimp_transform_layer ---------------------------------------------------------------------
+#
+# A per-LAYER affine transform (fit/scale/move/rotate/flip/skew/free) -- distinct from the
+# whole-CANVAS geometry ops above (crop/resize/rotate/flip), which move or resize every layer
+# together. Addressed the same way every other gimp_* layer op is (`_layer`): layer_id takes
+# priority over layer (name), neither given falls back to the selected layer, or the topmost one.
+#
+# Verified live (GIMP 3.2.6), the assumptions this section is built on:
+#   - `Item.transform_scale`/`transform_rotate`/`transform_flip_simple`/`transform_matrix` all
+#     carry the layer's own mask along automatically, repositioned and resized to match the
+#     layer's new bounds exactly -- no separate mask transform is needed.
+#   - Calling any of these on a GROUP layer transforms the whole group as a unit: every
+#     descendant's own offsets and size update too, in lockstep with the group's. No special-
+#     casing is needed for a group target beyond its own alpha (every non-group descendant gets
+#     one independently -- a group has no pixels of its own) and its predicted size caps: the
+#     group's own bounding box, each non-group descendant's own predicted size, and the SUM of
+#     those descendant sizes must all fit (GIMP allocates and transforms each descendant's own
+#     pixel buffer independently, so the group's bounding box fitting the cap guarantees
+#     neither a single descendant's buffer nor their combined memory does). A locked layer
+#     anywhere in the group's subtree refuses the whole transform up front.
+#   - `Context.transform_resize` set to ADJUST (rather than the default CLIP) is what makes
+#     `rotate`/`skew`/`free` grow the layer's own bounding box to its new, larger extent instead
+#     of clipping corners that rotate/shear outside the old one -- the same growth
+#     `gimp_transform_canvas`'s `expand` gives the whole canvas, but always-on here since a
+#     layer (unlike the canvas) has no reason to ever clip its own content.
+#   - `Context.interpolation` is read by the transform itself, not passed as an argument to any
+#     of the methods above -- set explicitly before every call (never left at whatever a PRIOR
+#     call happened to leave it at).
+#   - A layer with no alpha channel (e.g. a flattened base layer) would otherwise fill any area
+#     a transform exposes outside its old bounds with an opaque background color rather than
+#     transparency -- `add_alpha()` first avoids that, for every op, not only ones that grow the
+#     bounding box (harmless on one that doesn't need it).
+#   - `set_offsets`/every `transform_*` method reports a lock-position or lock-content layer it
+#     could not transform by returning a FALSY value (`False`/`None`) rather than raising --
+#     checked both proactively (`_refuse_if_layer_locked`, before alpha is ever added) and on the
+#     actual call's own return value (`_checked_transform`, defense in depth).
+#   - A text layer stays a text layer through every op here (verified live for scale, rotate,
+#     flip, skew and free; reported back as `text_layer`), never rasterized.
+#   - Refuses outright when the layer (or a containing group) carries a masked or unverifiable
+#     adjustment filter -- `_refuse_if_masked_filters_on` (the same scoped check the whole-image
+#     geometry ops' own `_refuse_if_masked_filters` is a sibling of). An UNMASKED adjustment
+#     filter, or an unmasked position/direction-dependent EFFECT filter (vignette, motion_blur,
+#     drop_shadow) under flip, an exact 90-degree-multiple rotate, or a uniform scale, is instead
+#     REMAPPED the same way the canvas geometry ops remap it (`_snapshot_effect_transform`,
+#     scoped to this layer's own subtree); an arbitrary-angle rotate, any skew or free transform,
+#     or a non-uniform scale is refused outright while such an effect is present, the same way
+#     the canvas ops refuse an arbitrary-angle rotate.
+
+
+def _transform_layer_center(layer):
+    ok, x, y = layer.get_offsets()
+    return (x if ok else 0) + layer.get_width() / 2.0, (y if ok else 0) + layer.get_height() / 2.0
+
+
+def _transform_layer_bounds(layer):
+    ok, x, y = layer.get_offsets()
+    return {
+        'x': x if ok else None, 'y': y if ok else None,
+        'width': layer.get_width(), 'height': layer.get_height(),
+    }
+
+
+def _set_transform_layer_interpolation(args):
+    choice = lib.validate_choice(
+        'interpolation', args.get('interpolation', 'cubic'), lib.TRANSFORM_LAYER_INTERPOLATIONS
+    )
+    Gimp.context_set_interpolation(_INTERPOLATION_ENUM[choice])
+    return choice
+
+
+def _snap_px(value):
+    """Round-half-up to the nearest whole pixel -- `floor(v + 0.5)`, not Python's own banker's
+    `round()` (which rounds a .5 to the nearest EVEN integer, silently snapping e.g. 2.5 down to
+    2). Every target rectangle `fit`/`scale` computes, and every `move` target, snaps to an
+    integer pixel this same, predictable way, so a layer already exactly sized/positioned for the
+    request is a true no-op -- never a half-pixel resample from float drift alone."""
+    return int(math.floor(value + 0.5))
+
+
+def _refuse_if_layer_locked(layer):
+    """Refuses outright, before anything else runs (including adding alpha), when `layer` -- or,
+    for a group, any layer in its subtree that the transform would move -- is lock-position or
+    lock-content. Verified live (GIMP 3.2.6): GIMP does not raise for either -- it silently
+    no-ops `set_offsets`/every `transform_*` method instead (`_checked_transform`'s own comment)
+    -- so this catches it earlier, naming the offending layer, rather than leave a group
+    half-transformed or fall through to that generic defense-in-depth check alone."""
+    for item in _layer_subtree(layer):
+        if item.get_lock_position():
+            raise ValueError(
+                'layer %r is lock-position and cannot be transformed; unlock it first'
+                % item.get_name()
+            )
+        if item.get_lock_content():
+            raise ValueError(
+                'layer %r is lock-content and cannot be transformed; unlock it first'
+                % item.get_name()
+            )
+
+
+def _checked_transform(layer, result):
+    """Verifies a `Item.transform_*`/`set_offsets` call's own return value actually did what it
+    claims. GIMP reports a layer it could not transform (lock-position, lock-content, or any
+    other reason `_refuse_if_layer_locked`'s own proactive check didn't already catch) by
+    returning a FALSY value instead of raising -- `False` for `set_offsets`, `None` for every
+    `transform_*` method (verified live, GIMP 3.2.6) -- so a caller that trusts the call
+    unconditionally would silently report success (and, worse, alpha_added: true) for a
+    transform that never actually happened. `result is True` (`set_offsets`' own success value)
+    is accepted without an id to compare; anything else truthy must be the SAME item this call
+    targeted, not some other one GIMP happened to return."""
+    if not result:
+        raise lib.OpError(
+            'gimp_op_failed',
+            'GIMP did not transform layer %r -- it may be lock-position or lock-content'
+            % layer.get_name()
+        )
+    if result is not True and result.get_id() != layer.get_id():
+        raise lib.OpError(
+            'gimp_op_failed', 'GIMP transformed a different item than layer %r' % layer.get_name()
+        )
+
+
+def _ensure_layer_alpha(layer):
+    """Adds an alpha channel to `layer` if it doesn't have one already. For a GROUP target, adds
+    one to every NON-GROUP descendant that lacks it instead (a group has no pixels of its own to
+    add a channel to, but transforming it cascades to every descendant, each of which can expose
+    a new area the same way a plain layer target can). Returns whether alpha was actually added
+    anywhere."""
+    if layer.is_group():
+        added = False
+        for descendant in _layer_subtree(layer):
+            if descendant.get_id() == layer.get_id() or descendant.is_group():
+                continue
+            if descendant.has_alpha():
+                continue
+            if not descendant.add_alpha():
+                raise lib.OpError(
+                    'gimp_op_failed',
+                    'GIMP could not add an alpha channel to layer %r' % descendant.get_name()
+                )
+            added = True
+        return added
+    if layer.has_alpha():
+        return False
+    if not layer.add_alpha():
+        raise lib.OpError('gimp_op_failed', 'GIMP could not add an alpha channel to this layer')
+    return True
+
+
+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
+    defined relative to the ANCESTOR's own extent, which transforming a descendant inside it
+    never changes, so it needs neither remapping nor refusing here (unlike a MASKED adjustment
+    filter's mask-channel alignment, which does -- see `_refuse_if_masked_filters_on`)."""
+    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
+    )
+
+
+def _refuse_if_tracked_effects_on(img, op_name, layer, reason):
+    tracked = _tracked_effect_names_on(img, layer)
+    if tracked:
+        raise ValueError(
+            '%s cannot proceed while effect filter(s) %s are present on this layer (or a group '
+            'containing it): %s. Delete these filters first and re-add them afterwards.'
+            % (op_name, ', '.join(repr(n) for n in tracked), 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, rotation_only=True)
+    if tracked:
+        raise ValueError(
+            '%s cannot use an arbitrary angle (%.4g°) while effect filter(s) %s are present on '
+            'this layer (or a group containing it): only an exact 0/90/180/270-degree rotation '
+            'keeps them locked to the content. Rotate at a right angle instead, or delete these '
+            'filters first and re-add them afterwards.'
+            % (op_name, degrees, ', '.join(repr(n) for n in tracked))
+        )
+
+
+def _transform_layer_precision(img):
+    return lib.transform_layer_precision_bucket(img.get_precision().value_nick)
+
+
+def _validate_transform_sizes(img, layer, matrix, precision):
+    """Validates `layer`'s own PREDICTED size (via `lib.transformed_bounds`, mapping the
+    layer's current rect through `matrix`) against the engine's precision-aware size cap
+    (`lib.validate_document_dims`, the same one gimp_create_document uses) -- and, for a GROUP
+    target, every non-group descendant's own predicted size the same way, plus the descendants'
+    summed pixel count (`lib.validate_group_total_pixels`; see this section's own comment). Does NOT validate the predicted ORIGIN -- callers whose own target position
+    is exactly `transformed_bounds`' own (new_x, new_y) call `_validated_move_offset` on it
+    themselves (`_validate_transform_prediction`, below); `fit`'s own target is the canvas
+    center instead, validated separately. Returns the layer's own predicted
+    (new_x, new_y, new_w, new_h)."""
+    ok, ox, oy = layer.get_offsets()
+    ox, oy = (ox if ok else 0), (oy if ok else 0)
+    w, h = layer.get_width(), layer.get_height()
+    new_x, new_y, new_w, new_h = lib.transformed_bounds(matrix, ox, oy, w, h)
+    lib.validate_document_dims(
+        lib.ceil_with_margin(new_w), lib.ceil_with_margin(new_h), precision=precision
+    )
+    if layer.is_group():
+        sizes = []
+        for descendant in _layer_subtree(layer):
+            if descendant.get_id() == layer.get_id() or descendant.is_group():
+                continue
+            dok, dx, dy = descendant.get_offsets()
+            dx, dy = (dx if dok else 0), (dy if dok else 0)
+            dw, dh = descendant.get_width(), descendant.get_height()
+            _, _, pred_w, pred_h = lib.transformed_bounds(matrix, dx, dy, dw, dh)
+            pw, ph = lib.ceil_with_margin(pred_w), lib.ceil_with_margin(pred_h)
+            lib.validate_document_dims(pw, ph, precision=precision)
+            sizes.append((pw, ph))
+        lib.validate_group_total_pixels(sizes, precision)
+    return new_x, new_y, new_w, new_h
+
+
+def _validate_transform_prediction(img, layer, matrix, precision):
+    """`_validate_transform_sizes` plus the same predicted-ORIGIN bound `move` enforces
+    (`_validated_move_offset`) -- every op whose own target position IS `transformed_bounds`'
+    predicted (new_x, new_y): rotate, skew, free, and scale (`fit`'s own target is the canvas
+    center instead; see its own handler)."""
+    new_x, new_y, new_w, new_h = _validate_transform_sizes(img, layer, matrix, precision)
+    _validated_move_offset(img, new_x, new_y)
+    return new_x, new_y, new_w, new_h
+
+
+def _transform_layer_fit(layer, img, args):
+    mode = lib.validate_choice('mode', args.get('mode', 'fit'), ('fit', 'fill'))
+    w, h = layer.get_width(), layer.get_height()
+    fraction = lib.fit_scale_fraction(w, h, img.get_width(), img.get_height(), mode)
+    if abs(fraction - 1.0) > 1e-9:
+        _refuse_if_tracked_effects_on(
+            img, 'fit', layer, 'fit/fill cannot keep them locked to the content at this scale'
+        )
+    cx, cy = _transform_layer_center(layer)
+    matrix = lib.compose_layer_matrix(cx, cy, fraction * 100.0, fraction * 100.0, 0.0, 0.0, 0.0, 0.0, 0.0)
+    precision = _transform_layer_precision(img)
+    # fit's own target is centered on the CANVAS, not wherever a scale-about-its-own-center
+    # would leave it -- only `matrix`'s predicted SIZE is used below; its predicted origin is
+    # irrelevant and is never read.
+    _, _, new_w, new_h = _validate_transform_sizes(img, layer, matrix, precision)
+    new_w_i, new_h_i = _snap_px(new_w), _snap_px(new_h)
+    lib.validate_transformed_layer_size(new_w_i, new_h_i)
+    target_x = (img.get_width() - new_w_i) / 2.0
+    target_y = (img.get_height() - new_h_i) / 2.0
+    _validated_move_offset(img, target_x, target_y)
+    planned = _snapshot_effect_transform(
+        img, 'fit',
+        lambda operation, params, flayer: lib.resize_effect_params(operation, params, fraction, fraction),
+        layers=_layer_subtree(layer),
+    )
+    alpha_added = _ensure_layer_alpha(layer)
+    x0, y0 = _snap_px(target_x), _snap_px(target_y)
+    result = layer.transform_scale(float(x0), float(y0), float(x0 + new_w_i), float(y0 + new_h_i))
+    _checked_transform(layer, result)
+    failures = _apply_planned_effect_transform(img, planned)
+    extra = {'mode': mode, 'scale_percent': round(fraction * 100.0, 6), 'alpha_added': alpha_added}
+    if failures:
+        extra['effect_update_failures'] = failures
+    return extra
+
+
+def _transform_layer_scale(layer, img, args):
+    lo, hi = lib.TRANSFORM_LAYER_MIN_SCALE_PERCENT, lib.TRANSFORM_LAYER_MAX_SCALE_PERCENT
+    sp = args.get('scale_percent')
+    sx_in, sy_in = args.get('scale_x_percent'), args.get('scale_y_percent')
+    if sx_in is None and sy_in is None:
+        if sp is None:
+            raise ValueError('scale requires scale_percent, or scale_x_percent/scale_y_percent')
+        sx = sy = lib.validate_range('scale_percent', sp, lo, hi)
+    else:
+        sx = lib.validate_range('scale_x_percent', sx_in if sx_in is not None else (sp if sp is not None else 100.0), lo, hi)
+        sy = lib.validate_range('scale_y_percent', sy_in if sy_in is not None else (sp if sp is not None else 100.0), lo, hi)
+    if abs(sx - sy) > 1e-9:
+        _refuse_if_tracked_effects_on(
+            img, 'scale', layer, 'a non-uniform scale cannot keep them locked to the content'
+        )
+    cx, cy = _transform_layer_center(layer)
+    matrix = lib.compose_layer_matrix(cx, cy, sx, sy, 0.0, 0.0, 0.0, 0.0, 0.0)
+    precision = _transform_layer_precision(img)
+    new_x, new_y, new_w, new_h = _validate_transform_prediction(img, layer, matrix, precision)
+    planned = _snapshot_effect_transform(
+        img, 'scale',
+        lambda operation, params, flayer: lib.resize_effect_params(operation, params, sx / 100.0, sy / 100.0),
+        layers=_layer_subtree(layer),
+    )
+    alpha_added = _ensure_layer_alpha(layer)
+    x0, y0 = _snap_px(new_x), _snap_px(new_y)
+    x1, y1 = _snap_px(new_x + new_w), _snap_px(new_y + new_h)
+    lib.validate_transformed_layer_size(x1 - x0, y1 - y0)
+    result = layer.transform_scale(float(x0), float(y0), float(x1), float(y1))
+    _checked_transform(layer, result)
+    failures = _apply_planned_effect_transform(img, planned)
+    extra = {'scale_x_percent': sx, 'scale_y_percent': sy, 'alpha_added': alpha_added}
+    if failures:
+        extra['effect_update_failures'] = failures
+    return extra
+
+
+def _transform_layer_move(layer, img, args):
+    delta, absolute, center_on = args.get('delta'), args.get('absolute'), args.get('center_on')
+    given = [m for m in (delta, absolute, center_on) if m is not None]
+    if len(given) == 0:
+        raise ValueError(
+            'move requires exactly one of delta, absolute, center_on -- each a {x, y} object; '
+            'flat fields like delta_x/absolute_x are not accepted'
+        )
+    if len(given) > 1:
+        raise ValueError(
+            'move accepts only ONE of delta, absolute, center_on -- not more than one (each a '
+            '{x, y} object; flat fields like delta_x/absolute_x are not accepted)'
+        )
+    ok, ox, oy = layer.get_offsets()
+    ox, oy = (ox if ok else 0), (oy if ok else 0)
+    w, h = layer.get_width(), layer.get_height()
+    if delta is not None:
+        nx, ny = ox + float(lib.require(delta, 'x')), oy + float(lib.require(delta, 'y'))
+    elif absolute is not None:
+        nx, ny = float(lib.require(absolute, 'x')), float(lib.require(absolute, 'y'))
+    else:
+        nx = float(lib.require(center_on, 'x')) - w / 2.0
+        ny = float(lib.require(center_on, 'y')) - h / 2.0
+    _validated_move_offset(img, nx, ny)
+    alpha_added = _ensure_layer_alpha(layer)
+    result = layer.set_offsets(_snap_px(nx), _snap_px(ny))
+    _checked_transform(layer, result)
+    return {'alpha_added': alpha_added}
+
+
+def _transform_layer_rotate(layer, img, args):
+    degrees = float(lib.require(args, 'degrees'))
+    if not math.isfinite(degrees):
+        raise ValueError('degrees must be finite')
+    _refuse_if_non_right_angle_tracked_effects_on(img, degrees, 'rotate', layer)
+    cx, cy = _transform_layer_center(layer)
+    matrix = lib.compose_layer_matrix(cx, cy, 100.0, 100.0, degrees, 0.0, 0.0, 0.0, 0.0)
+    precision = _transform_layer_precision(img)
+    _validate_transform_prediction(img, layer, matrix, precision)
+    planned = _snapshot_effect_transform(
+        img, 'rotate',
+        lambda operation, params, flayer: lib.rotate_effect_params(
+            operation, params, degrees, flayer.get_width(), flayer.get_height()
+        ),
+        layers=_layer_subtree(layer),
+    )
+    alpha_added = _ensure_layer_alpha(layer)
+    Gimp.context_set_transform_resize(Gimp.TransformResize.ADJUST)
+    result = layer.transform_rotate(math.radians(degrees), True, 0.0, 0.0)
+    _checked_transform(layer, result)
+    failures = _apply_planned_effect_transform(img, planned)
+    extra = {'degrees': degrees, 'alpha_added': alpha_added}
+    if failures:
+        extra['effect_update_failures'] = failures
+    return extra
+
+
+def _transform_layer_flip(layer, img, args):
+    axis = args.get('axis')
+    if axis not in _FLIP_ORIENTATIONS:
+        raise ValueError('axis must be one of %s' % sorted(_FLIP_ORIENTATIONS))
+    planned = _snapshot_effect_transform(
+        img, 'flip',
+        lambda operation, params, flayer: lib.flip_effect_params(operation, params, axis),
+        layers=_layer_subtree(layer),
+    )
+    alpha_added = _ensure_layer_alpha(layer)
+    result = layer.transform_flip_simple(_FLIP_ORIENTATIONS[axis], True, 0.0)
+    _checked_transform(layer, result)
+    failures = _apply_planned_effect_transform(img, planned)
+    extra = {'axis': axis, 'alpha_added': alpha_added}
+    if failures:
+        extra['effect_update_failures'] = failures
+    return extra
+
+
+def _transform_layer_skew(layer, img, args):
+    skew_h, skew_v = args.get('skew_h_degrees'), args.get('skew_v_degrees')
+    if skew_h is None and skew_v is None:
+        raise ValueError('skew requires at least one of skew_h_degrees, skew_v_degrees')
+    skew_h = float(skew_h) if skew_h is not None else 0.0
+    skew_v = float(skew_v) if skew_v is not None else 0.0
+    if not (math.isfinite(skew_h) and math.isfinite(skew_v)):
+        raise ValueError('skew_h_degrees/skew_v_degrees must be finite')
+    _refuse_if_tracked_effects_on(
+        img, 'skew', layer, 'a skew cannot keep them locked to the content at any angle'
+    )
+    cx, cy = _transform_layer_center(layer)
+    matrix = lib.compose_layer_matrix(cx, cy, 100.0, 100.0, 0.0, skew_h, skew_v, 0.0, 0.0)
+    precision = _transform_layer_precision(img)
+    _validate_transform_prediction(img, layer, matrix, precision)
+    alpha_added = _ensure_layer_alpha(layer)
+    Gimp.context_set_transform_resize(Gimp.TransformResize.ADJUST)
+    result = layer.transform_matrix(*matrix)
+    _checked_transform(layer, result)
+    return {'skew_h_degrees': skew_h, 'skew_v_degrees': skew_v, 'alpha_added': alpha_added}
+
+
+def _transform_layer_free(layer, img, args):
+    lo, hi = lib.TRANSFORM_LAYER_MIN_SCALE_PERCENT, lib.TRANSFORM_LAYER_MAX_SCALE_PERCENT
+    sx = lib.validate_range('scale_x_percent', args.get('scale_x_percent', 100.0), lo, hi)
+    sy = lib.validate_range('scale_y_percent', args.get('scale_y_percent', 100.0), lo, hi)
+    degrees = float(args.get('degrees', 0.0))
+    off_lo, off_hi = -lib.TRANSFORM_LAYER_MAX_OFFSET_PX, lib.TRANSFORM_LAYER_MAX_OFFSET_PX
+    offset_x = lib.validate_range('offset_x', args.get('offset_x', 0.0), off_lo, off_hi)
+    offset_y = lib.validate_range('offset_y', args.get('offset_y', 0.0), off_lo, off_hi)
+    if not math.isfinite(degrees):
+        raise ValueError('degrees must be finite')
+    _refuse_if_tracked_effects_on(
+        img, 'free', layer, 'a combined free transform cannot keep them locked to the content'
+    )
+    cx, cy = _transform_layer_center(layer)
+    matrix = lib.compose_layer_matrix(cx, cy, sx, sy, degrees, 0.0, 0.0, offset_x, offset_y)
+    precision = _transform_layer_precision(img)
+    _validate_transform_prediction(img, layer, matrix, precision)
+    alpha_added = _ensure_layer_alpha(layer)
+    Gimp.context_set_transform_resize(Gimp.TransformResize.ADJUST)
+    result = layer.transform_matrix(*matrix)
+    _checked_transform(layer, result)
+    return {
+        'scale_x_percent': sx, 'scale_y_percent': sy, 'degrees': degrees,
+        'offset_x': offset_x, 'offset_y': offset_y, 'alpha_added': alpha_added,
+    }
+
+
+TRANSFORM_LAYER_OPS = {
+    'fit': _transform_layer_fit,
+    'scale': _transform_layer_scale,
+    'move': _transform_layer_move,
+    'rotate': _transform_layer_rotate,
+    'flip': _transform_layer_flip,
+    'skew': _transform_layer_skew,
+    'free': _transform_layer_free,
+}
+
+
+def op_transform_layer(args):
+    img = _image(args)
+    top = args.get('op')
+    fn = TRANSFORM_LAYER_OPS.get(top)
+    if fn is None:
+        raise ValueError('op must be one of %s' % sorted(TRANSFORM_LAYER_OPS))
+    lib.reject_foreign_transform_fields(top, args)
+    layer = _layer(img, args)
+    _refuse_if_masked_filters_on(img, top, layer)
+    _refuse_if_layer_locked(layer)
+    # Interpolation (and, for rotate/skew/free, the ADJUST transform-resize mode) are ambient
+    # Context settings the transform methods below read rather than take as arguments -- pushed
+    # and popped so this call's choice never leaks into a LATER, unrelated gimp_* call (the same
+    # bracket `_fill_new_layer` uses around its own context changes). Each op validates its own
+    # arguments, the predicted result, and any tracked effect in scope, and raises BEFORE calling
+    # `_ensure_layer_alpha` (own code) or mutating anything, so a rejected call never adds an
+    # alpha channel it then goes on to refuse.
+    Gimp.context_push()
+    try:
+        interpolation = _set_transform_layer_interpolation(args)
+        Gimp.Selection.none(img)  # see op_open: geometry always applies to the whole layer
+        extra = fn(layer, img, args)
+    finally:
+        Gimp.context_pop()
+        _drop_proxies(img.get_id())
+    result = {
+        'layer_id': layer.get_id(),
+        'bounds': _transform_layer_bounds(layer),
+        'interpolation': interpolation,
+        'text_layer': layer.is_text_layer(),
+    }
+    result.update(extra)
+    return result
+
+
 def op_select_none(args):
     Gimp.Selection.none(_image(args))
     return {'selection': 'none'}
 
 
+# ---------- selection: gimp_select / gimp_modify_selection / gimp_layer_mask / masks ------------
+
+_CHANNEL_OPS = {
+    'replace': Gimp.ChannelOps.REPLACE, 'add': Gimp.ChannelOps.ADD,
+    'subtract': Gimp.ChannelOps.SUBTRACT, 'intersect': Gimp.ChannelOps.INTERSECT,
+}
+
+
+def _selection_to_channel(img, name):
+    """Copy the active selection into a (replaced) named channel, clear the selection, and return
+    the op result every selection op reports."""
+    w, h = img.get_width(), img.get_height()
+    rect = Gegl.Rectangle.new(0, 0, w, h)
+    data = img.get_selection().get_buffer().get(rect, 1.0, "Y' u8", Gegl.AbyssPolicy.NONE)
+    ch = _replace_named_channel(img, name, w, h)
+    buf = ch.get_buffer()
+    buf.set(rect, "Y' u8", data)
+    buf.flush()
+    ch.update(0, 0, w, h)
+    Gimp.Selection.none(img)
+    _drop_proxies(img.get_id())
+    selected, fraction = _channel_coverage(ch, w, h)
+    return {'channel': name, 'selected_pixels': selected, 'fraction': fraction}
+
+
+def _with_scratch_channel(img, w, h, fn):
+    """Run `fn(scratch_channel)` against a throwaway channel inserted for the duration of the
+    call, then remove it regardless of outcome -- including when `fn` itself raises partway
+    through (e.g. a bad gradient argument), so a failed select never leaves a stray channel
+    behind. Used to stash a selection's pixel data somewhere durable (a GIMP selection is a
+    single, unnamed piece of image state -- building a SECOND shape while the first is still
+    needed, as combine != 'replace' does, has nowhere else to put it).
+
+    Verified the same defensive way `_assert_layer_attached` checks a new layer: some GIMP calls
+    report success having silently done nothing, so insertion is confirmed by walking the image's
+    own live channel list rather than trusting the call's return value alone. If that check fails,
+    there is nothing to remove (the channel was never actually attached). Restores the image's
+    selected layers afterward -- see `_replace_named_channel`'s identical comment for why."""
+    original_selection = img.get_selected_layers()
+    scratch = Gimp.Channel.new(img, '__select_scratch__', w, h, 50.0, Gegl.Color.new('black'))
+    img.insert_channel(scratch, None, 0)
+    if not any(ch.get_id() == scratch.get_id() for ch in img.get_channels()):
+        raise lib.OpError('gimp_op_failed', 'the scratch channel did not attach to the image')
+    img.set_selected_layers(original_selection)
+    try:
+        return fn(scratch)
+    finally:
+        img.remove_channel(scratch)
+        img.set_selected_layers(original_selection)
+
+
+def _capture_selection(img, w, h, scratch):
+    """Copy the CURRENT active selection's pixels into `scratch`'s own buffer -- a durable
+    snapshot the caller can reload as the active selection later, after building a SECOND shape
+    (`_shape_selection`'s next call) would otherwise overwrite the first one."""
+    data = img.get_selection().get_buffer().get(
+        Gegl.Rectangle.new(0, 0, w, h), 1.0, "Y' u8", Gegl.AbyssPolicy.NONE)
+    buf = scratch.get_buffer()
+    buf.set(Gegl.Rectangle.new(0, 0, w, h), "Y' u8", data)
+    buf.flush()
+    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
+    selection touching the edge lost a strip there. Shrinking is the inverse of growing the
+    inverse, and a grow never reaches past the canvas, so shrink = invert, grow, invert."""
+    Gimp.Selection.invert(img)
+    Gimp.Selection.grow(img, px)
+    Gimp.Selection.invert(img)
+
+
+def _color_arg(img, drawable, args, sample_merged):
+    """The target color for mode=color_range: an explicit `color` hex, or the color AT a sample
+    point (x, y), always in document pixels. `Gimp.Image.pick_color` takes document coordinates
+    regardless of `sample_merged` and itself reports failure -- rather than a wrong or default
+    pixel -- for a point outside the image, or (when not sampling the composite) outside the one
+    given drawable's own bounds (verified live, GIMP 3.2.6: an out-of-bounds point returns
+    `(False, None)`, never raises and never silently samples the wrong pixel)."""
+    color = args.get('color')
+    if color is not None:
+        return Gegl.Color.new(lib.validate_hex_color('color', color))
+    if args.get('x') is None or args.get('y') is None:
+        raise ValueError('color_range needs `color` (e.g. "#c0392b") or a sample point x, y')
+    x, y = float(args['x']), float(args['y'])
+    success, picked = img.pick_color([drawable], x, y, sample_merged, False, 0.0)
+    if not success or picked is None:
+        where = 'the image' if sample_merged else 'layer %r' % drawable.get_name()
+        raise ValueError('sample point (%g, %g) is outside %s' % (x, y, where))
+    return picked
+
+
+def _layer_local_point(drawable, x, y):
+    """Convert a DOCUMENT-space point to coordinates local to `drawable`, refusing one outside its
+    bounds. `Gimp.Image.select_contiguous_color` (unlike `pick_color`) takes LOCAL coordinates when
+    sampling one drawable rather than the composite -- verified live, GIMP 3.2.6: an unconverted
+    document-space point on an offset layer selected the wrong region of that layer entirely
+    (or nothing, if the document point happened to fall outside the layer's own pixel extent)."""
+    _ok, ox, oy = drawable.get_offsets()
+    lx, ly = x - ox, y - oy
+    lw, lh = drawable.get_width(), drawable.get_height()
+    if not (0 <= lx < lw and 0 <= ly < lh):
+        raise ValueError(
+            'sample point (%g, %g) is outside layer %r (%dx%d at offset %d,%d)'
+            % (x, y, drawable.get_name(), lw, lh, ox, oy)
+        )
+    return lx, ly
+
+
+# A DoS floor on mode=polygon's point count -- the same reasoning as the resize/document pixel
+# caps elsewhere in this file.
+MAX_POLYGON_POINTS = 10_000
+
+
+def _polygon_segments(points):
+    """Validate `points` (mode=polygon's own argument) and flatten it into GIMP's flat
+    [x1, y1, x2, y2, ...] segment list. Every point must be an [x, y] pair of finite numbers -- a
+    malformed one (not a pair, a non-numeric value, NaN/Infinity) is refused here rather than
+    reaching `Gimp.Image.select_polygon` as garbage or silently coercing to 0."""
+    if not isinstance(points, list) or len(points) < 3:
+        raise ValueError('points must be a list of at least 3 [x, y] pairs')
+    if len(points) > MAX_POLYGON_POINTS:
+        raise ValueError('points must be at most %d pairs' % MAX_POLYGON_POINTS)
+    segs = []
+    for i, p in enumerate(points):
+        if not isinstance(p, (list, tuple)) or len(p) != 2:
+            raise ValueError('points[%d] must be an [x, y] pair' % i)
+        x, y = p
+        if (
+            not isinstance(x, (int, float)) or not isinstance(y, (int, float))
+            or not (math.isfinite(x) and math.isfinite(y))
+        ):
+            raise ValueError('points[%d] must be finite numbers' % i)
+        segs.extend([float(x), float(y)])
+    return segs
+
+
+def _shape_selection(img, mode, args, w, h):
+    """Build `mode`'s shape as the ACTIVE SELECTION, in ISOLATION (every branch uses
+    `Gimp.ChannelOps.REPLACE` against whatever was selected before, which is irrelevant -- the
+    caller always starts from a cleared selection). `op_select` applies `invert`/`feather_px` to
+    this shape ALONE, immediately after, before it is ever combined with an existing channel --
+    see `op_select`'s own docstring for why that order matters."""
+    REPLACE = Gimp.ChannelOps.REPLACE
+    sample_merged = lib.optional_bool(args, 'sample_merged', True)
+    Gimp.context_push()
+    try:
+        Gimp.context_set_feather(False)
+        Gimp.context_set_antialias(True)
+        threshold = lib.validate_range('threshold', args.get('threshold', 15), 0, 255)
+        Gimp.context_set_sample_threshold(threshold / 255.0)
+        Gimp.context_set_sample_merged(sample_merged)
+        Gimp.context_set_sample_criterion(Gimp.SelectCriterion.COMPOSITE)
+        # Set explicitly rather than inherited from whatever the session's own ambient context
+        # happens to already hold (a GUI action, or an earlier call, could have left either at a
+        # non-default value): sample_transparent False matches color_range/magic_wand's own
+        # "colour" framing -- a fully transparent pixel has no colour to match, so it is excluded
+        # from both the sampled target and the contiguous region, the same as GIMP's own tool
+        # defaults. diagonal_neighbors False keeps magic_wand's contiguous region 4-connected
+        # (up/down/left/right only), also GIMP's own tool default.
+        Gimp.context_set_sample_transparent(False)
+        Gimp.context_set_diagonal_neighbors(False)
+        if mode == 'all':
+            img.select_rectangle(REPLACE, 0, 0, w, h)
+        elif mode in ('rectangle', 'ellipse'):
+            x, y = float(lib.require(args, 'x')), float(lib.require(args, 'y'))
+            ww, hh = float(lib.require(args, 'width')), float(lib.require(args, 'height'))
+            (img.select_rectangle if mode == 'rectangle' else img.select_ellipse)(REPLACE, x, y, ww, hh)
+        elif mode == 'polygon':
+            segs = _polygon_segments(lib.require(args, 'points'))
+            img.select_polygon(REPLACE, segs)
+        elif mode == 'color_range':
+            drawable = _layer(img, args)
+            img.select_color(REPLACE, drawable, _color_arg(img, drawable, args, sample_merged))
+        elif mode == 'magic_wand':
+            drawable = _layer(img, args)
+            x, y = float(lib.require(args, 'x')), float(lib.require(args, 'y'))
+            if sample_merged:
+                # select_contiguous_color takes DOCUMENT coordinates when sampling the composite
+                # (verified live) -- bounds-checked against the image itself, since GIMP silently
+                # selects nothing for an out-of-image point rather than refusing it.
+                if not (0 <= x < w and 0 <= y < h):
+                    raise ValueError('sample point (%g, %g) is outside the %dx%d image' % (x, y, w, h))
+                img.select_contiguous_color(REPLACE, drawable, x, y)
+            else:
+                # ...but LOCAL coordinates when sampling one drawable (verified live) -- see
+                # _layer_local_point's own comment.
+                lx, ly = _layer_local_point(drawable, x, y)
+                img.select_contiguous_color(REPLACE, drawable, lx, ly)
+        elif mode == 'alpha':
+            img.select_item(REPLACE, _layer(img, args))
+        elif mode == 'channel':
+            src = _require_channel(img, lib.require(args, 'source'))
+            img.select_item(REPLACE, src)
+        else:
+            raise ValueError('unknown mode %r' % mode)
+    finally:
+        Gimp.context_pop()
+
+
+def op_select(args):
+    """Every mode builds its shape ALONE first (`_shape_selection`, or a gradient painted directly
+    into a scratch channel) -- `invert`/`feather_px` apply to that shape by itself, matching how a
+    feathered marquee combines in a raster editor: draw the new region, feather IT, then union/
+    subtract/intersect with whatever was already selected. Combining the raw (un-invert/feathered)
+    shape first would let those two options reach into the EXISTING channel's content instead,
+    which is not what either name promises."""
+    img = _image(args)
+    mode = lib.require(args, 'mode')
+    name = args.get('name', 'Selection')
+    combine = args.get('combine', 'replace')
+    if combine not in _CHANNEL_OPS:
+        raise ValueError('combine must be one of %s' % sorted(_CHANNEL_OPS))
+    _refuse_mask_in_use(img, name)
+    existing = _find_channel(img, name)
+    if combine != 'replace' and existing is None:
+        raise ValueError('combine=%s needs an existing channel named %r' % (combine, name))
+    invert = bool(args.get('invert', False))
+    feather_px = lib.validate_feather_px(args.get('feather_px', 0))
+    if feather_px > 0 and mode in ('gradient_linear', 'gradient_radial'):
+        raise ValueError(
+            'feather_px has no effect on a gradient (already a continuous ramp) -- omit it for '
+            'mode=%s rather than pass a value that would silently do nothing' % mode
+        )
+    w, h = img.get_width(), img.get_height()
+
+    try:
+        Gimp.Selection.none(img)
+        if mode in ('gradient_linear', 'gradient_radial'):
+            def _paint(scratch):
+                _paint_gradient_mask(scratch, mode, invert, args, w, h)
+                img.select_item(Gimp.ChannelOps.REPLACE, scratch)
+            _with_scratch_channel(img, w, h, _paint)
+            # invert is already applied above, as a color swap done while painting.
+        else:
+            _shape_selection(img, mode, args, w, h)
+            if invert:
+                Gimp.Selection.invert(img)
+            if feather_px > 0:
+                Gimp.Selection.feather(img, feather_px)
+
+        # The active selection is now the new shape ALONE, already invert/feathered -- never yet
+        # combined with whatever `name` previously held.
+        if combine == 'replace':
+            return _selection_to_channel(img, name)
+
+        def _combine(scratch):
+            _capture_selection(img, w, h, scratch)
+            img.select_item(Gimp.ChannelOps.REPLACE, existing)
+            img.select_item(_CHANNEL_OPS[combine], scratch)
+        _with_scratch_channel(img, w, h, _combine)
+        return _selection_to_channel(img, name)
+    finally:
+        Gimp.Selection.none(img)
+
+
+def op_modify_mask(args):
+    img = _image(args)
+    name = lib.require(args, 'channel')
+    out = args.get('output') or name
+    _refuse_mask_in_use(img, out)
+    ch = _require_channel(img, name)
+    how = lib.require(args, 'op')
+    try:
+        img.select_item(Gimp.ChannelOps.REPLACE, ch)
+        if how in ('expand', 'contract', 'border'):
+            # Capped well below feather's own range -- these are morphological ops whose cost
+            # scales with the radius AND the document's own megapixel count (see
+            # `effective_morphology_px`'s own comment for the live measurements behind this).
+            morphology_cap = lib.effective_morphology_px(img.get_width(), img.get_height())
+            px = lib.validate_positive_px('px', lib.require(args, 'px'), max_px=morphology_cap)
+            if how == 'expand':
+                Gimp.Selection.grow(img, px)
+            elif how == 'contract':
+                _shrink_edge_locked(img, px)
+            else:
+                Gimp.Selection.border(img, px)
+        elif how == 'feather':
+            px = lib.validate_positive_px('px', lib.require(args, 'px'))
+            Gimp.Selection.feather(img, px)
+        elif how == 'invert':
+            Gimp.Selection.invert(img)
+        elif how == 'harden':
+            _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))
+            _harden_selection(img)
+        else:
+            raise ValueError('unknown op %r' % how)
+        return _selection_to_channel(img, out)
+    finally:
+        Gimp.Selection.none(img)
+
+
+_LAYER_MASK_SOURCES = {
+    'white': Gimp.AddMaskType.WHITE, 'black': Gimp.AddMaskType.BLACK,
+    'alpha': Gimp.AddMaskType.ALPHA, 'grayscale': Gimp.AddMaskType.COPY,
+}
+
+
+def op_layer_mask(args):
+    img = _image(args)
+    layer = _layer(img, args)
+    how = lib.require(args, 'op')
+    mask = layer.get_mask()
+    if how == 'create':
+        source = args.get('source', 'channel')
+        # Resolve and validate EVERYTHING (the channel exists, or `source` names a real kind)
+        # before touching the layer's EXISTING mask: a typo'd channel name must never destroy a
+        # hand-tuned mask already in place. The new mask is built in full -- `create_mask` (a
+        # candidate GimpLayerMask object, not yet attached) succeeds independently of whatever
+        # mask the layer currently has -- and only once that succeeds is the old one discarded.
+        if source == 'channel':
+            ch = _require_channel(img, lib.require(args, 'channel'))
+            img.select_item(Gimp.ChannelOps.REPLACE, ch)
+            try:
+                new = layer.create_mask(Gimp.AddMaskType.SELECTION)
+            finally:
+                Gimp.Selection.none(img)
+        elif source in _LAYER_MASK_SOURCES:
+            new = layer.create_mask(_LAYER_MASK_SOURCES[source])
+        else:
+            raise ValueError('source must be one of %s' % sorted(['channel'] + list(_LAYER_MASK_SOURCES)))
+        if mask is not None:
+            layer.remove_mask(Gimp.MaskApplyMode.DISCARD)
+        if not layer.add_mask(new):
+            # Best-effort: put the old mask back rather than leaving the layer maskless on top of
+            # having failed to attach the new one. If this ALSO fails, the layer is left without a
+            # mask either way, but the attempt costs nothing.
+            if mask is not None:
+                layer.add_mask(mask)
+            raise lib.OpError(
+                'gimp_op_failed', 'GIMP could not attach the new mask to layer %r' % layer.get_name()
+            )
+        # `invert` runs AFTER add_mask -- verified live that inverting the mask object before it is
+        # attached to the layer has no visible effect (the invert is silently lost).
+        if lib.optional_bool(args, 'invert', False):
+            new.invert(False)
+    elif mask is None:
+        raise ValueError('layer %r has no mask' % layer.get_name())
+    elif how == 'delete':
+        layer.remove_mask(Gimp.MaskApplyMode.DISCARD)
+    elif how == 'apply':
+        layer.remove_mask(Gimp.MaskApplyMode.APPLY)
+    elif how == 'invert':
+        mask.invert(False)
+    else:
+        raise ValueError('unknown op %r' % how)
+    _drop_proxies(img.get_id())
+    return {'layer': layer.get_name(), 'layer_id': layer.get_id(), 'op': how,
+            '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
+    an exception here would leave the image orphaned in GIMP with no reference left to free it."""
+    tmp = Gimp.Image.new(w, h, Gimp.ImageBaseType.GRAY)
+    try:
+        lay = Gimp.Layer.new(tmp, 'm', w, h, Gimp.ImageType.GRAY_IMAGE, 100.0, Gimp.LayerMode.NORMAL)
+        tmp.insert_layer(lay, None, 0)
+        buf = lay.get_buffer()
+        buf.set(Gegl.Rectangle.new(0, 0, w, h), "Y' u8", data)
+        buf.flush()
+    except Exception:
+        tmp.delete()
+        raise
+    return tmp, lay
+
+
+def op_mask_preview(args):
+    img = _image(args)
+    ch = _require_channel(img, lib.require(args, 'channel'))
+    out_path = lib.require(args, 'out_path')
+    max_px = lib.validate_max_px(int(args.get('max_px', 1024)))
+    w, h = img.get_width(), img.get_height()
+    data = ch.get_buffer().get(Gegl.Rectangle.new(0, 0, w, h), 1.0, "Y' u8", Gegl.AbyssPolicy.NONE)
+    tmp, lay = _gray_bytes_image(data, w, h)
+    try:
+        _scale_to_max(tmp, max_px)
+        dw, dh = tmp.get_width(), tmp.get_height()
+        if args.get('style', 'overlay') == 'mask':
+            _export_stripped(tmp, out_path)
+            return {'path': out_path, 'width': dw, 'height': dh, 'unmirrored_filters': []}
+        small = lay.get_buffer().get(Gegl.Rectangle.new(0, 0, dw, dh), 1.0, "Y' u8",
+                                     Gegl.AbyssPolicy.NONE)
+    finally:
+        tmp.delete()
+    dup, unmirrored = _proxy_render(img, max_px)
+    try:
+        if dup.get_base_type() != Gimp.ImageBaseType.RGB:
+            dup.convert_rgb()
+        if (dup.get_width(), dup.get_height()) != (dw, dh):
+            dup.scale(dw, dh)
+        red = Gimp.Layer.new(dup, 'overlay', dw, dh, Gimp.ImageType.RGBA_IMAGE, 50.0,
+                             Gimp.LayerMode.NORMAL)
+        dup.insert_layer(red, None, 0)
+        Gimp.context_push()
+        try:
+            Gimp.context_set_foreground(Gegl.Color.new('red'))
+            red.fill(Gimp.FillType.FOREGROUND)
+        finally:
+            Gimp.context_pop()
+        m = red.create_mask(Gimp.AddMaskType.WHITE)
+        red.add_mask(m)
+        mb = m.get_buffer()
+        # Quick Mask style: red covers what is NOT selected.
+        mb.set(Gegl.Rectangle.new(0, 0, dw, dh), "Y' u8", small.translate(bytes(range(255, -1, -1))))
+        mb.flush()
+        dup.flatten()
+        _export_stripped(dup, out_path)
+        return {'path': out_path, 'width': dw, 'height': dh, 'unmirrored_filters': unmirrored}
+    finally:
+        dup.delete()
+
+
+def op_load_mask(args):
+    """A grey mask image (PNG/JPEG, white = selected) -> a named channel. With a layer, the mask
+    is taken to cover that layer's own bounds (e.g. a mask computed from `render_layer`).
+
+    Flattened onto an explicit OPAQUE BLACK layer at the bottom of the stack always -- never
+    GIMP's own flatten default (the session's current background colour, verified live) -- so a
+    source smaller than its own canvas, or carrying alpha, never picks up stray colour for the
+    gap/transparent area: a transparent (or uncovered) pixel means "not part of the mask" NOT
+    "selected". Every alpha-carrying layer's own composite space is set to RGB_PERCEPTUAL before
+    flattening, so the result is value x alpha IN PERCEPTUAL SPACE (verified live: a 50%-alpha
+    white pixel over black reads ~128, the plain 255 x 0.5), not a linear-light blend (which would
+    read ~186 for the same input) -- a mask is a plain 0-255 coverage value, not a photographed
+    light, so the perceptual (byte-arithmetic) reading is the one that matches every other mask
+    value this bridge produces."""
+    img = _image(args)
+    name = args.get('name', 'Mask')
+    _refuse_mask_in_use(img, name)
+    path = lib.require(args, 'path')
+    basename = os.path.basename(path)
+    if not os.path.exists(path):
+        raise FileNotFoundError('no file named %s to load as a mask' % basename)
+    w, h = img.get_width(), img.get_height()
+    if args.get('layer') or args.get('layer_id') is not None:
+        layer = _layer(img, args)
+        _ok, ox, oy = layer.get_offsets()
+        tw, th = layer.get_width(), layer.get_height()
+    else:
+        ox = oy = 0
+        tw, th = w, h
+    load_error = None
+    try:
+        src = Gimp.file_load(Gimp.RunMode.NONINTERACTIVE, Gio.File.new_for_path(path))
+    except Exception as e:
+        src = None
+        load_error = str(e)
+    if src is None:
+        detail = _path_free_detail(load_error)
+        raise lib.OpError('gimp_op_failed', 'could not load %s as a mask%s' % (basename, detail))
+    try:
+        lib.validate_loaded_mask_dims(src.get_width(), src.get_height())
+        if src.get_base_type() != Gimp.ImageBaseType.GRAY:
+            src.convert_grayscale()
+        for src_layer in src.get_layers():
+            if src_layer.has_alpha():
+                src_layer.set_composite_space(Gimp.LayerColorSpace.RGB_PERCEPTUAL)
+        bg = Gimp.Layer.new(src, 'mask-bg', src.get_width(), src.get_height(),
+                            Gimp.ImageType.GRAY_IMAGE, 100.0, Gimp.LayerMode.NORMAL)
+        src.insert_layer(bg, None, len(src.get_layers()))
+        Gimp.context_push()
+        try:
+            Gimp.context_set_foreground(Gegl.Color.new('black'))
+            bg.fill(Gimp.FillType.FOREGROUND)
+        finally:
+            Gimp.context_pop()
+        if (src.get_width(), src.get_height()) != (tw, th):
+            src.scale(tw, th)
+        flat = src.flatten()
+        data = flat.get_buffer().get(Gegl.Rectangle.new(0, 0, tw, th), 1.0, "Y' u8",
+                                     Gegl.AbyssPolicy.NONE)
+    finally:
+        src.delete()
+    ch = _replace_named_channel(img, name, w, h)
+    x0, y0, x1, y1 = lib.compute_mask_paste_rect(ox, oy, tw, th, w, h)
+    if x1 > x0 and y1 > y0:
+        if (ox, oy, tw, th) == (0, 0, w, h):
+            sub = data
+        else:
+            sub = b''.join(data[(y - oy) * tw + (x0 - ox):(y - oy) * tw + (x1 - ox)]
+                           for y in range(y0, y1))
+        buf = ch.get_buffer()
+        buf.set(Gegl.Rectangle.new(x0, y0, x1 - x0, y1 - y0), "Y' u8", sub)
+        buf.flush()
+        ch.update(0, 0, w, h)
+    Gimp.Selection.none(img)
+    _drop_proxies(img.get_id())
+    selected, fraction = _channel_coverage(ch, w, h)
+    return {'channel': name, 'selected_pixels': selected, 'fraction': fraction}
+
+
+def op_render_layer(args):
+    """One layer's own pixels (not the composite), downscaled, to out_path -- the input for a mask
+    that should follow that layer. Returns the layer's bounds in document pixels.
+
+    Rendered as if the layer were fully VISIBLE, at 100% opacity, in Normal mode -- set on the
+    duplicated layer before flatten, so a hidden, partially-transparent, or blend-mode layer still
+    renders its own pixels plainly rather than the (possibly empty or blended-dark) result its
+    current display settings would otherwise produce. The layer's own mask and any live filters
+    are still included, exactly as they would render in the document. Any remaining transparency
+    (the layer's own alpha, not just visibility/opacity/mode) is flattened onto an explicit OPAQUE
+    WHITE background -- not whatever the session's own ambient context background happens to be --
+    since the output feeds a subject/object detector that expects an ordinary opaque photo."""
+    img = _image(args)
+    layer = _layer(img, args)
+    out_path = lib.require(args, 'out_path')
+    max_px = lib.validate_max_px(int(args.get('max_px', 2048)))
+    lw, lh = layer.get_width(), layer.get_height()
+    _ok, ox, oy = layer.get_offsets()
+    tmp = Gimp.Image.new(lw, lh, Gimp.ImageBaseType.RGB)
+    try:
+        nl = Gimp.Layer.new_from_drawable(layer, tmp)
+        tmp.insert_layer(nl, None, 0)
+        nl.set_offsets(0, 0)
+        nl.set_visible(True)
+        nl.set_opacity(100.0)
+        nl.set_mode(Gimp.LayerMode.NORMAL)
+        bg = Gimp.Layer.new(tmp, 'render-bg', lw, lh, Gimp.ImageType.RGB_IMAGE, 100.0,
+                            Gimp.LayerMode.NORMAL)
+        tmp.insert_layer(bg, None, 1)
+        Gimp.context_push()
+        try:
+            Gimp.context_set_foreground(Gegl.Color.new('white'))
+            bg.fill(Gimp.FillType.FOREGROUND)
+        finally:
+            Gimp.context_pop()
+        _scale_to_max(tmp, max_px)
+        tmp.flatten()
+        _export_stripped(tmp, out_path)
+        return {'path': out_path, 'width': tmp.get_width(), 'height': tmp.get_height(),
+                'layer_id': layer.get_id(), 'bounds': {'x': ox, 'y': oy, 'width': lw, 'height': lh}}
+    finally:
+        tmp.delete()
+
+
 def op_close(args):
     img = _image(args)
     _drop_proxies(img.get_id())
@@ -3067,6 +5907,11 @@ OPS = {
     'select_none': op_select_none, 'layer': op_layer, 'bake': op_bake,
     'create_document': op_create_document, 'place_image': op_place_image,
     'canvas': op_canvas, 'convert_image_mode': op_convert_image_mode,
+    'text': op_text, 'fonts': op_fonts,
+    '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, 'retouch': op_retouch, 'fill': op_fill, 'render_region': op_render_region,
 }