editmamei 1.7.1 → 1.9.0

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

@@ -13,6 +13,7 @@
 # helpers below do real file I/O, same as any other stdlib code would.
 
 import collections
+import itertools
 import json
 import math
 import os
@@ -21,7 +22,13 @@ import sys
 import time
 import traceback
 
-LEDGER_VERSION = 1
+# The newest ledger version this bridge reads and writes. A document is written at the lowest
+# version that can hold its records: version 2 added the outline, outer_glow and surface_blur
+# types, whose params an earlier bridge cannot read. Written as 2, an earlier bridge treats the
+# ledger as newer than itself (it reads the filters back from GIMP and leaves the ledger alone)
+# instead of failing on them; a ledger without them stays version 1, which every bridge reads.
+LEDGER_VERSION = 2
+LEDGER_V2_TYPES = frozenset(('outline', 'outer_glow', 'surface_blur'))
 LEDGER_WRITER = 'editmamei'
 
 HIST_CHANNELS = ('luminance', 'red', 'green', 'blue')
@@ -84,7 +91,9 @@ SPATIAL_SCALE_PROPS = {
     'gegl:gaussian-blur': ('std-dev-x', 'std-dev-y'),
     'gegl:motion-blur-linear': ('length',),
     'gegl:focus-blur': ('blur-radius',),
-    'gegl:dropshadow': ('x', 'y', 'radius'),
+    'gegl:dropshadow': ('x', 'y', 'radius', 'grow-radius'),
+    # surface_blur's blur-radius is a pixel neighborhood, scaled like any other radius.
+    'gegl:bilateral-filter': ('blur-radius',),
     # gegl:vignette and gegl:mono-mixer are deliberately absent: vignette's radius/x/y are
     # proportional (fractions of the LAYER's own size, not absolute pixel lengths), and
     # mono-mixer is a per-pixel channel-weight filter with no spatial extent at all.
@@ -128,6 +137,7 @@ MASK_TYPES = ('rectangle', 'ellipse', 'gradient_linear', 'gradient_radial')
 #   hard_light=hardlight darken=darken-only lighten=lighten-only difference=difference
 #   exclusion=exclusion addition=addition subtract=subtract divide=divide dodge=dodge burn=burn
 #   hue=hsv-hue saturation=hsv-saturation color=hsl-color luminosity=luminance
+#   grain_extract=grain-extract grain_merge=grain-merge
 # hue/saturation/color/luminosity map to the HSV/HSL (not LCH) variants -- those are the ones
 # GIMP's own UI labels plainly "Hue"/"Saturation"/"Color"/"Luminosity" without a "(LCH)" suffix.
 LAYER_MODES = {
@@ -150,6 +160,8 @@ LAYER_MODES = {
     'saturation': 'HSV_SATURATION',
     'color': 'HSL_COLOR',
     'luminosity': 'LUMINANCE',
+    'grain_extract': 'GRAIN_EXTRACT',
+    'grain_merge': 'GRAIN_MERGE',
 }
 
 
@@ -159,6 +171,171 @@ def validate_layer_mode(value):
     return value
 
 
+# ---- gimp_fill ---------------------------------------------------------------------------------
+
+FILL_OPS = ('solid', 'linear_gradient', 'radial_gradient')
+FILL_MIN_STOPS = 2
+FILL_MAX_STOPS = 8
+# gimp_fill takes gimp_layer's blend-mode names plus 'lch_color': GIMP's LCh Color keeps the
+# layer underneath's lightness exactly and swaps only hue and chroma, which is what a recolor
+# wants. 'color' stays HSL Color (see LAYER_MODES), so existing callers are unchanged.
+FILL_MODES = dict(LAYER_MODES, lch_color='LCH_COLOR')
+_HEX_COLOR_RE = re.compile(r'^#[0-9a-fA-F]{6}$')
+
+
+def _is_number(v):
+    if not isinstance(v, (int, float)) or isinstance(v, bool):
+        return False
+    try:
+        return math.isfinite(v)
+    except OverflowError:  # an int too large for a float (10**400)
+        return False
+
+
+def parse_hex_color(name, value):
+    """'#rrggbb' (strictly: a leading '#' and six hex digits) -> (r, g, b) ints 0..255."""
+    if not isinstance(value, str) or not _HEX_COLOR_RE.match(value):
+        raise ValueError('%s must be a color like #rrggbb' % name)
+    return int(value[1:3], 16), int(value[3:5], 16), int(value[5:7], 16)
+
+
+def _fill_point(name, value, default):
+    if value is None:
+        return default
+    if not isinstance(value, dict) or not _is_number(value.get('x')) or not _is_number(value.get('y')):
+        raise ValueError('%s must be {x, y} with finite numbers' % name)
+    try:
+        x, y = float(value['x']), float(value['y'])
+    except OverflowError:  # a Python int too large for a float (10**400)
+        raise ValueError('%s is out of range' % name)
+    if abs(x) > FILL_MAX_COORD_PX or abs(y) > FILL_MAX_COORD_PX:
+        raise ValueError('%s must be within +/-%d px' % (name, FILL_MAX_COORD_PX))
+    return x, y
+
+
+def validate_fill_stops(stops):
+    """2..8 stops [{offset 0..1, color #rrggbb, opacity? 0..100}], offsets non-decreasing (they
+    must arrive sorted: a mis-ordered list is a caller mistake, not something to silently fix).
+    Returns [(offset, (r, g, b), alpha 0..1)]."""
+    if not isinstance(stops, list) or not FILL_MIN_STOPS <= len(stops) <= FILL_MAX_STOPS:
+        raise ValueError('stops must be a list of %d..%d stops' % (FILL_MIN_STOPS, FILL_MAX_STOPS))
+    out = []
+    for i, s in enumerate(stops):
+        if not isinstance(s, dict):
+            raise ValueError('stops[%d] must be an object {offset, color, opacity?}' % i)
+        offset = s.get('offset')
+        if not _is_number(offset) or not 0 <= offset <= 1:
+            raise ValueError('stops[%d].offset must be a number within 0..1' % i)
+        opacity = s.get('opacity', 100)
+        if not _is_number(opacity) or not 0 <= opacity <= 100:
+            raise ValueError('stops[%d].opacity must be within 0..100' % i)
+        if out and offset < out[-1][0]:
+            raise ValueError('stops must be sorted by offset: stops[%d] comes before stops[%d]' % (i, i - 1))
+        out.append((float(offset), parse_hex_color('stops[%d].color' % i, s.get('color')), opacity / 100.0))
+    return out
+
+
+def gradient_ramp(stops):
+    """The stops widened to cover the whole 0..1 range (the first color holds back to 0, the last
+    holds on to 1), so the gradient is defined everywhere. Returns a new list."""
+    ramp = list(stops)
+    if ramp[0][0] > 0:
+        ramp.insert(0, (0.0,) + ramp[0][1:])
+    if ramp[-1][0] < 1:
+        ramp.append((1.0,) + ramp[-1][1:])
+    return ramp
+
+
+def _fill_name(value, op):
+    name = str(value or ('Fill' if op == 'solid' else 'Gradient')).strip() or 'Fill'
+    if len(name) > FILL_MAX_STRING_LEN:
+        raise ValueError('name must be at most %d characters' % FILL_MAX_STRING_LEN)
+    return name
+
+
+def validate_fill_args(args, width, height):
+    """Everything gimp_fill needs, validated before any GIMP call. Points are image pixels."""
+    op = validate_choice('op', args.get('op'), FILL_OPS)
+    opts = {
+        'op': op,
+        'name': _fill_name(args.get('name'), op),
+        'mode': validate_choice('mode', args.get('mode', 'normal'), FILL_MODES),
+        'mask': args.get('mask'),
+    }
+    opacity = args.get('opacity', 100)
+    if not _is_number(opacity) or not 0 <= opacity <= 100:
+        raise ValueError('opacity must be within 0..100')
+    opts['opacity'] = float(opacity)
+    if opts['mask'] is not None and (not isinstance(opts['mask'], str) or not opts['mask']):
+        raise ValueError('mask must be a channel name')
+    if opts['mask'] is not None and len(opts['mask']) > FILL_MAX_STRING_LEN:
+        raise ValueError('mask must be at most %d characters' % FILL_MAX_STRING_LEN)
+    if op == 'solid':
+        opts['color'] = parse_hex_color('color', args.get('color'))
+        for k in ('stops', 'start', 'end', 'center', 'radius'):
+            if args.get(k) is not None:
+                raise ValueError('%s does not apply to op solid' % k)
+        return opts
+    if args.get('color') is not None:
+        raise ValueError('color applies to op solid only; a gradient takes stops')
+    opts['stops'] = validate_fill_stops(args.get('stops'))
+    if op == 'linear_gradient':
+        for k in ('center', 'radius'):
+            if args.get(k) is not None:
+                raise ValueError('%s does not apply to op linear_gradient' % k)
+        opts['start'] = _fill_point('start', args.get('start'), (width / 2.0, 0.0))
+        opts['end'] = _fill_point('end', args.get('end'), (width / 2.0, float(height)))
+        if math.hypot(opts['end'][0] - opts['start'][0], opts['end'][1] - opts['start'][1]) < 1:
+            raise ValueError('start and end must be at least 1 pixel apart')
+    else:
+        for k in ('start', 'end'):
+            if args.get(k) is not None:
+                raise ValueError('%s does not apply to op radial_gradient' % k)
+        opts['center'] = _fill_point('center', args.get('center'), (width / 2.0, height / 2.0))
+        radius = args.get('radius')
+        if radius is None:
+            radius = math.hypot(width, height) / 2.0
+        if not _is_number(radius) or not 1 <= radius <= FILL_MAX_COORD_PX:
+            raise ValueError('radius must be within 1..%d pixels' % FILL_MAX_COORD_PX)
+        opts['radius'] = float(radius)
+    return opts
+
+
+# ---- masked measurement (gimp_get_histogram `mask`) ---------------------------------------------
+
+MASK_SELECTED_MIN = 128  # a mask pixel counts as selected at 50% or more (>= 128 of 255)
+_MASK_FLAG_TABLE = bytes(1 if v >= MASK_SELECTED_MIN else 0 for v in range(256))
+
+
+def mask_flags(mask_data):
+    """One byte per mask pixel: 1 where the pixel is selected (>= 50%), else 0."""
+    return bytes(mask_data).translate(_MASK_FLAG_TABLE)
+
+
+# A hard-edged mask scaled down keeps a ring of partial-coverage pixels around its edge; a thin
+# one is ALL ring (a 1 px line reads as a pale smear whose pixels blend with their neighbors).
+# Past this share of edge pixels among the touched ones the scaled copy is not trusted.
+MASK_EDGE_FRACTION_MAX = 0.25
+
+
+def mask_is_proxy_reliable(mask_data):
+    """Whether a downscaled copy's mask is solid enough to measure. Not when it touches nothing
+    (it may have vanished in the scale-down; the full-resolution pass tells that from a mask that
+    is truly empty) or when its partial-coverage pixels (not 0, not 255) are more than
+    MASK_EDGE_FRACTION_MAX of all the pixels it touches."""
+    data = bytes(mask_data)
+    touched = len(data) - data.count(0)
+    if touched == 0:
+        return False
+    edge = touched - data.count(255)
+    return edge <= MASK_EDGE_FRACTION_MAX * touched
+
+
+def select_masked(data, flags):
+    """The bytes of `data` (one value per pixel) at the positions `flags` marks 1."""
+    return bytes(itertools.compress(data, flags))
+
+
 # gimp_layer op=create's fill options -- verified live that `Gimp.FillType.TRANSPARENT` exists
 # and that a freshly created layer's content is otherwise undefined, so `create` always fills
 # explicitly rather than trusting whatever `Gimp.Layer.new` leaves behind.
@@ -175,16 +352,170 @@ IMAGE_MODES = ('rgb', 'grayscale')
 EXPORT_FORMATS = {'.jpg': 'jpeg', '.jpeg': 'jpeg', '.png': 'png', '.webp': 'webp',
                   '.tif': 'tiff', '.tiff': 'tiff'}
 
+# Formats `_export_layered` (ops.py) writes with the layer stack kept, instead of a flattened copy.
+LAYERED_EXPORT_FORMATS = {'.psd': 'psd'}
+
 BIT_DEPTHS = (8, 16)
 
 # A DoS floor for `resize`: bounds a single call's memory/time cost regardless of how large the
 # SOURCE document already is (crop/rotate/flip only ever shrink-or-preserve the existing canvas,
 # so they don't need this; resize is the one op that can grow it arbitrarily from a tiny source).
 MAX_RESIZE_SIDE_PX = 30_000
-MAX_RESIZE_MEGAPIXELS = 250
+# gimp_fill's geometry bounds: a gradient axis may sit well off-canvas but not at 1e308, where
+# GIMP's float arithmetic overflows. Also the longest layer name / mask channel name it takes.
+FILL_MAX_COORD_PX = 10 * MAX_RESIZE_SIDE_PX
+FILL_MAX_STRING_LEN = 255
+_DEFAULT_MAX_RESIZE_MEGAPIXELS = 250
+
+
+def megapixel_cap_from_env(raw, default=_DEFAULT_MAX_RESIZE_MEGAPIXELS):
+    """A host-supplied (`EM_GIMP_MAX_MEGAPIXELS`) ceiling that can only LOWER `default` -- a memory-
+    constrained host (e.g. a small container) tightens every pixel-growing op's cap this way. Anything
+    that is not a finite positive number below `default` (unset, empty, junk, NaN/inf, zero/negative,
+    or an attempt to RAISE it) is ignored and `default` is returned unchanged."""
+    if not raw:
+        return default
+    try:
+        value = float(raw)
+    except (TypeError, ValueError):
+        return default
+    if not math.isfinite(value) or value <= 0 or value >= default:
+        return default
+    return value
+
+
+MAX_RESIZE_MEGAPIXELS = megapixel_cap_from_env(os.environ.get('EM_GIMP_MAX_MEGAPIXELS'))
 
 MAX_FEATHER_PX = 1000
 
+# Hardening a mask read as "Y' u8": 50% and above becomes fully selected (255), the rest 0. The
+# same 128 cut `_channel_coverage` counts as selected. Applied with `bytes.translate`, a C pass.
+HARDEN_TABLE = bytes(255 if v >= 128 else 0 for v in range(256))
+# Rows per band when hardening, so a very large mask is never held twice in memory at once.
+HARDEN_BAND_ROWS = 512
+
+
+def harden_mask_bytes(data):
+    """`data` ("Y' u8" mask bytes) with every value hardened to 0 or 255 at the 50% cut."""
+    return bytes(data).translate(HARDEN_TABLE)
+
+# gimp_modify_selection's expand/contract/border radius cap -- much lower than MAX_FEATHER_PX.
+# `Gimp.Selection.grow`/`shrink`/`border` are morphological (structuring-element) operations whose
+# cost scales with the radius, unlike `feather` (a GEGL blur, flat ~0.5s regardless of radius on a
+# 24MP image, measured live). This is the cap for a document at or below MORPHOLOGY_BASELINE_MP;
+# a bigger document gets a SMALLER cap -- see `effective_morphology_px`.
+MAX_MORPHOLOGY_PX = 150
+
+# Measured live at px=150 (border, the most expensive of the three): ~30s at 24MP (6016x4000),
+# ~73.5s at 100MP (14000x7143), and a GIMP session OUTRIGHT TIMEOUT past 180s at ~217MP
+# (30000x7228, this bridge's own largest allowed document -- MAX_RESIZE_SIDE_PX/
+# MAX_RESIZE_MEGAPIXELS). Cost does not scale linearly with megapixels (100MP was only ~2.45x the
+# 24MP cost for a ~4.17x bigger image), but it very much does not fit inside
+# gimp_modify_selection's budget either, so the cap itself has to shrink as the document grows.
+MORPHOLOGY_BASELINE_MP = 24.0
+# A document-size floor so a huge document still gets a meaningfully large morphology radius
+# rather than being squeezed to single-digit pixels.
+MIN_MORPHOLOGY_PX = 10
+
+
+def effective_morphology_px(width, height):
+    """The actual expand/contract/border cap for a `width`x`height` document: `MAX_MORPHOLOGY_PX`
+    at or below `MORPHOLOGY_BASELINE_MP`, shrinking as 1/megapixels above it (simple and, per the
+    live measurements on `MAX_MORPHOLOGY_PX`'s own comment, SAFELY conservative -- the real cost
+    curve is sub-linear in megapixels, so this reduces the cap by more than the measured cost
+    alone would require). Verified live at the two points that matter: at ~100MP the scaled cap
+    (36px) cost ~11.8s; at ~217MP (this bridge's largest allowed document) the scaled cap (17px)
+    cost ~27.2s -- both comfortably inside gimp_modify_selection's 45s budget with its own margin,
+    even though a large document also carries a substantial FIXED per-call cost that shrinking
+    `px` alone cannot remove (measured ~13-17s of that 27.2s at ~217MP comes from px=5 alone,
+    i.e. just handling a document that size, before any morphology radius is even considered)."""
+    megapixels = (width * height) / 1_000_000.0
+    if megapixels <= MORPHOLOGY_BASELINE_MP:
+        return MAX_MORPHOLOGY_PX
+    scaled = MAX_MORPHOLOGY_PX * MORPHOLOGY_BASELINE_MP / megapixels
+    return max(MIN_MORPHOLOGY_PX, min(MAX_MORPHOLOGY_PX, round(scaled)))
+
+
+# gimp_transform_layer's scale/scale_x_percent/scale_y_percent bound -- generous enough for any
+# real use (100x in either direction) while still keeping a single call's resulting layer size
+# bounded alongside validate_resize_dims' own check on the actual pixel dimensions.
+TRANSFORM_LAYER_MIN_SCALE_PERCENT = 1
+TRANSFORM_LAYER_MAX_SCALE_PERCENT = 10_000
+
+# gimp_transform_layer's `interpolation` choices -- the GIMP resampling filters this bridge
+# exposes, by name. The gi-dependent mapping to the real `Gimp.InterpolationType` enum members
+# lives in ops.py (this module stays gi-free).
+TRANSFORM_LAYER_INTERPOLATIONS = ('none', 'linear', 'cubic', 'nohalo', 'lohalo')
+
+# gimp_transform_layer's `free` op: offset_x/offset_y bound -- a sanity ceiling on the final
+# absolute translation, well past MAX_RESIZE_SIDE_PX (30000) so any real placement fits, but
+# tight enough that a wildly out-of-range value is refused here rather than only by the derived
+# predicted-origin check (`_validated_move_offset`) it also feeds into.
+TRANSFORM_LAYER_MAX_OFFSET_PX = 100_000
+
+# gimp_transform_layer's own op -> the field names that op reads, the same role
+# `type_fields`/`FILTER_COMMON_KEYS` play for gimp_add_adjustment/gimp_add_effect above --
+# `reject_foreign_transform_fields` refuses any OTHER declared field a caller sent (e.g. a
+# PS-style flat `delta_x`, or `skew_h_degrees` on op=scale), so a typo validates instead of
+# silently being ignored by that op's own handler.
+TRANSFORM_LAYER_COMMON_KEYS = frozenset(('image', 'op', 'layer', 'layer_id', 'interpolation'))
+
+TRANSFORM_LAYER_OP_FIELDS = {
+    'fit': ('mode',),
+    'scale': ('scale_percent', 'scale_x_percent', 'scale_y_percent'),
+    'move': ('delta', 'absolute', 'center_on'),
+    'rotate': ('degrees',),
+    'flip': ('axis',),
+    'skew': ('skew_h_degrees', 'skew_v_degrees'),
+    'free': ('scale_x_percent', 'scale_y_percent', 'degrees', 'offset_x', 'offset_y'),
+}
+
+
+def reject_foreign_transform_fields(op, args):
+    """Refuse any field `op` does not read -- the gimp_transform_layer analogue of
+    `reject_foreign_fields` above, over `TRANSFORM_LAYER_OP_FIELDS` instead of the filter-type
+    tables. `op`'s own schema is flat (one property per name across every op), so without this a
+    field meant for a DIFFERENT op (`skew_h_degrees` on op=scale, or PS's flat `delta_x` instead
+    of this tool's nested `delta`) validates, is ignored by that op's own handler, and silently
+    does nothing. None values are ignored (an omitted field)."""
+    own = TRANSFORM_LAYER_OP_FIELDS.get(op, ())
+    foreign = sorted(
+        k for k, v in args.items()
+        if v is not None and k not in TRANSFORM_LAYER_COMMON_KEYS and k not in own
+    )
+    if foreign:
+        raise ValueError(
+            "op '%s' does not use field(s) %s; its fields are: %s"
+            % (op, ', '.join(foreign), ', '.join(own) or '(none)')
+        )
+
+
+def ceil_with_margin(value):
+    """`value` rounded UP to the next whole pixel, plus one more -- the conservative integer a
+    cap check validates against for a float `transformed_bounds` predicts, matching the extra
+    pixel GIMP's own ADJUST transform-resize can add by rounding each edge of a rotated/sheared
+    bounding box outward independently (floor the min edge, ceil the max edge), which can land
+    the ACTUAL resulting integer width/height one pixel past a plain `ceil` of the float width.
+    Never used for the transform's own corner coordinates (those stay exact floats) -- only for
+    deciding whether to refuse BEFORE any pixel moves."""
+    return int(math.ceil(value)) + 1
+
+
+def transform_layer_precision_bucket(precision_nick):
+    """`Gimp.Precision.value_nick` (e.g. 'u8-non-linear', 'u16-perceptual', 'float-linear')
+    bucketed into the '8'/'16'/'32' strings `validate_document_dims`'s own
+    `DOCUMENT_MEGAPIXEL_CAP` is keyed by -- gimp_transform_layer validates a layer's predicted
+    size against the SAME precision-aware cap gimp_create_document does, rather than always
+    assuming 8-bit. u16 and half bucket to '16' (2 bytes/channel); every other precision (u32,
+    float, double) buckets to '32' (4+ bytes/channel, the most conservative bucket) -- this
+    bridge has no DOCUMENT_MEGAPIXEL_CAP entry finer than that."""
+    nick = precision_nick.lower()
+    if nick.startswith('u8'):
+        return '8'
+    if nick.startswith('u16') or nick.startswith('half'):
+        return '16'
+    return '32'
+
 
 def require(args, name):
     """Fetch a required field from an op's `args`, raising ValueError naming it -- the
@@ -195,6 +526,24 @@ def require(args, name):
     return args[name]
 
 
+GINT32_MAX = 2147483647
+
+
+def gimp_id(value):
+    """`value` as an image or item id GIMP's gint32 `get_by_id` can take, or None when it can't be
+    one (a bool, not a whole number, below 1, or past gint32). The caller then answers "no ... with
+    id N" instead of letting PyGObject raise a raw OverflowError on the lookup."""
+    if isinstance(value, bool):
+        return None
+    try:
+        number = int(value)
+    except (TypeError, ValueError, OverflowError):
+        return None
+    if isinstance(value, float) and value != number:
+        return None
+    return number if 1 <= number <= GINT32_MAX else None
+
+
 def require_bool(args, name):
     """Like `require`, but also rejects anything that isn't a real JSON boolean -- `bool("false")`
     is `True` in Python (any non-empty string is truthy), so a caller that sends the STRING
@@ -270,7 +619,7 @@ def validate_resize_dims(width, height):
         raise ValueError('width and height must each be at most %d px' % MAX_RESIZE_SIDE_PX)
     megapixels = (width * height) / 1_000_000.0
     if megapixels > MAX_RESIZE_MEGAPIXELS:
-        raise ValueError('resize target must be at most %d MP' % MAX_RESIZE_MEGAPIXELS)
+        raise ValueError('resize target must be at most %g MP' % MAX_RESIZE_MEGAPIXELS)
     return width, height
 
 
@@ -281,7 +630,13 @@ def validate_resize_dims(width, height):
 # that picks its own bit depth up front (`open`/`resize`/etc. all work on whatever precision an
 # already-open image happens to be), so it is the one place this DoS floor needs to vary by
 # precision rather than assuming 8-bit throughout.
-DOCUMENT_MEGAPIXEL_CAP = {'8': MAX_RESIZE_MEGAPIXELS, '16': 125, '32': 60}
+# A lowered EM_GIMP_MAX_MEGAPIXELS scales the 16/32-bit caps down with the 8-bit one, never above
+# their own defaults.
+DOCUMENT_MEGAPIXEL_CAP = {
+    '8': MAX_RESIZE_MEGAPIXELS,
+    '16': min(125, MAX_RESIZE_MEGAPIXELS / 2),
+    '32': min(60, MAX_RESIZE_MEGAPIXELS / 4),
+}
 
 
 def validate_document_dims(width, height, precision='8'):
@@ -295,14 +650,182 @@ def validate_document_dims(width, height, precision='8'):
     cap = DOCUMENT_MEGAPIXEL_CAP[precision]
     megapixels = (width * height) / 1_000_000.0
     if megapixels > cap:
-        raise ValueError('a %s-bit document must be at most %d MP' % (precision, cap))
+        raise ValueError(
+            '%s %s-bit document must be at most %g MP'
+            % ('an' if precision == '8' else 'a', precision, cap)
+        )
     return width, height
 
 
+def validate_group_total_pixels(sizes, precision='8'):
+    """A GROUP transform allocates every non-group descendant's own result buffer, so the SUM of
+    their predicted pixel counts (`sizes`: (width, height) pairs) must fit the same
+    precision-aware megapixel ceiling `validate_document_dims` applies to a single layer."""
+    cap = DOCUMENT_MEGAPIXEL_CAP[precision]
+    megapixels = sum(w * h for w, h in sizes) / 1_000_000.0
+    if megapixels > cap:
+        raise ValueError(
+            "the group's layers would total %.1f MP after this transform; the %s-bit limit is %d MP"
+            % (megapixels, precision, cap)
+        )
+
+
 def validate_feather_px(value):
     return validate_range('feather_px', value, 0.0, MAX_FEATHER_PX)
 
 
+# ---- match_layer: statistics transfer as per-channel curves ---------------------------------
+#
+# Everything here is pure (no gi). Means and standard deviations are in GIMP's own histogram
+# units (0-255 in the image's perceptual encoding, the same space a gimp:curves filter works in).
+
+MATCH_TAG = 'match_layer'
+MATCH_MODES = ('both', 'color', 'tone')
+MATCH_REFERENCES = ('surround', 'below')
+MATCH_DEFAULT_STRENGTH = 70.0
+MATCH_MIN_PIXELS = 500
+MATCH_GAIN_MIN = 0.5
+MATCH_GAIN_MAX = 2.0
+MATCH_MAX_EDGE_CONTRACT_PX = 20
+MATCH_MAX_EDGE_FEATHER_PX = 50
+MATCH_SURROUND_MIN_PX = 16
+MATCH_SURROUND_MAX_PX = 400
+# A std-dev below this (0-255 units) is treated as a flat region: its contrast ratio is
+# meaningless, so the gain stays 1 and only the mean moves.
+MATCH_FLAT_SD = 0.5
+# Spacing of the helper points that keep a clamped curve on its line (see match_curve_points).
+MATCH_CURVE_STEP = 16.0
+# Measuring runs on a copy of the layer's region scaled so its long side is at most this: means
+# and spreads survive the downscale, and growing the surround ring stays cheap at any size.
+MATCH_MEASURE_MAX_SIDE = 2048
+
+
+def default_surround_px(layer_width, layer_height):
+    """About 12% of the layer's longer side, clamped to 16..400 px."""
+    px = int(round(0.12 * max(layer_width, layer_height)))
+    return max(MATCH_SURROUND_MIN_PX, min(MATCH_SURROUND_MAX_PX, px))
+
+
+def validate_match_args(args, layer_width, layer_height):
+    """The validated, defaulted `match_layer` options as a dict:
+    match/strength/reference/surround_px/edge_contract_px/edge_feather_px. `strength` is returned
+    as a 0..1 fraction under `s` as well."""
+    match = validate_choice('match', args.get('match') or 'both', MATCH_MODES)
+    reference = validate_choice('reference', args.get('reference') or 'surround', MATCH_REFERENCES)
+    strength = args.get('strength')
+    strength = validate_range(
+        'strength', MATCH_DEFAULT_STRENGTH if strength is None else strength, 0.0, 100.0
+    )
+    surround = args.get('surround_px')
+    surround = (
+        default_surround_px(layer_width, layer_height)
+        if surround is None
+        else validate_int_range('surround_px', surround, 1, MATCH_SURROUND_MAX_PX)
+    )
+    contract = args.get('edge_contract_px')
+    contract = validate_int_range(
+        'edge_contract_px', 0 if contract is None else contract, 0, MATCH_MAX_EDGE_CONTRACT_PX
+    )
+    feather = args.get('edge_feather_px')
+    feather = validate_int_range(
+        'edge_feather_px', 0 if feather is None else feather, 0, MATCH_MAX_EDGE_FEATHER_PX
+    )
+    return {
+        'match': match, 'reference': reference, 'strength': strength, 's': strength / 100.0,
+        'surround_px': surround, 'edge_contract_px': contract, 'edge_feather_px': feather,
+    }
+
+
+def match_transfer(mu_src, sd_src, mu_ref, sd_ref, s):
+    """The Reinhard-style linear map moving the source's mean/std toward the reference's, scaled
+    by `s` (0..1): out = (in - mu_src) * gain + mu_src + shift, with
+    gain = clamp(1 + (sd_ref / sd_src - 1) * s, 0.5, 2.0) and shift = (mu_ref - mu_src) * s.
+    A flat source (or reference) keeps gain 1. Returns {gain, shift, mean_after, std_after};
+    the `_after` values ignore the 0-255 clamp of the curve."""
+    if sd_src < MATCH_FLAT_SD or sd_ref < MATCH_FLAT_SD:
+        ratio = 1.0
+    else:
+        ratio = sd_ref / sd_src
+    gain = max(MATCH_GAIN_MIN, min(MATCH_GAIN_MAX, 1.0 + (ratio - 1.0) * s))
+    shift = (mu_ref - mu_src) * s
+    return {
+        'gain': gain, 'shift': shift,
+        'mean_after': mu_src + shift, 'std_after': sd_src * gain,
+    }
+
+
+def match_curve_points(mu_src, gain, shift):
+    """The transfer map as gimp:curves [input, output] points (0-255, strictly ascending input).
+    The line y = gain * (x - mu_src) + mu_src + shift is clamped to 0..255. Unclamped it is just
+    its two endpoints (a two-point curve is exactly straight; gain 1 and shift 0 gives
+    [[0, 0], [255, 255]]). Where the line meets the clamp, a point is added there and helper
+    points every MATCH_CURVE_STEP along the sloped part: GIMP draws a smooth spline through the
+    points, and without the helpers it bows away from the line (measured: ~6 levels at the
+    middle of a clamped curve)."""
+    def y_at(x):
+        return gain * (x - mu_src) + mu_src + shift
+
+    def clamp(y):
+        return max(0.0, min(255.0, y))
+
+    y0, y1 = y_at(0.0), y_at(255.0)
+    xs = [0.0, 255.0]
+    if y0 < 0.0 or y1 > 255.0:
+        # y is strictly increasing (gain > 0): it crosses 0 once and 255 once.
+        low = 0.0 if y0 >= 0.0 else mu_src - (mu_src + shift) / gain
+        high = 255.0 if y1 <= 255.0 else mu_src + (255.0 - mu_src - shift) / gain
+        knots = [x for x in (low, high) if MATCH_CURVE_STEP / 4 < x < 255.0 - MATCH_CURVE_STEP / 4]
+        xs.extend(knots)
+        # Helpers fill the sloped part [low, high] only, kept clear of the knots.
+        x = MATCH_CURVE_STEP * (int(low // MATCH_CURVE_STEP) + 1)
+        while x < 255.0:
+            if low + MATCH_CURVE_STEP / 4 < x < high - MATCH_CURVE_STEP / 4 and x > MATCH_CURVE_STEP / 4:
+                xs.append(float(x))
+            x += MATCH_CURVE_STEP
+    xs = sorted(set(xs))
+    return [[round(x, 2), round(clamp(y_at(x)), 2)] for x in xs]
+
+
+def match_measure_scale(width, height):
+    """The factor (0 < f <= 1) a measuring copy of a `width` x `height` region is scaled by."""
+    longest = max(width, height)
+    return 1.0 if longest <= MATCH_MEASURE_MAX_SIDE else MATCH_MEASURE_MAX_SIDE / float(longest)
+
+
+def match_scaled_px(px, factor):
+    """A pixel distance on a copy scaled by `factor`, never below 1 for a non-zero distance."""
+    return 0 if px <= 0 else max(1, int(round(px * factor)))
+
+
+def match_full_res_count(count, factor):
+    """A pixel count measured on a copy scaled by `factor`, as the full-resolution count."""
+    return int(round(count / (factor * factor)))
+
+
+def histogram_scale(nick):
+    """What a Drawable.histogram mean/std must be multiplied by to read 0-255: GIMP reports them
+    in 0-255 for 8-bit precisions and in 0-1 for every higher one."""
+    return 1.0 if nick.startswith('u8') else 255.0
+
+
+def is_linear_precision(nick):
+    """Whether a GIMP precision nick ('u8-non-linear', 'float-linear', ...) stores linear light."""
+    return nick.endswith('-linear') and not nick.endswith('-non-linear')
+
+
+def match_roi(layer_x, layer_y, layer_width, layer_height, canvas_width, canvas_height, pad):
+    """The layer's box grown by `pad` and clipped to the canvas, as (x, y, width, height); None
+    when the layer's own box does not touch the canvas."""
+    if (layer_x >= canvas_width or layer_y >= canvas_height
+            or layer_x + layer_width <= 0 or layer_y + layer_height <= 0):
+        return None
+    x0 = max(0, layer_x - pad)
+    y0 = max(0, layer_y - pad)
+    x1 = min(canvas_width, layer_x + layer_width + pad)
+    y1 = min(canvas_height, layer_y + layer_height + pad)
+    return x0, y0, x1 - x0, y1 - y0
+
+
 _HEX_COLOR_RE = re.compile(r'^#[0-9a-fA-F]{6}$')
 
 # gimp_canvas's fill choices: the same white/black/transparent LAYER_FILLS a new layer gets, plus
@@ -319,6 +842,57 @@ def validate_canvas_fill(value):
     )
 
 
+def validate_hex_color(name, value):
+    """A '#rrggbb' hex color -- the same `_HEX_COLOR_RE` gimp_canvas's own fill validates against,
+    reused here so a color field never silently reaches `Gegl.Color.new` with a string it cannot
+    parse (which would otherwise fall back to black)."""
+    if not isinstance(value, str) or not _HEX_COLOR_RE.fullmatch(value):
+        raise ValueError('%s must be a "#rrggbb" hex color, got %r' % (name, value))
+    return value
+
+
+def _round_half_up(value):
+    """Round half away from zero, unlike Python's builtin `round()` (round-half-to-even:
+    `round(0.5) == 0`, `round(2.5) == 2`) -- surprising for a user-facing pixel radius, where
+    "4.5 px" should become 5, not 4."""
+    return math.floor(value + 0.5) if value >= 0 else math.ceil(value - 0.5)
+
+
+def validate_positive_px(name, value, max_px=MAX_FEATHER_PX):
+    """A strictly positive pixel radius (expand/contract/border/feather). Rounds half-up to the
+    nearest whole pixel FIRST, then refuses anything that is not strictly positive or exceeds
+    max_px -- so a value that ROUNDS to 0 (e.g. 0.3) is refused, same as an outright 0 or
+    negative, rather than silently accepted as a no-op radius."""
+    rounded = int(_round_half_up(float(value)))
+    if not 0 < rounded <= max_px:
+        raise ValueError('%s must round to a value greater than 0 and at most %s' % (name, max_px))
+    return rounded
+
+
+# load_mask's own DoS floor on a SOURCE mask image's dimensions. Checked right after
+# `Gimp.file_load` decodes the file (GIMP's Python environment has no cheap way to read a PNG/
+# JPEG header's own width/height without decoding -- GdkPixbuf is not bound in this environment),
+# so it bounds the IN-MEMORY size before the heavier work that follows (alpha compositing, scale,
+# flatten), not the decode itself. Reuses the same cap `validate_resize_dims` applies to a resize
+# target, since both are "how big a single in-memory image may get" limits.
+def validate_loaded_mask_dims(width, height):
+    return validate_resize_dims(width, height)
+
+
+def compute_mask_paste_rect(ox, oy, tw, th, img_width, img_height):
+    """Where a `tw`x`th` mask (already scaled to its target -- the whole image, or one layer's own
+    bounds, at offset `(ox, oy)`) actually lands inside the `img_width`x`img_height` canvas: the
+    intersection of [ox, ox+tw) x [oy, oy+th) with [0, img_width) x [0, img_height). Pure and
+    gi-free so the off-canvas cases (a negative offset, or a layer hanging off the right/bottom
+    edge) are unit-tested without GIMP. Returns (x0, y0, x1, y1); x1 <= x0 or y1 <= y0 means the
+    mask lands ENTIRELY off-canvas (nothing to paste -- the channel stays all-black there)."""
+    x0 = max(0, ox)
+    y0 = max(0, oy)
+    x1 = min(img_width, ox + tw)
+    y1 = min(img_height, oy + th)
+    return x0, y0, x1, y1
+
+
 # gimp_canvas's anchor grid -> the fraction of the GROWTH (new size minus old size) that lands
 # BEFORE the existing content on each axis. 0.0 pins that edge (no padding there); 1.0 puts all
 # the padding there instead; 0.5 splits it evenly. Keyed by the full 3x3 grid a Photoshop-style
@@ -350,6 +924,69 @@ def canvas_anchor_offset(anchor, old_width, old_height, new_width, new_height):
     )
 
 
+# EXIF Orientation (1-8) -> the steps that turn the stored pixels upright, in order. Each step is
+# 'cw90' / 'cw180' / 'cw270' (clockwise rotation), 'flip_h' (mirror left-right) or 'flip_v'
+# (mirror top-bottom). 1 (normal) needs none.
+EXIF_ORIENTATION_STEPS = {
+    1: (),
+    2: ('flip_h',),
+    3: ('cw180',),
+    4: ('flip_v',),
+    5: ('cw90', 'flip_h'),
+    6: ('cw90',),
+    7: ('cw90', 'flip_v'),
+    8: ('cw270',),
+}
+
+
+def parse_exif_orientation(raw):
+    """The EXIF Orientation value (1-8) from a metadata tag's raw value, or None when it is
+    missing, non-numeric or out of range -- a broken tag is ignored, never an error."""
+    try:
+        value = int(str(raw).strip())
+    except (TypeError, ValueError):
+        return None
+    return value if value in EXIF_ORIENTATION_STEPS else None
+
+
+def exif_orientation_steps(orientation):
+    """The upright-making steps for an EXIF Orientation value; () for None, 1 or anything else."""
+    return EXIF_ORIENTATION_STEPS.get(orientation, ())
+
+
+EXIF_ORIENTATION_TAG = 'Exif.Image.Orientation'
+
+
+def read_exif_orientation(metadata):
+    """The orientation (1-8) a GimpMetadata-like object carries, or None when `metadata` is None,
+    has no usable tag, or reading it raises."""
+    if metadata is None:
+        return None
+    try:
+        return parse_exif_orientation(metadata.try_get_tag_string(EXIF_ORIENTATION_TAG))
+    except Exception:
+        return None
+
+
+# Every tag a viewer may read orientation from; the EXIF one is the one this bridge applies.
+ORIENTATION_TAGS = (EXIF_ORIENTATION_TAG, 'Xmp.tiff.Orientation', 'Exif.Thumbnail.Orientation')
+
+
+def clear_exif_orientation(metadata):
+    """Removes the orientation tags from `metadata` (absent reads as normal); True when the EXIF
+    one was cleared. Clearing is used rather than writing 1: GIMP's metadata object can silently
+    ignore a write of that tag while still reporting success."""
+    cleared = False
+    for tag in ORIENTATION_TAGS:
+        try:
+            ok = bool(metadata.try_clear_tag(tag))
+        except Exception:
+            ok = False
+        if tag == EXIF_ORIENTATION_TAG:
+            cleared = ok
+    return cleared
+
+
 def pct_to_unit(name, value, lo=-100.0, hi=100.0):
     """User-facing -100..100 (or a narrower lo..hi) percent-like value -> the -1..1 unit
     GEGL/GIMP properties in this family use."""
@@ -492,10 +1129,18 @@ def build_saturation_params(args, defaults):
     }
 
 
+# gegl:vibrance's own -100..100 is far stronger than the Photoshop scale callers expect:
+# on a marina photo its +15 sent 38% of pixels to red 0, where Photoshop's +15 added about 0.014
+# mean saturation and clipped nothing. Dividing by this factor lines the two up (Photoshop +15 and
+# +50 match gegl about 0.5 and 2.0 on that photo), so the field keeps a Photoshop-like -100..100.
+VIBRANCE_GEGL_DIVISOR = 25.0
+
+
 def build_vibrance_params(args, defaults):
     return {
         'vibrance': resolve_field(
-            args, 'vibrance', defaults, 'vibrance', lambda v: validate_range('vibrance', v, -100.0, 100.0)
+            args, 'vibrance', defaults, 'vibrance',
+            lambda v: validate_range('vibrance', v, -100.0, 100.0) / VIBRANCE_GEGL_DIVISOR,
         ),
         'saturation': resolve_field(
             args, 'saturation', defaults, 'saturation', lambda v: validate_range('saturation', v, 0.0, 10.0)
@@ -609,13 +1254,35 @@ EFFECT_OPERATIONS = {
     'lens_blur': 'gegl:focus-blur',
     'add_noise': 'gegl:noise-rgb',
     'drop_shadow': 'gegl:dropshadow',
+    # outline and outer_glow are also gegl:dropshadow (zero offset, grown by grow-radius): one
+    # operation, three types -- the ledger's `type` tells them apart, see OPERATION_TYPES below.
+    'outline': 'gegl:dropshadow',
+    'outer_glow': 'gegl:dropshadow',
+    'surface_blur': 'gegl:bilateral-filter',
 }
 
 # The inverse of ADJUST_OPERATIONS and EFFECT_OPERATIONS together, for a ledger record written
 # without a `type` field -- one shared map, since `op_list_filters` looks a record's operation up
-# here regardless of which tool (gimp_add_adjustment or gimp_add_effect) created it.
+# here regardless of which tool (gimp_add_adjustment or gimp_add_effect) created it. Where several
+# types share one operation (gegl:dropshadow), the first listed wins: a record with no `type` is
+# from before outline/outer_glow existed, so it can only be a drop_shadow. THAT DEPENDS ON
+# INSERTION ORDER: `setdefault` keeps whichever type reached the map first, so 'drop_shadow' must
+# stay listed above 'outline' and 'outer_glow' in EFFECT_OPERATIONS (test_lib.py pins it).
 OPERATION_TYPES = {operation: type_ for type_, operation in ADJUST_OPERATIONS.items()}
-OPERATION_TYPES.update({operation: type_ for type_, operation in EFFECT_OPERATIONS.items()})
+for _type, _operation in EFFECT_OPERATIONS.items():
+    OPERATION_TYPES.setdefault(_operation, _type)
+del _type, _operation
+
+
+def record_type(rec):
+    """The tool `type` of a ledger filter record: its stored `type`, or -- for a record written
+    before `type` was stored -- the type its operation implies (`OPERATION_TYPES`). None for an
+    operation neither tool owns. The one place both the filter listing and the effect re-edit
+    type guard resolve a record's type, so a typeless legacy gegl:dropshadow reads as drop_shadow
+    in both."""
+    if not isinstance(rec, dict):
+        return None
+    return rec.get('type') or OPERATION_TYPES.get(rec.get('operation'))
 
 # Every validate_range/validate_int_range call below uses `val`, not `v`, as its lambda's
 # parameter name -- deliberately, so it is NOT matched by gimp-adjustment-tools.test.ts's own
@@ -770,6 +1437,79 @@ def build_drop_shadow_params(args, defaults):
     }
 
 
+def build_outline_params(args, defaults):
+    # A solid ring around the layer's alpha: gegl:dropshadow with no offset and no blur, grown by
+    # `width` px (grow-radius, a circle) at full opacity. Only `grow-radius` and `color` are
+    # recorded; `_set_drop_shadow` fills the rest in (offset 0, blur 0, opacity 1). The shadow is
+    # drawn under the layer's own pixels, so the interior is untouched.
+    #
+    # GEGL allows grow-radius up to 100, but its cost grows linearly with the radius times the
+    # pixel count. Measured live (GIMP 3.2.6, a 6000x4000 = 24 MP layer, full export incl. a ~1 s
+    # baseline export with no filter): width 6 -> 4 s, 50 -> 18.5 s, 100 -> 39.5 s; outer_glow at
+    # radius 250 with spread 50 -> 17.7 s, spread 100 -> 30.6 s. Width and spread stop at 50, the
+    # same ~20 s worst case on 24 MP as SURFACE_BLUR_MAX_RADIUS.
+    return {
+        'grow-radius': resolve_field(
+            args, 'width', defaults, 'grow-radius', lambda val: validate_range('width', val, 1.0, 50.0)
+        ),
+        'color': resolve_field(
+            args, 'color', defaults, 'color', lambda val: validate_hex_color('color', val)
+        ),
+    }
+
+
+def build_outer_glow_params(args, defaults):
+    # The same gegl:dropshadow, centered (no offset, filled in by `_set_drop_shadow`): `spread`
+    # grows the glow's solid core, `radius` blurs it.
+    return {
+        'radius': resolve_field(
+            args, 'radius', defaults, 'radius', lambda val: validate_range('radius', val, 1.0, 250.0)
+        ),
+        'grow-radius': resolve_field(
+            args, 'spread', defaults, 'grow-radius',
+            lambda val: validate_range('spread', val, 0.0, 50.0),
+        ),
+        'opacity': resolve_field(
+            args, 'opacity', defaults, 'opacity', lambda val: validate_range('opacity', val, 0.0, 1.0)
+        ),
+        'color': resolve_field(
+            args, 'color', defaults, 'color', lambda val: validate_hex_color('color', val)
+        ),
+    }
+
+
+# gegl:bilateral-filter's `edge-preservation` runs 0..100 (default 8), where HIGHER keeps more of
+# the original, edges and noise alike -- probed live on a noisy patch beside a hard edge: 0 smooths
+# hard enough to blur the edge itself, 8 flattens the noise (stddev 17 -> 2) with the edge intact,
+# 100 barely smooths. The tool exposes it as 0..1 (this factor times the tool value).
+# gegl:mean-curvature-blur and gegl:snn-mean were not needed: GIMP attaches bilateral-filter fine.
+BILATERAL_EDGE_SCALE = 100.0
+
+
+# gegl:bilateral-filter's cost grows with the SQUARE of the radius times the pixel count. Measured
+# live (GIMP 3.2.6, this dev box, a noisy 6016x4000 = 24 MP layer; full export incl. a ~2 s
+# baseline export with no filter): radius 5 -> 12 s, 6 -> 17 s, 7 -> 23 s, 8 -> 28 s, 10 -> 41 s;
+# radius 25 and 50 were not finished inside a 400 s timeout (extrapolating the r^2 trend: ~4 and
+# ~16 minutes). The tool's ~20 s worst case on 24 MP therefore stops at radius 6, and the remote
+# box is slower still. A smaller image has headroom (cost scales with pixels) but the cap is a flat
+# per-filter number: it does not look at the layer. TS schema, EFFECT_TRANSFORM_BOUNDS and this
+# builder share it.
+SURFACE_BLUR_MAX_RADIUS = 6.0
+
+
+def build_surface_blur_params(args, defaults):
+    return {
+        'blur-radius': resolve_field(
+            args, 'radius', defaults, 'blur-radius',
+            lambda val: validate_range('radius', val, 1.0, SURFACE_BLUR_MAX_RADIUS),
+        ),
+        'edge-preservation': resolve_field(
+            args, 'edge_preservation', defaults, 'edge-preservation',
+            lambda val: validate_range('edge_preservation', val, 0.0, 1.0),
+        ),
+    }
+
+
 EFFECT_PARAM_BUILDERS = {
     'vignette': build_vignette_params,
     'black_white': build_black_white_params,
@@ -777,6 +1517,9 @@ EFFECT_PARAM_BUILDERS = {
     'lens_blur': build_lens_blur_params,
     'add_noise': build_add_noise_params,
     'drop_shadow': build_drop_shadow_params,
+    'outline': build_outline_params,
+    'outer_glow': build_outer_glow_params,
+    'surface_blur': build_surface_blur_params,
 }
 
 # Creation-time defaults, already in GEGL-property units -- probed live via `describe_operation`
@@ -790,6 +1533,9 @@ EFFECT_CREATE_DEFAULTS = {
     'lens_blur': {'blur-radius': 25.0, 'highlight-factor': 0.0},
     'add_noise': {'red': 0.2, 'green': 0.2, 'blue': 0.2, 'alpha': 0.0, 'seed': 0},
     'drop_shadow': {'x': 20.0, 'y': 20.0, 'radius': 10.0, 'opacity': 0.5},
+    'outline': {'grow-radius': 4.0, 'color': '#000000'},
+    'outer_glow': {'radius': 20.0, 'grow-radius': 4.0, 'opacity': 0.75, 'color': '#ffffff'},
+    'surface_blur': {'blur-radius': 4.0, 'edge-preservation': 0.08},
 }
 
 
@@ -846,7 +1592,7 @@ USER_FIELDS = {
     ),
     'saturation': (('scale', 'scale', _same),),
     'vibrance': (
-        ('vibrance', 'vibrance', _same),
+        ('vibrance', 'vibrance', _scaled(VIBRANCE_GEGL_DIVISOR)),
         ('saturation', 'saturation', _same),
     ),
     'sharpen': (
@@ -889,6 +1635,20 @@ USER_FIELDS = {
         ('radius', 'radius', _same),
         ('opacity', 'opacity', _same),
     ),
+    'outline': (
+        ('width', 'grow-radius', _same),
+        ('color', 'color', _same),
+    ),
+    'outer_glow': (
+        ('spread', 'grow-radius', _same),
+        ('radius', 'radius', _same),
+        ('opacity', 'opacity', _same),
+        ('color', 'color', _same),
+    ),
+    'surface_blur': (
+        ('radius', 'blur-radius', _same),
+        ('edge_preservation', 'edge-preservation', _same),
+    ),
 }
 
 CURVES_USER_FIELDS = ('channel', 'points')
@@ -975,7 +1735,6 @@ def json_safe(value):
 # operations this engine actually uses.
 ALLOWED_DESCRIBE_OPERATIONS = frozenset(ADJUST_OPERATIONS.values()) | frozenset(EFFECT_OPERATIONS.values())
 
-
 # ---- geometry-op masked-filter detection (pure logic; ops.py supplies the live GIMP state) -----
 
 
@@ -1208,7 +1967,7 @@ def flip_effect_params(operation, params, orientation):
         else:
             params['angle'] = _round_transform_value(_wrap_angle_deg(-params['angle']))
         return params
-    if operation == 'gegl:dropshadow':
+    if operation == 'gegl:dropshadow' and 'x' in params:  # outline / outer_glow have no offset
         params = dict(params)
         if orientation == 'horizontal':
             params['x'] = _round_transform_value(-params['x'])
@@ -1245,7 +2004,7 @@ def rotate_effect_params(operation, params, degrees, layer_width, layer_height):
         canonical_degrees = _right_angle_k(degrees) * 90.0
         params['angle'] = _round_transform_value(_wrap_angle_deg(params['angle'] + canonical_degrees))
         return params
-    if operation == 'gegl:dropshadow':
+    if operation == 'gegl:dropshadow' and 'x' in params:
         params = dict(params)
         cos_t, sin_t = _right_angle_cos_sin(degrees)
         dx, dy = params['x'], params['y']
@@ -1295,9 +2054,18 @@ def resize_effect_params(operation, params, scale_x, scale_y):
     if operation == 'gegl:dropshadow':
         params = dict(params)
         isotropic_scale = math.sqrt(scale_x * scale_y)
-        params['x'] = _round_transform_value(params['x'] * scale_x)
-        params['y'] = _round_transform_value(params['y'] * scale_y)
-        params['radius'] = _round_transform_value(params['radius'] * isotropic_scale)
+        # outline has only grow-radius, outer_glow lacks the offset: scale what is recorded.
+        for prop, factor in (
+            ('x', scale_x), ('y', scale_y), ('radius', isotropic_scale),
+            ('grow-radius', isotropic_scale),
+        ):
+            if prop in params:
+                params[prop] = _round_transform_value(params[prop] * factor)
+        return params
+    if operation == 'gegl:bilateral-filter':
+        params = dict(params)
+        isotropic_scale = math.sqrt(scale_x * scale_y)
+        params['blur-radius'] = _round_transform_value(params['blur-radius'] * isotropic_scale)
         return params
     return params
 
@@ -1311,7 +2079,12 @@ EFFECT_TRANSFORM_BOUNDS = {
     'gegl:vignette': {'x': (0.0, 1.0), 'y': (0.0, 1.0)},
     'gegl:motion-blur-linear': {'length': (0.0, 1000.0), 'angle': (-180.0, 180.0)},
     'gegl:focus-blur': {'blur-radius': (0.0, 150.0)},
-    'gegl:dropshadow': {'x': (-500.0, 500.0), 'y': (-500.0, 500.0), 'radius': (0.0, 1500.0)},
+    'gegl:dropshadow': {
+        'x': (-500.0, 500.0), 'y': (-500.0, 500.0), 'radius': (0.0, 1500.0),
+        # outline's width and outer_glow's spread share a cap (see build_outline_params).
+        'grow-radius': (0.0, 50.0),
+    },
+    'gegl:bilateral-filter': {'blur-radius': (0.0, SURFACE_BLUR_MAX_RADIUS)},
 }
 
 # The user-facing (gimp_add_effect) field name for each EFFECT_TRANSFORM_BOUNDS entry -- so a
@@ -1328,10 +2101,44 @@ EFFECT_TRANSFORM_FIELD_NAMES = {
     ('gegl:dropshadow', 'x'): 'offset_x',
     ('gegl:dropshadow', 'y'): 'offset_y',
     ('gegl:dropshadow', 'radius'): 'radius',
+    ('gegl:dropshadow', 'grow-radius'): 'width/spread',
+    ('gegl:bilateral-filter', 'blur-radius'): 'radius',
 }
 
 
-def validate_effect_transform(op_name, operation, filter_name, new_params):
+# Per-type floors a re-edit enforces above EFFECT_TRANSFORM_BOUNDS' own lower bound (those are
+# per operation, and gegl:dropshadow serves three types): shrinking resize would otherwise store a
+# value a re-edit of the same filter refuses. A resize that bottoms out is clamped to the floor
+# (the 1 px minimum the effect itself allows) instead of refused: the filter is still valid, only
+# no thinner than the tool can express.
+EFFECT_TRANSFORM_FLOORS = {
+    ('outline', 'grow-radius'): 1.0,
+    ('outer_glow', 'radius'): 1.0,
+    ('surface_blur', 'blur-radius'): 1.0,
+}
+
+
+# Per-type ceilings a re-edit enforces below EFFECT_TRANSFORM_BOUNDS' own upper bound: outer_glow
+# shares gegl:dropshadow (radius up to 1500) but its own builder caps radius at 250, so a growing
+# resize would otherwise store a radius a re-edit of the same glow refuses. Unlike a floor, a
+# value past a ceiling is refused, the same as any other out-of-range transform.
+EFFECT_TRANSFORM_CEILINGS = {
+    ('outer_glow', 'radius'): 250.0,
+}
+
+
+def clamp_effect_transform(type_, new_params):
+    """`new_params` with every EFFECT_TRANSFORM_FLOORS entry for `type_` applied (the same dict
+    when nothing needed clamping, so callers' `==` change check stays honest)."""
+    clamped = None
+    for (floor_type, prop), floor in EFFECT_TRANSFORM_FLOORS.items():
+        if floor_type == type_ and prop in new_params and new_params[prop] < floor:
+            clamped = clamped if clamped is not None else dict(new_params)
+            clamped[prop] = floor
+    return new_params if clamped is None else clamped
+
+
+def validate_effect_transform(op_name, operation, filter_name, new_params, type_=None):
     """Refuse `op_name` (the geometry op about to run) outright if any of `new_params` -- already
     computed for `operation` by flip_effect_params/rotate_effect_params/resize_effect_params --
     would leave the range its own create/re-edit path enforces. Called BEFORE the geometry
@@ -1339,10 +2146,12 @@ def validate_effect_transform(op_name, operation, filter_name, new_params):
     range never gets a chance to silently clamp via GObject's own property setter instead of a
     clear, actionable refusal -- and the geometry op never partially applies. Names the filter
     (`filter_name`, the same way `_refuse_if_masked_filters` does) and the field in gimp_add_
-    effect's OWN terms (`EFFECT_TRANSFORM_FIELD_NAMES`), not the raw GEGL property name."""
+    effect's OWN terms (`EFFECT_TRANSFORM_FIELD_NAMES`), not the raw GEGL property name. `type_`
+    (the record's effect type) adds that type's EFFECT_TRANSFORM_CEILINGS."""
     for prop, (lo, hi) in EFFECT_TRANSFORM_BOUNDS.get(operation, {}).items():
         if prop not in new_params:
             continue
+        hi = min(hi, EFFECT_TRANSFORM_CEILINGS.get((type_, prop), hi))
         value = new_params[prop]
         if not lo <= value <= hi:
             field = EFFECT_TRANSFORM_FIELD_NAMES.get((operation, prop), prop)
@@ -1358,6 +2167,155 @@ def validate_effect_transform(op_name, operation, filter_name, new_params):
             )
 
 
+
+# ---- gimp_transform_layer: pure geometry math (fit/fill scale, matrix composition, bounds) ----
+#
+# A layer-level affine transform (scale/rotate/skew/free), distinct from the whole-CANVAS
+# geometry ops above and from the direction/position-dependent EFFECT param remapping above.
+# `Item.transform_matrix` (ops.py) applies the given 3x3 matrix directly in ABSOLUTE
+# document-pixel coordinates -- verified live (GIMP 3.2.6): a matrix built by
+# `compose_layer_matrix` below, applied to a layer at a known offset, moved it to exactly the
+# bounding box this module's own `transformed_bounds` predicts for the same matrix and corners
+# (within floating-point rounding). So every matrix built here already carries whatever
+# translation is needed to anchor the transform at the layer's own center; there is no separate
+# "local" coordinate frame to convert into or out of first.
+
+
+def fit_scale_fraction(layer_width, layer_height, canvas_width, canvas_height, mode):
+    """The uniform scale fraction (1.0 = 100%) that makes a `layer_width` x `layer_height`
+    rectangle fit inside (mode='fit', letterbox -- the SMALLER of the two axis ratios) or fill
+    (mode='fill', cover -- the LARGER) a `canvas_width` x `canvas_height` canvas, preserving
+    aspect. `op_transform_layer`'s `fit` scales by this fraction and centers the result; fitting
+    an already-fitted layer computes a fraction of 1.0, a no-op scale -- what makes that op
+    idempotent."""
+    if mode not in ('fit', 'fill'):
+        raise ValueError("mode must be one of 'fit', 'fill'")
+    width_ratio = canvas_width / float(layer_width)
+    height_ratio = canvas_height / float(layer_height)
+    return min(width_ratio, height_ratio) if mode == 'fit' else max(width_ratio, height_ratio)
+
+
+def _mat_mul(a, b):
+    """3x3 matrix product, both `a` and `b` flat row-major 9-lists (the same layout
+    `Item.transform_matrix`'s own 9 positional args use), applied to a column vector [x,y,1] as
+    p' = a*(b*p) -- `b` is the transform applied FIRST."""
+    return [
+        a[0] * b[0] + a[1] * b[3] + a[2] * b[6],
+        a[0] * b[1] + a[1] * b[4] + a[2] * b[7],
+        a[0] * b[2] + a[1] * b[5] + a[2] * b[8],
+        a[3] * b[0] + a[4] * b[3] + a[5] * b[6],
+        a[3] * b[1] + a[4] * b[4] + a[5] * b[7],
+        a[3] * b[2] + a[4] * b[5] + a[5] * b[8],
+        a[6] * b[0] + a[7] * b[3] + a[8] * b[6],
+        a[6] * b[1] + a[7] * b[4] + a[8] * b[7],
+        a[6] * b[2] + a[7] * b[5] + a[8] * b[8],
+    ]
+
+
+def _mat_translate(tx, ty):
+    return [1.0, 0.0, tx, 0.0, 1.0, ty, 0.0, 0.0, 1.0]
+
+
+def _mat_scale(sx, sy):
+    return [sx, 0.0, 0.0, 0.0, sy, 0.0, 0.0, 0.0, 1.0]
+
+
+def _mat_rotate(degrees):
+    theta = math.radians(degrees)
+    cos_t, sin_t = math.cos(theta), math.sin(theta)
+    return [cos_t, -sin_t, 0.0, sin_t, cos_t, 0.0, 0.0, 0.0, 1.0]
+
+
+def _mat_shear_h(skew_h_degrees):
+    """A pure horizontal shear: x' = x - tan(skew_h_degrees)*y, y' = y -- determinant exactly 1
+    for any angle. Positive `skew_h_degrees` slants the top edge right (a point above center,
+    smaller y, moves toward +x) -- the convention `gimp_transform_layer`'s own schema documents,
+    and the one `ps_transform_layer`'s op=skew uses."""
+    return [1.0, -math.tan(math.radians(skew_h_degrees)), 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0]
+
+
+def _mat_shear_v(skew_v_degrees):
+    """A pure vertical shear: x' = x, y' = -tan(skew_v_degrees)*x + y -- determinant exactly 1
+    for any angle. Positive `skew_v_degrees` slants the left edge down (a point left of center,
+    smaller x, moves toward +y)."""
+    return [1.0, 0.0, 0.0, -math.tan(math.radians(skew_v_degrees)), 1.0, 0.0, 0.0, 0.0, 1.0]
+
+
+def _mat_determinant(m):
+    """The determinant of `m`'s linear (non-translation) 2x2 part -- the translation column
+    (indices 2, 5) never affects it. Zero means the transform collapses the rectangle to a line
+    or a point; negative means it mirrors (flips handedness) rather than purely scaling/
+    rotating/shearing it."""
+    return m[0] * m[4] - m[1] * m[3]
+
+
+# A composed matrix below this |determinant| is treated the same as an exact 0: numerically
+# indistinguishable from a transform that collapses the layer to a line, so refused outright
+# rather than handed to `Item.transform_matrix` to silently produce a degenerate result.
+TRANSFORM_LAYER_MIN_DETERMINANT = 1e-6
+
+
+def compose_layer_matrix(cx, cy, scale_x_percent, scale_y_percent, degrees,
+                          skew_h_degrees, skew_v_degrees, offset_x, offset_y):
+    """The 9 row-major coefficients for `Item.transform_matrix`: a scale (percent, 100 =
+    unchanged), then a skew (skew_h_degrees/skew_v_degrees, composed as two independent real
+    shears -- Sh_v . Sh_h, each with its OWN determinant of exactly 1, so the composed skew's
+    determinant is always exactly 1 too, for any angle), then a rotation (degrees, clockwise),
+    all anchored at the layer's own center (`cx`, `cy`, document pixels), followed by an absolute
+    translation (`offset_x`, `offset_y`). Never the single combined-shear matrix
+    [[1,-tan(h)],[-tan(v),1]] -- that matrix's OWN determinant is `1 - tan(h)*tan(v)`, which
+    reaches exactly 0 at h=v=45 (collapsing the rectangle to a line) and goes NEGATIVE past that
+    (silently mirroring it instead of shearing it). `op_transform_layer`'s `free` op calls this
+    directly (scale + degrees + offset, no skew); `skew` calls it with scale 100/100, degrees 0,
+    offset 0/0; `rotate`'s own bounds check (not its actual transform, which goes through
+    `Item.transform_rotate` instead -- see ops.py) reuses it with scale 100/100, skew 0/0, offset
+    0/0 purely to predict the post-rotation bounding box via `transformed_bounds`.
+
+    Raises if the FINAL composed matrix's determinant is below `TRANSFORM_LAYER_MIN_DETERMINANT`
+    or negative -- scale alone is already bounded away from both by its own 1..10000% range, but
+    this is the belt-and-braces check against the composed result as a whole, not just its own
+    skew component."""
+    m = _mat_translate(-cx, -cy)
+    m = _mat_mul(_mat_scale(scale_x_percent / 100.0, scale_y_percent / 100.0), m)
+    m = _mat_mul(_mat_shear_v(skew_v_degrees), _mat_mul(_mat_shear_h(skew_h_degrees), m))
+    m = _mat_mul(_mat_rotate(degrees), m)
+    m = _mat_mul(_mat_translate(cx, cy), m)
+    m = _mat_mul(_mat_translate(offset_x, offset_y), m)
+    det = _mat_determinant(m)
+    if not math.isfinite(det) or det < 0 or abs(det) < TRANSFORM_LAYER_MIN_DETERMINANT:
+        raise ValueError(
+            'this combination of scale/skew/rotate collapses or mirrors the layer (determinant '
+            '%.6g) instead of transforming it -- reduce the scale or skew and try again' % det
+        )
+    return m
+
+
+def transformed_bounds(matrix, x, y, width, height):
+    """The axis-aligned bounding box of a `width` x `height` rectangle at document-pixel origin
+    (`x`, `y`), after mapping each of its four corners through `matrix` (9 row-major
+    coefficients, `Item.transform_matrix`'s own layout) -- what the transformed layer's new
+    offsets/width/height will measure to. Used to validate a rotate/skew/free transform against
+    the same size cap `validate_resize_dims` enforces, BEFORE any pixel actually moves. Returns
+    (new_x, new_y, new_width, new_height)."""
+    corners = ((x, y), (x + width, y), (x, y + height), (x + width, y + height))
+    xs = [matrix[0] * cx + matrix[1] * cy + matrix[2] for cx, cy in corners]
+    ys = [matrix[3] * cx + matrix[4] * cy + matrix[5] for cx, cy in corners]
+    min_x, max_x = min(xs), max(xs)
+    min_y, max_y = min(ys), max(ys)
+    return min_x, min_y, max_x - min_x, max_y - min_y
+
+
+def validate_transformed_layer_size(width, height):
+    """Refuses a scale/fit whose rounded target is under 1px in either dimension. Without this
+    GIMP is handed a zero-size rectangle, returns nothing, and the caller reports a misleading
+    "lock-position or lock-content" failure for a layer that was never locked."""
+    if width < 1 or height < 1:
+        raise ValueError(
+            'the transform would shrink the layer to %dx%d px after rounding; use a larger scale'
+            % (width, height)
+        )
+
+
 def region_to_proxy_px(region, scale):
     """Map a document-pixel `region` dict into proxy-pixel integer bounds at the proxy's
     `scale` factor (0 < scale <= 1). Returns (x, y, width, height); width/height are at least
@@ -1370,6 +2328,13 @@ def region_to_proxy_px(region, scale):
     return x, y, w, h
 
 
+def visible_image_ids(all_ids, hidden_ids):
+    """The ids in `all_ids` that are real documents: every id in `hidden_ids` (the bridge's own
+    preview-proxy images, which are live GIMP images but not the user's) is dropped, order kept."""
+    hidden = set(hidden_ids)
+    return [i for i in all_ids if i not in hidden]
+
+
 def read_pgm(raw):
     """Decode minimal binary PGM (P5, maxval 255) bytes. Returns (width, height, data).
 
@@ -1506,10 +2471,10 @@ def parse_ledger(raw):
       parasite bytes ARE the filters map directly (no wrapper). Treated as
       v1-compatible so files written before the ledger was versioned keep
       working.
-    - Versioned + "v" == LEDGER_VERSION: "filters" is the map; any OTHER
+    - Versioned + "v" in 1..LEDGER_VERSION: "filters" is the map; any OTHER
       top-level key is returned as `unknown_top_level` so a future writer's
       extra fields round-trip untouched through serialize_ledger.
-    - Versioned + "v" != LEDGER_VERSION (in practice: greater, from a future
+    - Versioned + "v" outside that range (in practice: greater, from a future
       writer): every filter is treated as absent — the caller falls back to
       readback for all of them, per the documented contract that we never
       guess at a schema we don't recognize. `unknown_top_level` still
@@ -1545,7 +2510,7 @@ def parse_ledger(raw):
         return _validate_filters(raw_filters), {}, raw_filters
     unknown = {k: v for k, v in doc.items() if k not in ('v', 'writer', 'filters')}
     raw_filters = dict(doc['filters'])
-    if doc['v'] != LEDGER_VERSION:
+    if not 1 <= doc['v'] <= LEDGER_VERSION:
         return {}, unknown, raw_filters
     return _validate_filters(raw_filters), unknown, raw_filters
 
@@ -1593,12 +2558,19 @@ def ledger_is_newer_version(raw):
     return doc['v'] > LEDGER_VERSION
 
 
+def ledger_write_version(filters_by_name):
+    """The lowest ledger version that holds every record in `filters_by_name` (see LEDGER_VERSION)."""
+    if any(record_type(rec) in LEDGER_V2_TYPES for rec in filters_by_name.values()):
+        return 2
+    return 1
+
+
 def serialize_ledger(filters_by_name, unknown_top_level=None):
-    """Serialize filters_by_name as the current-version ledger, preserving any
+    """Serialize filters_by_name as a ledger at `ledger_write_version`, preserving any
     unknown_top_level keys carried over from parse_ledger byte-for-byte
     (as JSON values -- not literal bytes, but nothing under them is rewritten)."""
     doc = dict(unknown_top_level or {})
-    doc['v'] = LEDGER_VERSION
+    doc['v'] = ledger_write_version(filters_by_name)
     doc['writer'] = LEDGER_WRITER
     doc['filters'] = filters_by_name
     return json.dumps(doc)
@@ -1688,13 +2660,16 @@ def list_requests(rpc_dir):
     return [name for _req_id, name in numbered]
 
 
-def read_request(req_path, attempts=5, delay_s=0.02, on_retry=None):
+def read_request(req_path, attempts=8, delay_s=0.02, max_delay_s=0.25, on_retry=None):
     """Read + parse a request file. Retries ONLY on OSError (e.g. a
     PermissionError from anti-virus or a file indexer holding a brief lock on
     a just-renamed file on Windows) -- a JSONDecodeError means the content
     itself is bad and is raised immediately; retrying that would just mask a
     genuinely malformed file rather than a transient lock.
 
+    The wait doubles from `delay_s` up to `max_delay_s`, about 1s in all at the defaults, since a Windows
+    file lock can outlast 100ms.
+
     `on_retry(exc, attempt)`, if given, is called right before each sleep --
     the bridge logs the exception type through it; tests can assert on it
     without capturing stderr."""
@@ -1707,9 +2682,11 @@ def read_request(req_path, attempts=5, delay_s=0.02, on_retry=None):
             raise
         except OSError as e:
             last_err = e
+            if attempt == attempts - 1:
+                break
             if on_retry:
                 on_retry(e, attempt)
-            time.sleep(delay_s)
+            time.sleep(min(delay_s * (2 ** attempt), max_delay_s))
     raise last_err
 
 
@@ -1986,3 +2963,790 @@ def metadata_strip_settings(fmt, prop_names):
     if fmt == 'tiff' and 'save-geotiff' in names:
         settings.append('save-geotiff')
     return settings
+
+
+def profile_is_editors_own(texts):
+    """Whether a color profile is the editor's built-in one, from its description, manufacturer,
+    model and copyright strings (None for an image that has no profile of its own, i.e. the
+    built-in one). Exports leave such a profile out: the file is then plain untagged sRGB, which
+    every viewer assumes anyway, and the profile's name ("GIMP built-in sRGB") would otherwise ride
+    along in every file. A camera's or phone's own profile is kept, unless the editor itself
+    rewrote it (a precision or mode conversion marks the variant it makes with its own name);
+    such a file is exported untagged too."""
+    if texts is None:
+        return True
+    return any('gimp' in (t or '').lower() for t in texts)
+
+
+PSD_ICC_RESOURCE = 1039
+
+
+def psd_resources_without(section, resource_id):
+    """A PSD image-resource section (the bytes after its 4-byte length) with every block of
+    `resource_id` removed. Each block: '8BIM', a 2-byte id, a Pascal name padded to even length,
+    a 4-byte size, then the data padded to even length. Raises ValueError on a malformed section."""
+    out = bytearray()
+    at = 0
+    while at < len(section):
+        start = at
+        if section[at:at + 4] != b'8BIM' or at + 7 > len(section):
+            raise ValueError('malformed PSD image resource at %d' % at)
+        rid = int.from_bytes(section[at + 4:at + 6], 'big')
+        at += 6
+        at += 1 + section[at]
+        at += at % 2
+        if at + 4 > len(section):
+            raise ValueError('malformed PSD image resource at %d' % start)
+        size = int.from_bytes(section[at:at + 4], 'big')
+        at += 4 + size + size % 2
+        if at > len(section):
+            raise ValueError('malformed PSD image resource at %d' % start)
+        if rid != resource_id:
+            out += section[start:at]
+    return bytes(out)
+
+
+def layered_bake_plan(nodes):
+    """Which layers a layered (.psd) export must flatten its live filters into first.
+
+    `nodes` is `(layer_id, parent_id, is_group, has_filters)` per layer in `_all_layers` order
+    (a group before its children; `parent_id` None at top level). Returns `(merge_groups,
+    bake_layers)`: a group carrying a live filter is merged whole into one raster layer, since the
+    PSD exporter drops a group's own filter (verified live, GIMP 3.2.6) and merging is the only
+    way to keep its look; everything inside it is absorbed by that merge. Any other layer with
+    filters is baked in place, keeping its own mask, mode and opacity."""
+    absorbed = set()
+    merge_groups, bake_layers = [], []
+    for layer_id, parent_id, is_group, has_filters in nodes:
+        if parent_id is not None and parent_id in absorbed:
+            absorbed.add(layer_id)
+        elif is_group and has_filters:
+            merge_groups.append(layer_id)
+            absorbed.add(layer_id)
+        elif has_filters:
+            bake_layers.append(layer_id)
+    return merge_groups, bake_layers
+
+
+# ---- text layers (gimp_text) -----------------------------------------------------------------
+
+TEXT_MAX_CHARS = 2000
+TEXT_MIN_FONT_PT = 1
+TEXT_MAX_FONT_PT = 1296
+TEXT_DEFAULT_FONT_PT = 24
+TEXT_FONT_LIST_CAP = 200
+FONT_SUGGESTION_LIMIT = 8
+DEFAULT_TEXT_FONT = 'Sans-serif'
+DEFAULT_RESOLUTION_PPI = 72.0
+
+# gimp_text's `alignment` enum is ps_text's. GIMP's own justification has only left / right /
+# center / fill, so the three "last line" variants Photoshop adds are refused rather than
+# approximated.
+TEXT_ALIGNMENTS = {'LEFT': 'left', 'CENTER': 'center', 'RIGHT': 'right', 'FULLYJUSTIFIED': 'fill'}
+TEXT_UNSUPPORTED_ALIGNMENTS = ('LEFTJUSTIFIED', 'CENTERJUSTIFIED', 'RIGHTJUSTIFIED')
+_JUSTIFICATION_TO_ALIGNMENT = {nick: name for name, nick in TEXT_ALIGNMENTS.items()}
+
+# Words that describe a face of a family rather than the family itself, used to tell "Arial" +
+# "Narrow Bold" (a face of the family) from an unrelated font whose name merely starts the same.
+_FONT_STYLE_WORDS = frozenset((
+    'regular', 'book', 'roman', 'normal', 'medium', 'bold', 'italic', 'oblique', 'light', 'thin',
+    'extralight', 'ultralight', 'semilight', 'semibold', 'demibold', 'extrabold', 'ultrabold',
+    'black', 'heavy', 'condensed', 'semicondensed', 'extracondensed', 'narrow', 'cond', 'expanded',
+    'semiexpanded', 'extra', 'ultra', 'semi', 'demi', 'variable',
+))
+_FONT_REGULAR_ORDER = ('regular', 'book', 'roman', 'normal', 'medium')
+
+
+def validate_text_content(value):
+    if not isinstance(value, str):
+        raise ValueError('text must be a string')
+    if value == '':
+        raise ValueError('text must not be empty')
+    if len(value) > TEXT_MAX_CHARS:
+        raise ValueError('text must be at most %d characters (got %d)' % (TEXT_MAX_CHARS, len(value)))
+    return value
+
+
+def validate_font_size_pt(value):
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ValueError('font_size must be a number')
+    return validate_range('font_size', value, TEXT_MIN_FONT_PT, TEXT_MAX_FONT_PT)
+
+
+def validate_text_rgb(args):
+    """(r, g, b) ints 0..255 from `red`/`green`/`blue`, or None when none of the three is given.
+    Giving only some of them is refused rather than guessing the rest."""
+    given = [k for k in ('red', 'green', 'blue') if args.get(k) is not None]
+    if not given:
+        return None
+    if len(given) != 3:
+        raise ValueError('red, green and blue must all be given together (missing: %s)'
+                         % ', '.join(k for k in ('red', 'green', 'blue') if k not in given))
+    out = []
+    for key in ('red', 'green', 'blue'):
+        value = args[key]
+        if isinstance(value, bool) or not isinstance(value, (int, float)) or int(value) != value:
+            raise ValueError('%s must be an integer 0..255' % key)
+        out.append(validate_int_range(key, value, 0, 255))
+    return tuple(out)
+
+
+def srgb_u8_to_linear(value):
+    """An 8-bit sRGB channel as the linear-light float GEGL's set_rgba expects."""
+    c = value / 255.0
+    return c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4
+
+
+def linear_to_srgb_u8(value):
+    """A linear-light float channel (GEGL's get_rgba) as an 8-bit sRGB integer."""
+    v = min(1.0, max(0.0, value))
+    c = v * 12.92 if v <= 0.0031308 else 1.055 * v ** (1 / 2.4) - 0.055
+    return int(round(c * 255))
+
+
+def justification_nick(alignment):
+    """GIMP's justification nick ('left' | 'right' | 'center' | 'fill') for a ps_text-style
+    `alignment`; refuses the variants GIMP has no equivalent for, naming what is supported."""
+    if alignment in TEXT_UNSUPPORTED_ALIGNMENTS:
+        raise ValueError(
+            'alignment %s is not supported by GIMP text layers; use one of %s'
+            % (alignment, ', '.join(TEXT_ALIGNMENTS))
+        )
+    if alignment not in TEXT_ALIGNMENTS:
+        raise ValueError('alignment must be one of %s'
+                         % ', '.join(list(TEXT_ALIGNMENTS) + list(TEXT_UNSUPPORTED_ALIGNMENTS)))
+    return TEXT_ALIGNMENTS[alignment]
+
+
+def alignment_name(nick):
+    """The ps_text-style alignment name for a GIMP justification nick (None when unknown)."""
+    return _JUSTIFICATION_TO_ALIGNMENT.get(nick)
+
+
+def _resolution_ppi(ppi):
+    return float(ppi) if ppi and ppi > 0 else DEFAULT_RESOLUTION_PPI
+
+
+def pt_to_px(pt, ppi):
+    """Points -> pixels at the image's vertical resolution (1 pt = 1/72 in)."""
+    return pt * _resolution_ppi(ppi) / 72.0
+
+
+def px_to_pt(px, ppi):
+    return round(px * 72.0 / _resolution_ppi(ppi), 2)
+
+
+def unit_size_to_pt(size, unit_is_pixel, units_per_inch, ppi):
+    """A text layer's font size in points, whichever unit it is stored in: pixels convert through
+    the image resolution; any other unit through its own units-per-inch factor."""
+    if unit_is_pixel or not units_per_inch:
+        return px_to_pt(size, ppi)
+    return round(size / units_per_inch * 72.0, 2)
+
+
+def _font_tokens(name):
+    return re.sub(r'[-_]+', ' ', name).lower().split()
+
+
+def _font_key(name):
+    return ' '.join(_font_tokens(name))
+
+
+def font_suggestions(query, names, limit=FONT_SUGGESTION_LIMIT):
+    """Up to `limit` installed font names closest to `query`: names containing it (or contained
+    by it) first, then the nearest by spelling."""
+    import difflib
+    q = _font_key(query)
+    ordered = sorted(set(names), key=lambda n: n.lower())
+    out = [n for n in ordered if q and (q in _font_key(n) or _font_key(n) in q)][:limit]
+    if len(out) < limit:
+        by_key = {}
+        for n in ordered:
+            by_key.setdefault(_font_key(n), n)
+        for key in difflib.get_close_matches(q, list(by_key), n=limit, cutoff=0.0):
+            if by_key[key] not in out:
+                out.append(by_key[key])
+            if len(out) >= limit:
+                break
+    return out[:limit]
+
+
+def resolve_font(query, names):
+    """Resolve a family ("Inter", "Open Sans") or full name ("Inter Bold") to an installed font
+    name, case- and spacing-insensitively. Returns (name, matched_by) with matched_by in
+    'name' | 'family+regular' | 'family'. Raises ValueError listing the closest installed names
+    when nothing matches."""
+    if not isinstance(query, str) or not query.strip():
+        raise ValueError('font_name must be a non-empty string')
+    ordered = sorted(set(names), key=lambda n: n.lower())
+    q = _font_key(query)
+    for n in ordered:
+        if _font_key(n) == q:
+            return n, 'name'
+    q_sorted = sorted(q.split())
+    for n in ordered:
+        if sorted(_font_tokens(n)) == q_sorted:
+            return n, 'name'
+    for style in _FONT_REGULAR_ORDER:
+        wanted = q + ' ' + style
+        for n in ordered:
+            if _font_key(n) == wanted:
+                return n, 'family+regular'
+    family = [
+        n for n in ordered
+        if _font_key(n).startswith(q + ' ')
+        and all(t in _FONT_STYLE_WORDS for t in _font_key(n)[len(q) + 1:].split())
+    ]
+    if family:
+        return min(family, key=lambda n: (len(n), n.lower())), 'family'
+    suggestions = font_suggestions(query, ordered)
+    if not suggestions:
+        raise ValueError('no installed font matches %r (no fonts are installed)' % query[:100])
+    raise ValueError(
+        'no installed font matches %r. Closest installed names: %s' % (query[:100], ', '.join(suggestions))
+    )
+
+
+def pick_default_font(names):
+    """The font a text layer gets when none is named: GIMP's built-in generic sans if listed,
+    else the first installed name (None when there are none)."""
+    ordered = sorted(set(names), key=lambda n: n.lower())
+    for n in ordered:
+        if _font_key(n) == _font_key(DEFAULT_TEXT_FONT):
+            return n
+    return ordered[0] if ordered else None
+
+
+def list_fonts(names, substring=None):
+    """(page, total) for gimp_inspect what=fonts: names sorted case-insensitively, filtered by a
+    case-insensitive substring, capped at TEXT_FONT_LIST_CAP; `total` counts every match."""
+    ordered = sorted(set(names), key=lambda n: n.lower())
+    if substring:
+        needle = substring.lower()
+        ordered = [n for n in ordered if needle in n.lower()]
+    return ordered[:TEXT_FONT_LIST_CAP], len(ordered)
+
+
+# Headroom on the small-size layout probe: glyph advances hinted at a few pixels round to whole
+# pixels, so scaling a probe up can undershoot the full-size layout.
+TEXT_ESTIMATE_MARGIN = 1.3
+
+
+def estimate_text_extent(probe_w, probe_h, probe_px, size_px, chars=0, lines=1, letter_spacing=0.0,
+                         line_spacing=0.0, indent=0.0):
+    """The (width, height) in px a text layer will render at `size_px`, from its layout measured
+    at `probe_px` (`probe_w` x `probe_h`), with headroom. Letter spacing, line spacing and indent
+    are absolute pixels that do not scale with the font, so each adds its full worst case: spacing
+    after every character and between every line, plus the indent. Never below 1x1."""
+    scale = size_px / float(probe_px)
+    width = math.ceil(probe_w * scale * TEXT_ESTIMATE_MARGIN) + chars * max(0.0, letter_spacing) + max(0.0, indent)
+    height = math.ceil(probe_h * scale * TEXT_ESTIMATE_MARGIN) + max(0, lines - 1) * max(0.0, line_spacing)
+    return max(1, int(math.ceil(width))), max(1, int(math.ceil(height)))
+
+
+def check_estimated_text_size(width, height):
+    """Refuses text whose estimated size (`estimate_text_extent`) is past the engine's size cap,
+    before anything is drawn at full size."""
+    try:
+        validate_resize_dims(width, height)
+    except ValueError as exc:
+        raise ValueError(
+            'the text would render as about %dx%d px, past the size limit (%s); use a smaller '
+            'font_size or less text' % (width, height, exc)
+        )
+
+
+# ---- text box and fit (gimp_text box / fit) --------------------------------------------------
+
+TEXT_FIT_DEFAULT_MIN_PX = 8
+TEXT_FIT_MAX_MIN_PX = 10000
+TEXT_FIT_MAX_PROBES = 12
+TEXT_BOX_SCAN_MAX_PIXELS = 16_000_000
+TEXT_OVERFLOW_LINES = 1_000_000  # "more lines than any box holds": what an overflowing probe reports
+TEXT_LINE_PITCH_SAMPLE_LINES = 10
+
+# A text box's own area ceiling, precision-aware like DOCUMENT_MEGAPIXEL_CAP but much tighter (a
+# text layer is a caption, not a canvas): 64 MP at 8-bit, halved for 16-bit and quartered for
+# 32-bit, and never above the matching document cap when EM_GIMP_MAX_MEGAPIXELS lowers those.
+TEXT_BOX_MEGAPIXEL_CAP = {
+    '8': min(64, MAX_RESIZE_MEGAPIXELS),
+    '16': min(32, MAX_RESIZE_MEGAPIXELS / 2),
+    '32': min(16, MAX_RESIZE_MEGAPIXELS / 4),
+}
+
+# Marks a text layer this tool put in a fixed box. GIMP cannot report a layer's box mode, so this
+# persistent layer parasite is how later edits know their size is bounded by the box.
+TEXT_BOX_TAG = 'editmamei-text-box'
+
+
+def check_text_box_area(width, height, precision='8'):
+    """Refuses a text box past the precision-aware text-box area cap (`TEXT_BOX_MEGAPIXEL_CAP`)."""
+    cap = TEXT_BOX_MEGAPIXEL_CAP[precision]
+    megapixels = (width * height) / 1_000_000.0
+    if megapixels > cap:
+        raise ValueError(
+            'a %dx%d px text box is %.1f MP, past the %g MP limit for a %s-bit text layer; use a '
+            'smaller box' % (width, height, megapixels, cap, precision)
+        )
+
+
+def text_scan_max_pixels(precision='8'):
+    """The largest probe layer (px) a box scan renders: `TEXT_BOX_SCAN_MAX_PIXELS`, or the text-box
+    area cap for `precision` when EM_GIMP_MAX_MEGAPIXELS has lowered it below that."""
+    return min(TEXT_BOX_SCAN_MAX_PIXELS, int(TEXT_BOX_MEGAPIXEL_CAP[precision] * 1_000_000))
+
+
+def check_text_fit_box(width, height, precision='8'):
+    """Refuses `fit` for a box too large to probe in one render (`text_scan_max_pixels`)."""
+    limit = text_scan_max_pixels(precision)
+    if width * height > limit:
+        raise ValueError(
+            'fit supports a box of at most %g MP (got %dx%d px); use a smaller box, or set the '
+            'box and font_size without fit' % (limit / 1_000_000.0, width, height)
+        )
+
+
+def text_scan_cap(width, precision='8'):
+    """The tallest probe layer (px) the box scan renders at `width`."""
+    return max(1, min(MAX_RESIZE_SIDE_PX, text_scan_max_pixels(precision) // max(1, width)))
+
+
+def fit_probe_plan(width, limit_h, pitch, precision='8'):
+    """(scan_h, clamped): the probe height for testing whether text fits `limit_h`, a little
+    taller than the limit so overflow shows as ink past it. `clamped` means the scan cap cut it
+    below that height, so ink on its last row only says "reaches the end of the probe"."""
+    ideal = int(math.ceil(limit_h + 2 * pitch)) + 1
+    scan_h = min(text_scan_cap(width, precision), ideal)
+    return scan_h, scan_h < ideal
+
+
+def fit_probe_overflows(ink_bottom_row, scan_h, clamped):
+    """Whether a clamped probe (`fit_probe_plan`) with ink on its last row means the text
+    overflows. An unclamped probe is judged by its line count instead."""
+    return bool(clamped and ink_bottom_row >= scan_h - 1)
+
+
+def validate_text_box(box):
+    """(width, height) from a `box` object `{width, height?}` in image px; height is None when
+    omitted (the layer grows to fit the wrapped text). Each side is held to the engine's resize
+    caps, and the area to its megapixel cap."""
+    if not isinstance(box, dict):
+        raise ValueError('box must be an object {width, height?}')
+    unknown = sorted(set(box) - {'width', 'height'})
+    if unknown:
+        raise ValueError('box has unknown keys: %s' % ', '.join(unknown))
+    if box.get('width') is None:
+        raise ValueError('box.width is required')
+    width = _box_side('box.width', box['width'])
+    height = None if box.get('height') is None else _box_side('box.height', box['height'])
+    validate_resize_dims(width, height if height is not None else 1)
+    return width, height
+
+
+def _box_side(name, value):
+    if (isinstance(value, bool) or not isinstance(value, (int, float))
+            or (isinstance(value, float) and not math.isfinite(value)) or int(value) != value):
+        raise ValueError('%s must be an integer' % name)
+    return validate_int_range(name, value, 1, MAX_RESIZE_SIDE_PX)
+
+
+def validate_text_fit(args, box):
+    """(fit, min_px) from `fit` / `min_size`. Fitting needs a box with both width and height;
+    `min_size` (pixels) is only meaningful with `fit`."""
+    fit = args.get('fit')
+    if fit is not None and not isinstance(fit, bool):
+        raise ValueError('fit must be a boolean')
+    min_given = args.get('min_size') is not None
+    if not fit:
+        if min_given:
+            raise ValueError('min_size only applies with fit: true')
+        return False, None
+    if box is None or box[1] is None:
+        raise ValueError('fit needs a box with both width and height')
+    min_px = TEXT_FIT_DEFAULT_MIN_PX
+    if min_given:
+        value = args['min_size']
+        if isinstance(value, bool) or not isinstance(value, (int, float)):
+            raise ValueError('min_size must be a number')
+        min_px = validate_range('min_size', value, 1, TEXT_FIT_MAX_MIN_PX)
+    return True, min_px
+
+
+def fit_font_size(max_px, min_px, fits, max_probes=TEXT_FIT_MAX_PROBES):
+    """The largest font size in [min_px, max_px] for which `fits(size)` is true, searched in
+    whole pixels (the requested max is tried exactly as given). Returns (size, fitted, probes);
+    `fitted` is False when even `min_px` overflows (the size is then `min_px`). Never calls
+    `fits` more than `max_probes` times: the search keeps the best size that fit so far."""
+    if min_px > max_px:
+        min_px = max_px
+    probes = 0
+
+    def probe(size):
+        nonlocal probes
+        probes += 1
+        return fits(size)
+
+    if probe(max_px):
+        return max_px, True, probes
+    if min_px >= max_px or not probe(min_px):
+        return min_px, False, probes
+    lo, hi = min_px, max_px  # lo fits, hi does not
+    while probes < max_probes:
+        mid = math.floor((lo + hi) / 2.0)
+        if mid <= lo:
+            break
+        if probe(mid):
+            lo = mid
+        else:
+            hi = mid
+    return lo, True, probes
+
+
+def wrapped_line_count(ink_bottom_row, pitch, explicit_lines):
+    """How many lines a wrapped text layout occupies, from the last row holding ink
+    (`ink_bottom_row`, -1 when blank) and the line pitch (line height plus line spacing). The
+    last line's ink always sits below the top of its own line box and within it, so its index is
+    `floor(row / pitch)`; lines the content separates with newlines count even when blank."""
+    lines = explicit_lines
+    if ink_bottom_row >= 0 and pitch > 0:
+        lines = max(lines, int(ink_bottom_row // pitch) + 1)
+    return max(1, lines)
+
+
+TEXT_REPORT_MAX_CHARS = 200
+
+
+def text_for_report(text):
+    """(text, length, truncated) for reporting a layer's text: at most TEXT_REPORT_MAX_CHARS,
+    since a layer opened from a file can hold any amount."""
+    text = text or ''
+    return text[:TEXT_REPORT_MAX_CHARS], len(text), len(text) > TEXT_REPORT_MAX_CHARS
+
+
+def check_text_layer_size(width, height):
+    """Refuses a rendered text layer past the engine's size cap (`validate_resize_dims`)."""
+    try:
+        validate_resize_dims(width, height)
+    except ValueError as exc:
+        raise ValueError(
+            'the text would render as a %dx%d px layer, past the size limit (%s); use a smaller '
+            'font_size or less text' % (width, height, exc)
+        )
+
+
+# ---- retouch: heal / clone / spot heal --------------------------------------------------------
+#
+# Pure helpers (no gi). Coordinates are image pixels; `bounds` is the half-open box
+# (x0, y0, x1, y1) of the layer clipped to the canvas.
+
+RETOUCH_TAG = 'editmamei-retouch'
+RETOUCH_METHODS = ('heal', 'clone', 'spot_heal')
+RETOUCH_TARGETS = ('retouch_layer', 'in_place')
+RETOUCH_MAX_POINTS = 500
+RETOUCH_MAX_SPOTS = 50
+RETOUCH_MIN_BRUSH = 1
+RETOUCH_MAX_BRUSH = 1000
+RETOUCH_DEFAULT_BRUSH = 20
+RETOUCH_DEFAULT_HARDNESS = {'heal': 0.5, 'clone': 0.8}
+RETOUCH_SPOT_HARDNESS = 0.5
+RETOUCH_MAX_SPOT_RADIUS = 500
+# Spot-heal source search: 8 directions on two rings, as multiples of the spot radius.
+RETOUCH_SPOT_RINGS = (2.2, 3.5)
+RETOUCH_SPOT_DIRECTIONS = 8
+# Healing blends a dab to the pixels around its edge, so the dab must reach past the spot: 2.6x the
+# radius is 1.3x the spot's diameter. A smaller brush sits wholly inside the spot and keeps its color.
+RETOUCH_SPOT_BRUSH_FACTOR = 2.6
+RETOUCH_SPOT_MIN_BRUSH = 3.0
+# The annulus a spot's surround is measured over, as a multiple of the spot radius.
+RETOUCH_SPOT_RING_OUTER = 1.6
+# How far a spot's heal reaches, as a multiple of its radius: half the spot brush (1.3x) beyond the
+# spot's own edge. Source candidates must keep this footprint inside the layer, and the Retouch
+# layer's mask reveals a feathered disc of this radius around each spot.
+RETOUCH_SPOT_REACH = 2.3
+# Hardness of the dab that reveals a healed spot on the Retouch layer's mask.
+RETOUCH_REVEAL_HARDNESS = 0.7
+# Work budgets, measured on a 6000x4000 image so the worst accepted call stays under about a minute:
+# a heal stroke costs about (path length + one brush) x brush, at worst ~25 us per unit (brush 90-100;
+# ~2-9 us at other sizes; a clone is far cheaper), so 2,000,000 is ~50 s; spot_heal costs ~270 us per
+# unit of the sum of radius squared, so 200,000 is ~55 s. Mirrored in tools/gimp-retouch-tools.ts.
+RETOUCH_MAX_STROKE_WORK = 2000000
+RETOUCH_MAX_SPOT_WORK = 200000
+
+
+def _finite_number(name, value):
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
+        raise ValueError('%s must be a finite number, got %r' % (name, value))
+    return float(value)
+
+
+def _xy(name, value):
+    if not isinstance(value, (list, tuple)) or len(value) != 2:
+        raise ValueError('%s must be [x, y], got %r' % (name, value))
+    return [_finite_number(name, value[0]), _finite_number(name, value[1])]
+
+
+def validate_retouch_args(args):
+    """The validated, defaulted `retouch` options as a dict. Raises ValueError (-> invalid_argument)
+    naming the field. heal/clone need `points` plus exactly one of `source` / `source_offset`
+    (returned as `source_offset` (dx, dy) relative to points[0]); spot_heal needs `spots`."""
+    method = args.get('method')
+    if method is None:
+        raise ValueError('method is required')
+    validate_choice('method', method, RETOUCH_METHODS)
+    target = validate_choice('target', args.get('target') or 'retouch_layer', RETOUCH_TARGETS)
+    opts = {'method': method, 'target': target}
+    if method == 'spot_heal':
+        if args.get('hardness') is not None:
+            raise ValueError('hardness does not apply to method spot_heal (it sizes its own brush)')
+        spots = args.get('spots')
+        if not isinstance(spots, list) or not 1 <= len(spots) <= RETOUCH_MAX_SPOTS:
+            raise ValueError('spots must be a list of 1..%d spots' % RETOUCH_MAX_SPOTS)
+        clean = []
+        for i, spot in enumerate(spots):
+            if not isinstance(spot, dict):
+                raise ValueError('spots[%d] must be {x, y, radius}' % i)
+            radius = _finite_number('spots[%d].radius' % i, spot.get('radius'))
+            if not 1 <= radius <= RETOUCH_MAX_SPOT_RADIUS:
+                raise ValueError('spots[%d].radius must be within 1..%d' % (i, RETOUCH_MAX_SPOT_RADIUS))
+            clean.append((
+                _finite_number('spots[%d].x' % i, spot.get('x')),
+                _finite_number('spots[%d].y' % i, spot.get('y')),
+                radius,
+            ))
+        work = retouch_spots_work(clean)
+        if work > RETOUCH_MAX_SPOT_WORK:
+            raise ValueError(
+                'these spots are too large to heal in one call (the sum of radius squared is %g, '
+                'the limit is %d): split them into several calls or use smaller radii'
+                % (work, RETOUCH_MAX_SPOT_WORK)
+            )
+        opts['spots'] = clean
+        return opts
+    points = args.get('points')
+    if not isinstance(points, list) or not 1 <= len(points) <= RETOUCH_MAX_POINTS:
+        raise ValueError('points must be a list of 1..%d [x, y] points' % RETOUCH_MAX_POINTS)
+    opts['points'] = [_xy('points', p) for p in points]
+    source, offset = args.get('source'), args.get('source_offset')
+    if (source is None) == (offset is None):
+        raise ValueError('give exactly one of source {x, y} or source_offset {dx, dy}')
+    if source is not None:
+        if not isinstance(source, dict):
+            raise ValueError('source must be {x, y}')
+        sx = _finite_number('source.x', source.get('x'))
+        sy = _finite_number('source.y', source.get('y'))
+        opts['source_offset'] = (sx - opts['points'][0][0], sy - opts['points'][0][1])
+    else:
+        if not isinstance(offset, dict):
+            raise ValueError('source_offset must be {dx, dy}')
+        opts['source_offset'] = (
+            _finite_number('source_offset.dx', offset.get('dx')),
+            _finite_number('source_offset.dy', offset.get('dy')),
+        )
+    brush = args.get('brush_size')
+    opts['brush_size'] = validate_range(
+        'brush_size', RETOUCH_DEFAULT_BRUSH if brush is None else brush,
+        RETOUCH_MIN_BRUSH, RETOUCH_MAX_BRUSH,
+    )
+    work = retouch_stroke_work(opts['points'], opts['brush_size'])
+    if work > RETOUCH_MAX_STROKE_WORK:
+        raise ValueError(
+            'this stroke is too long for its brush size to paint in one call (about %d px of '
+            'path x brush, the limit is %d): split the stroke into several calls or use a '
+            'smaller brush' % (work, RETOUCH_MAX_STROKE_WORK)
+        )
+    hardness = args.get('hardness')
+    opts['hardness'] = validate_range(
+        'hardness', RETOUCH_DEFAULT_HARDNESS[method] if hardness is None else hardness, 0.0, 1.0
+    )
+    return opts
+
+
+def retouch_stroke_work(points, brush_size):
+    """The cost estimate of a heal/clone stroke: (path length + one brush) x brush, about the area
+    the brush sweeps (a single dab still costs its own area)."""
+    length = sum(
+        math.hypot(b[0] - a[0], b[1] - a[1]) for a, b in zip(points, points[1:])
+    )
+    return (length + brush_size) * brush_size
+
+
+def retouch_spots_work(spots):
+    """The cost estimate of a spot_heal call: the sum of radius squared over its (x, y, r) spots."""
+    return sum(r * r for _x, _y, r in spots)
+
+
+def retouch_bounds(layer_x, layer_y, layer_width, layer_height, canvas_width, canvas_height):
+    """The layer's box clipped to the canvas as half-open (x0, y0, x1, y1); None when empty."""
+    x0, y0 = max(0, layer_x), max(0, layer_y)
+    x1 = min(canvas_width, layer_x + layer_width)
+    y1 = min(canvas_height, layer_y + layer_height)
+    if x1 <= x0 or y1 <= y0:
+        return None
+    return (x0, y0, x1, y1)
+
+
+def retouch_check_points(points, bounds, what):
+    """Raises ValueError naming `bounds` for the first point outside the half-open box."""
+    x0, y0, x1, y1 = bounds
+    for i, (x, y) in enumerate(points):
+        if not (x0 <= x < x1 and y0 <= y < y1):
+            raise ValueError(
+                '%s point %d (%g, %g) is outside the layer bounds x %d..%d, y %d..%d (image pixels)'
+                % (what, i, x, y, x0, x1 - 1, y0, y1 - 1)
+            )
+
+
+def retouch_spot_brush(radius):
+    """Brush diameter for healing a spot of `radius`: 1.3x the spot's diameter, within 3..1000."""
+    return max(RETOUCH_SPOT_MIN_BRUSH,
+               min(float(RETOUCH_MAX_BRUSH), radius * RETOUCH_SPOT_BRUSH_FACTOR))
+
+
+def retouch_cover_stroke(cx, cy, radius, brush_size, bounds=None, max_points=RETOUCH_MAX_POINTS):
+    """A stroke (list of [x, y]) whose brush (diameter `brush_size`) covers the disc at (cx, cy):
+    an Archimedean spiral from the center out to `radius` with a turn pitch of 0.6 x the brush, then
+    one full circle at `radius`, points spaced 0.4 x the brush apart (a heal dab blends to its
+    own edge, so several overlapping dabs beat one). Clamped into `bounds`; the
+    spacing widens if the stroke would exceed `max_points`."""
+    if radius <= 0 or brush_size <= 0:
+        return [[cx, cy]]
+    scale = 1.0
+    # Estimated point count (spiral length / spacing + the closing circle), so a stroke that would
+    # blow the cap widens its spacing up front instead of generating it first.
+    while ((math.pi * radius ** 2 / (0.6 * brush_size * scale) + 2 * math.pi * radius)
+           / (0.4 * brush_size * scale) > max_points * 0.9):
+        scale *= 1.1
+    while True:
+        pitch, step = 0.6 * brush_size * scale, 0.4 * brush_size * scale
+        pts = [(cx, cy)]
+        theta = 0.0
+        while True:
+            r = min(radius, pitch * theta / (2 * math.pi))
+            if r >= radius:
+                break
+            theta += step / max(r, step)
+            r = min(radius, pitch * theta / (2 * math.pi))
+            pts.append((cx + r * math.cos(theta), cy + r * math.sin(theta)))
+            if r >= radius:
+                break
+        n = max(3, int(math.ceil(2 * math.pi * radius / step)))
+        for k in range(1, n + 1):
+            a = theta + 2 * math.pi * k / n
+            pts.append((cx + radius * math.cos(a), cy + radius * math.sin(a)))
+        if len(pts) <= max_points:
+            break
+        scale *= 1.25
+    if bounds is not None:
+        x0, y0, x1, y1 = bounds
+        pts = [(min(max(x, x0), x1 - 1), min(max(y, y0), y1 - 1)) for x, y in pts]
+    return [[round(x, 2), round(y, 2)] for x, y in pts]
+
+
+def retouch_painted_bbox(points, brush_size, bounds):
+    """[x, y, w, h] of the stroke's brush footprint (points grown by half the brush), clipped to
+    `bounds`; [0, 0, 0, 0] when nothing is left."""
+    half = brush_size / 2.0
+    x0 = max(bounds[0], int(math.floor(min(p[0] for p in points) - half)))
+    y0 = max(bounds[1], int(math.floor(min(p[1] for p in points) - half)))
+    x1 = min(bounds[2], int(math.ceil(max(p[0] for p in points) + half)))
+    y1 = min(bounds[3], int(math.ceil(max(p[1] for p in points) + half)))
+    if x1 <= x0 or y1 <= y0:
+        return [0, 0, 0, 0]
+    return [x0, y0, x1 - x0, y1 - y0]
+
+
+def union_bbox_xywh(a, b):
+    """Union of two [x, y, w, h] boxes; an empty (zero-area) box is ignored."""
+    if a is None or a[2] <= 0 or a[3] <= 0:
+        return list(b) if b is not None else None
+    if b is None or b[2] <= 0 or b[3] <= 0:
+        return list(a)
+    x0, y0 = min(a[0], b[0]), min(a[1], b[1])
+    x1, y1 = max(a[0] + a[2], b[0] + b[2]), max(a[1] + a[3], b[1] + b[3])
+    return [x0, y0, x1 - x0, y1 - y0]
+
+
+def spot_candidates(cx, cy, radius, bounds, reach=None):
+    """Candidate source offsets (dx, dy) for a spot: 8 directions on each of the two rings
+    (2.2x and 3.5x the radius). A candidate is dropped when its source footprint -- a disc of
+    `reach` (default 2.3 x radius, RETOUCH_SPOT_REACH: the spot plus the healing brush's edge)
+    around the shifted center -- leaves `bounds`. Rounded to whole pixels; order is ring-major, then by angle."""
+    if reach is None:
+        reach = radius * RETOUCH_SPOT_REACH
+    x0, y0, x1, y1 = bounds
+    out = []
+    for ring in RETOUCH_SPOT_RINGS:
+        dist = ring * radius
+        for k in range(RETOUCH_SPOT_DIRECTIONS):
+            a = 2 * math.pi * k / RETOUCH_SPOT_DIRECTIONS
+            dx, dy = int(round(dist * math.cos(a))), int(round(dist * math.sin(a)))
+            sx, sy = cx + dx, cy + dy
+            if sx - reach < x0 or sy - reach < y0 or sx + reach > x1 or sy + reach > y1:
+                continue
+            out.append((dx, dy))
+    return out
+
+
+def spot_score(cand_mean, cand_std, ring_mean, ring_std):
+    """How far a candidate disc's (mean, std) is from the spot's surround ring: the sum of the two
+    absolute differences, in histogram units (0-255). Lower is better."""
+    return abs(cand_mean - ring_mean) + abs(cand_std - ring_std)
+
+
+def spot_pick_best(scored):
+    """The (dx, dy, score) with the lowest score from [(dx, dy, score), ...]; the earliest wins
+    a tie. None when empty."""
+    best = None
+    for item in scored:
+        if best is None or item[2] < best[2]:
+            best = item
+    return best
+
+
+# ---- render_region / keep_alpha ---------------------------------------------------------------
+
+# render_region is never downscaled: a box past either bound is refused outright.
+RENDER_REGION_MAX_PIXELS = 16_000_000
+RENDER_REGION_MAX_SIDE = 4096
+KEEP_ALPHA_EXTENSIONS = ('.png', '.webp')
+
+
+def _whole_pixels(name, value):
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
+        raise ValueError('%s must be a whole number of pixels, got %r' % (name, value))
+    if value != int(value):
+        raise ValueError('%s must be a whole number of pixels, got %r' % (name, value))
+    return int(value)
+
+
+def validate_render_box(box, canvas_width, canvas_height):
+    """`box` [x, y, w, h] in image pixels, clamped to the canvas, as ints. Refuses a malformed box,
+    a box with no pixels on the canvas, and one past RENDER_REGION_MAX_PIXELS /
+    RENDER_REGION_MAX_SIDE (checked after clamping)."""
+    if not isinstance(box, (list, tuple)) or len(box) != 4:
+        raise ValueError('box must be [x, y, width, height] in image pixels')
+    x, y, w, h = [_whole_pixels('box', v) for v in box]
+    if w <= 0 or h <= 0:
+        raise ValueError('box width and height must be positive')
+    x0, y0 = max(0, x), max(0, y)
+    x1, y1 = min(canvas_width, x + w), min(canvas_height, y + h)
+    if x1 <= x0 or y1 <= y0:
+        raise ValueError(
+            'box [%d, %d, %d, %d] does not overlap the %dx%d canvas' % (x, y, w, h, canvas_width, canvas_height)
+        )
+    w, h = x1 - x0, y1 - y0
+    if max(w, h) > RENDER_REGION_MAX_SIDE or w * h > RENDER_REGION_MAX_PIXELS:
+        raise ValueError(
+            'box is %dx%d px; render_region allows at most %d px on a side and %d megapixels '
+            '(it never downscales)' % (w, h, RENDER_REGION_MAX_SIDE, RENDER_REGION_MAX_PIXELS // 1_000_000)
+        )
+    return x0, y0, w, h
+
+
+def validate_keep_alpha(args, path):
+    """Whether `export` should keep transparency: `keep_alpha` must be a boolean (default False)
+    and only PNG and WebP can carry it."""
+    keep = optional_bool(args, 'keep_alpha', False)
+    if keep and os.path.splitext(path)[1].lower() not in KEEP_ALPHA_EXTENSIONS:
+        raise ValueError('keep_alpha only works with a .png or .webp file path')
+    return keep