editmamei 1.8.0 → 1.9.1

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,12 +352,19 @@ 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
+# 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
 
 
@@ -204,6 +388,17 @@ MAX_RESIZE_MEGAPIXELS = megapixel_cap_from_env(os.environ.get('EM_GIMP_MAX_MEGAP
 
 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
@@ -331,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
@@ -916,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)
@@ -1033,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
@@ -1194,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,
@@ -1201,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`
@@ -1214,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},
 }
 
 
@@ -1270,7 +1592,7 @@ USER_FIELDS = {
     ),
     'saturation': (('scale', 'scale', _same),),
     'vibrance': (
-        ('vibrance', 'vibrance', _same),
+        ('vibrance', 'vibrance', _scaled(VIBRANCE_GEGL_DIVISOR)),
         ('saturation', 'saturation', _same),
     ),
     'sharpen': (
@@ -1313,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')
@@ -1399,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) -----
 
 
@@ -1632,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'])
@@ -1669,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']
@@ -1719,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
 
@@ -1735,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
@@ -1752,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',
+}
+
+
+# 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,
 }
 
 
-def validate_effect_transform(op_name, operation, filter_name, new_params):
+# 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
@@ -1763,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)
@@ -2086,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
@@ -2125,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
 
@@ -2173,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)
@@ -2268,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."""
@@ -2287,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
 
 
@@ -2568,6 +2965,69 @@ def metadata_strip_settings(fmt, prop_names):
     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
@@ -2796,6 +3256,163 @@ def check_estimated_text_size(width, height):
         )
 
 
+# ---- 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
 
 
@@ -2815,3 +3432,321 @@ def check_text_layer_size(width, height):
             '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