editmamei 1.7.0 → 1.8.0

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

@@ -423,6 +423,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'])
@@ -579,13 +589,6 @@ SETTERS = {
 }
 
 
-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 +613,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 +638,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 +660,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 +694,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 +789,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 +815,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):
@@ -912,6 +995,340 @@ def op_effect(args):
     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)
+    Gimp.Selection.sharpen(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)
+            Gimp.Selection.sharpen(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,
+    }
+
+
 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 +1386,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 +1398,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):
@@ -1240,7 +1665,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,13 +1680,18 @@ 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()}
     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():
@@ -1816,12 +2246,18 @@ def op_export(args):
 
 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."""
+    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 +2292,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 +2334,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 +2350,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 +2603,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 +2613,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 +2641,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 +2666,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))
         )
 
@@ -2479,19 +2963,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 +3075,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 +3090,333 @@ 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 _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)
+    justification = None
+    if args.get('alignment') is not None:
+        justification = _JUSTIFICATIONS[lib.justification_nick(args['alignment'])]
+    _layer_type_for(img)  # refuses image modes a text layer cannot be added to (indexed)
+    font = _resolved_font(_font_list(), args.get('font_name'))
+    size_px = lib.pt_to_px(size_pt, _image_ppi(img))
+    _check_estimated_text_size(text, font, size_px, img)
+    layer = Gimp.TextLayer.new(img, text, font, size_px, Gimp.Unit.pixel())
+    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)
+        lib.check_text_layer_size(layer.get_width(), layer.get_height())
+        layer.set_offsets(x, y)
+        record = _text_record(layer)
+    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'))
+    return _op_text_edit(
+        img, args, lambda layer: layer.set_text(text),
+        precheck_fn=lambda layer: _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):
+        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))
+
+
+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,
+}
+
+
+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 +3529,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 +3644,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 +3715,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 +3850,1034 @@ 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):
+    """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)
+    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)
+    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 _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':
+            Gimp.Selection.sharpen(img)
+        elif how == 'smooth':
+            # Round off jaggies: feather, then re-threshold at 50%. `px` is optional here (unlike
+            # the four ops above) -- a plain smoothing pass with no caller-chosen radius is still
+            # meaningful, so it floors at 1.0 rather than requiring one.
+            px = lib.validate_range('px', args.get('px', 0), 0, lib.MAX_FEATHER_PX)
+            Gimp.Selection.feather(img, max(px, 1.0))
+            Gimp.Selection.sharpen(img)
+        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 _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 +4895,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,
 }