editmamei 1.7.1 → 1.9.0

package/dist/tools/gimp-fill-tools.js

@@ -0,0 +1,256 @@
+import { GimpError } from '../backends/gimp/errors.js';
+import { GIMP_IMAGE_PROP, GIMP_LAYER_ID_PROP, GIMP_LAYER_PROP, pickSchemaDeclaredKeys, runGimpTool, } from './gimp-shared.js';
+export const FILL_MIN_STOPS = 2;
+export const FILL_MAX_STOPS = 8;
+const OPS = ['solid', 'linear_gradient', 'radial_gradient'];
+export const FILL_MODE_NAMES = [
+    'normal',
+    'multiply',
+    'screen',
+    'overlay',
+    'soft_light',
+    'hard_light',
+    'darken',
+    'lighten',
+    'difference',
+    'exclusion',
+    'addition',
+    'subtract',
+    'divide',
+    'dodge',
+    'burn',
+    'hue',
+    'saturation',
+    'color',
+    'luminosity',
+    'grain_extract',
+    'grain_merge',
+    'lch_color',
+];
+export const FILL_MAX_COORD_PX = 300_000;
+export const FILL_MAX_STRING_LEN = 255;
+const MIN_AXIS_PX = 1;
+const HEX = /^#[0-9a-fA-F]{6}$/;
+const POINT_PROP = {
+    type: 'object',
+    properties: {
+        x: { type: 'number', minimum: -FILL_MAX_COORD_PX, maximum: FILL_MAX_COORD_PX },
+        y: { type: 'number', minimum: -FILL_MAX_COORD_PX, maximum: FILL_MAX_COORD_PX },
+    },
+    required: ['x', 'y'],
+};
+const fillSchema = {
+    type: 'object',
+    properties: {
+        image: GIMP_IMAGE_PROP,
+        op: {
+            type: 'string',
+            enum: OPS,
+            description: "'solid': one flat color. 'linear_gradient': a ramp from start to end. " +
+                "'radial_gradient': a ramp from a center out to a radius.",
+        },
+        layer: {
+            ...GIMP_LAYER_PROP,
+            description: 'Name of the layer the new fill layer goes directly above (inside its group). Defaults ' +
+                'to the selected layer, or the topmost layer if none is selected.',
+        },
+        layer_id: GIMP_LAYER_ID_PROP,
+        name: {
+            type: 'string',
+            description: "New layer's name. Default 'Fill' for solid, 'Gradient' for a gradient.",
+        },
+        color: {
+            type: 'string',
+            pattern: '^#[0-9a-fA-F]{6}$',
+            description: 'solid only: the color as #rrggbb.',
+        },
+        stops: {
+            type: 'array',
+            minItems: FILL_MIN_STOPS,
+            maxItems: FILL_MAX_STOPS,
+            items: {
+                type: 'object',
+                properties: {
+                    offset: { type: 'number', minimum: 0, maximum: 1 },
+                    color: { type: 'string', pattern: '^#[0-9a-fA-F]{6}$' },
+                    opacity: { type: 'number', minimum: 0, maximum: 100, default: 100 },
+                },
+                required: ['offset', 'color'],
+            },
+            description: 'Gradient only: 2-8 color stops {offset 0..1, color #rrggbb, opacity 0..100}, sorted by ' +
+                'offset. Colors blend in sRGB (a black to white stop pair reads 128 at the midpoint). ' +
+                'Before the first stop and after the last, the end colors hold.',
+        },
+        start: {
+            ...POINT_PROP,
+            description: 'linear_gradient: where offset 0 sits, in image pixels. Default top center of the canvas.',
+        },
+        end: {
+            ...POINT_PROP,
+            description: 'linear_gradient: where offset 1 sits, in image pixels. Default bottom center of the canvas.',
+        },
+        center: {
+            ...POINT_PROP,
+            description: 'radial_gradient: where offset 0 sits, in image pixels. Default canvas center.',
+        },
+        radius: {
+            type: 'number',
+            minimum: 1,
+            maximum: FILL_MAX_COORD_PX,
+            description: 'radial_gradient: the distance in pixels at which offset 1 is reached. Default half the ' +
+                'canvas diagonal.',
+        },
+        mode: {
+            type: 'string',
+            enum: FILL_MODE_NAMES,
+            default: 'normal',
+            description: "The new layer's blend mode: gimp_layer's list plus 'lch_color'. 'color' is HSL Color; " +
+                "'lch_color' (LCh Color) keeps the lightness underneath exactly and swaps only hue and " +
+                'chroma, the better choice for recoloring.',
+        },
+        opacity: {
+            type: 'number',
+            minimum: 0,
+            maximum: 100,
+            default: 100,
+            description: "The new layer's opacity, 0-100.",
+        },
+        mask: {
+            type: 'string',
+            description: "The name of a selection channel: becomes the new layer's layer mask, white " +
+                'where the channel is selected, so the fill shows only there.',
+        },
+    },
+    required: ['image', 'op'],
+};
+const bad = (message) => {
+    throw new GimpError('invalid_argument', message);
+};
+function isNum(v) {
+    return typeof v === 'number' && Number.isFinite(v);
+}
+function checkPoint(name, v) {
+    const o = v;
+    if (!o || typeof o !== 'object' || !isNum(o['x']) || !isNum(o['y'])) {
+        return bad(`${name} must be {x, y} with finite numbers`);
+    }
+    if (Math.abs(o['x']) > FILL_MAX_COORD_PX || Math.abs(o['y']) > FILL_MAX_COORD_PX) {
+        bad(`${name} must be within +/-${FILL_MAX_COORD_PX} px`);
+    }
+    return { x: o['x'], y: o['y'] };
+}
+export function validateFillArgs(args) {
+    const op = args['op'];
+    for (const k of ['name', 'mask']) {
+        const v = args[k];
+        if (typeof v === 'string' && v.length > FILL_MAX_STRING_LEN) {
+            bad(`${k} must be at most ${FILL_MAX_STRING_LEN} characters`);
+        }
+    }
+    const only = (keys, why) => {
+        for (const k of keys)
+            if (args[k] !== undefined)
+                bad(`${k} does not apply to ${why}`);
+    };
+    if (op === 'solid') {
+        if (typeof args['color'] !== 'string' || !HEX.test(args['color'])) {
+            bad('color must be a color like #rrggbb for op solid');
+        }
+        only(['stops', 'start', 'end', 'center', 'radius'], 'op solid');
+        return;
+    }
+    only(['color'], 'a gradient (give stops)');
+    const stops = args['stops'];
+    if (!Array.isArray(stops) || stops.length < FILL_MIN_STOPS || stops.length > FILL_MAX_STOPS) {
+        bad(`stops must be a list of ${FILL_MIN_STOPS}..${FILL_MAX_STOPS} stops for op ${String(op)}`);
+    }
+    let previous = -1;
+    stops.forEach((s, i) => {
+        const o = s;
+        if (!o || typeof o !== 'object' || !isNum(o['offset']) || typeof o['color'] !== 'string') {
+            return bad(`stops[${i}] must be {offset, color, opacity?}`);
+        }
+        if (!HEX.test(o['color']))
+            bad(`stops[${i}].color must be a color like #rrggbb`);
+        if (o['offset'] < 0 || o['offset'] > 1)
+            bad(`stops[${i}].offset must be within 0..1`);
+        const opacity = o['opacity'];
+        if (opacity !== undefined && (!isNum(opacity) || opacity < 0 || opacity > 100)) {
+            bad(`stops[${i}].opacity must be within 0..100`);
+        }
+        if (o['offset'] < previous)
+            bad(`stops must be sorted by offset: stops[${i}] is out of order`);
+        previous = o['offset'];
+    });
+    if (op === 'linear_gradient') {
+        only(['center', 'radius'], 'op linear_gradient');
+        const start = args['start'] === undefined ? undefined : checkPoint('start', args['start']);
+        const end = args['end'] === undefined ? undefined : checkPoint('end', args['end']);
+        if (start && end && Math.hypot(end.x - start.x, end.y - start.y) < MIN_AXIS_PX) {
+            bad(`start and end must be at least ${MIN_AXIS_PX} pixel apart`);
+        }
+    }
+    else {
+        only(['start', 'end'], 'op radial_gradient');
+        if (args['center'] !== undefined)
+            checkPoint('center', args['center']);
+        const radius = args['radius'];
+        if (radius !== undefined && (!isNum(radius) || radius < 1 || radius > FILL_MAX_COORD_PX)) {
+            bad(`radius must be within 1..${FILL_MAX_COORD_PX} pixels`);
+        }
+    }
+}
+export function createGimpFillTools(gimp) {
+    return [
+        {
+            tool: {
+                name: 'gimp_fill',
+                description: 'Headless GIMP: add a NEW layer, canvas-sized, filled with a solid color (op solid), a ' +
+                    'linear gradient (start to end) or a radial gradient (center and radius) through 2-8 ' +
+                    'color stops. The layer goes directly above the target layer (inside its group), with ' +
+                    'the blend mode and opacity you give; mode lch_color tints without touching lightness, ' +
+                    'the usual choice for recoloring. Pass mask (a channel name) to confine the fill to ' +
+                    'that channel: it becomes the layer mask. Gradients blend in sRGB, are not dithered, ' +
+                    'and use image pixels for every point. The current selection is kept and does not clip ' +
+                    'the fill. Do NOT use for painting strokes or touching up pixels; use gimp_retouch ' +
+                    'for that. Returns layer_id, layer_name, op, mode, opacity and masked.',
+                inputSchema: fillSchema,
+                outputSchema: {
+                    type: 'object',
+                    properties: {
+                        layer_id: { type: 'number' },
+                        layer_name: { type: 'string' },
+                        op: { type: 'string' },
+                        mode: { type: 'string' },
+                        opacity: { type: 'number' },
+                        masked: { type: 'boolean' },
+                    },
+                },
+                annotations: {
+                    title: 'Fill GIMP Layer',
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: true,
+                },
+            },
+            handler: async (args) => runGimpTool({
+                gimp,
+                rawArgs: args,
+                schema: fillSchema,
+                op: 'fill',
+                errorPrefix: 'Error filling GIMP layer',
+                params: (validated) => {
+                    validateFillArgs(validated);
+                    return pickSchemaDeclaredKeys(fillSchema, validated);
+                },
+                successText: (result) => {
+                    const r = result;
+                    return (`Fill: ${r.op.replace('_', ' ')} on new layer "${r.layer_name}" (layer ${r.layer_id}), ` +
+                        `${r.mode} at ${r.opacity}%${r.masked ? ', masked' : ''}.`);
+                },
+            }),
+        },
+    ];
+}
+export const FILL_SCHEMA_FOR_TESTS = fillSchema;

package/dist/tools/gimp-filter-tools.js

@@ -1,6 +1,7 @@
 import { validateArgs } from '../utils/validate.js';
 import { toolGimpErrorResult, unknownDiscriminator } from '../utils/tool-helpers.js';
 import { GIMP_IMAGE_PROP, pickSchemaDeclaredKeys } from './gimp-shared.js';
+import { capLines, filterLine } from './gimp-result-text.js';
 const filterSchema = {
     type: 'object',
     properties: {
@@ -41,7 +42,9 @@ async function gimpFilter(gimp, rawArgs) {
         let text;
         if (op === 'list') {
             const filters = result.filters ?? [];
-            text = `${filters.length} filter(s) on image ${args.image}.`;
+            text = `${filters.length} filter(s) on image ${args.image}, top of stack first.`;
+            if (filters.length > 0)
+                text += '\n' + capLines(filters.map(filterLine)).join('\n');
         }
         else if (op === 'set_visibility') {
             text = `Filter ${result.filter_id} visibility set to ${result.visible}.`;

package/dist/tools/gimp-geometry-tools.js

@@ -38,7 +38,7 @@ const resizeSchema = {
     },
     required: ['image'],
 };
-const EFFECT_UPDATE_FAILURES_PROP = {
+export const EFFECT_UPDATE_FAILURES_PROP = {
     type: 'array',
     items: { type: 'string' },
     description: 'Names of effect filters (position/direction/size-dependent ones tracked through geometry ' +
@@ -75,7 +75,7 @@ const transformCanvasSchema = {
     },
     required: ['image', 'op'],
 };
-function effectUpdateFailuresNote(failures) {
+export function effectUpdateFailuresNote(failures) {
     if (!failures || failures.length === 0)
         return '';
     const plural = failures.length > 1;

package/dist/tools/gimp-inspect-tools.js

@@ -1,7 +1,8 @@
 import { validateArgs } from '../utils/validate.js';
 import { toolGimpErrorResult, unknownDiscriminator } from '../utils/tool-helpers.js';
 import { pickSchemaDeclaredKeys } from './gimp-shared.js';
-const INSPECT_WHATS = ['documents', 'document', 'layers', 'channels', 'filter'];
+import { capLines, channelsText, filterLine, layerTreeLines } from './gimp-result-text.js';
+const INSPECT_WHATS = ['documents', 'document', 'layers', 'channels', 'filter', 'fonts'];
 const inspectSchema = {
     type: 'object',
     properties: {
@@ -20,12 +21,19 @@ const inspectSchema = {
                 "allows duplicate layer names) and flag `is_text_layer`. 'document'/'layers' cap the tree " +
                 'at 2000 nodes total and report `truncated: true` if the cap was hit, alongside ' +
                 '`top_level_count` and `total_nodes`; if it times out the GIMP session restarts and ' +
-                'unsaved work is lost, so save (gimp_save_xcf) first.',
+                "unsaved work is lost, so save (gimp_save_xcf) first. A text layer's node also reports " +
+                "its text, font, font_size (points), color and alignment. 'fonts' lists the installed " +
+                'font names (no image needed), optionally narrowed by `filter`.',
         },
         image: {
             type: 'integer',
             description: 'Image id, as returned by gimp_open_document. Required for every `what` except ' +
-                "'documents'.",
+                "'documents' and 'fonts'.",
+        },
+        filter: {
+            type: 'string',
+            description: "what='fonts' only: case-insensitive substring to narrow the font names by. The list is " +
+                'sorted and capped at 200 names; `total` counts every match.',
         },
         filter_id: {
             type: 'integer',
@@ -35,28 +43,35 @@ const inspectSchema = {
     },
     required: ['what'],
 };
+function withLayerTree(summary, layers) {
+    const lines = capLines(layerTreeLines(layers));
+    return lines.length > 0 ? `${summary}\n${lines.join('\n')}` : summary;
+}
 function describeSummary(what, args, result) {
     const truncatedSuffix = result.truncated ? ' (truncated at the node cap)' : '';
     if (what === 'filter') {
-        return `Filter ${result.filter_id} ("${result.name}"): ${result.operation}.`;
+        return filterLine(result);
     }
     if (what === 'layers') {
         const layers = result.layers ?? [];
         const topLevelCount = result.top_level_count ?? layers.length;
-        return `${topLevelCount} top-level layer(s) on image ${args.image}${truncatedSuffix}.`;
+        return withLayerTree(`${topLevelCount} top-level layer(s) on image ${args.image}${truncatedSuffix}, top of stack first.`, layers);
     }
     if (what === 'channels') {
         const channels = result.channels ?? [];
         const skipped = result.channels_skipped;
         const stoppedEarlySuffix = result.truncated && skipped ? ` (stopped early, ${skipped} channel(s) skipped)` : '';
-        return `${channels.length} channel(s) on image ${args.image}${stoppedEarlySuffix}.`;
+        return (`${channels.length} channel(s) on image ${args.image}${stoppedEarlySuffix}` +
+            (channels.length > 0 ? `: ${channelsText(channels)}.` : '.'));
     }
     const layers = result.layers ?? [];
     const channels = result.channels ?? [];
     const topLevelCount = result.top_level_count ?? layers.length;
-    return (`Document ${result.image}: ${result.width}x${result.height} ${result.base_type} ` +
+    return withLayerTree(`Document ${result.image}: ${result.width}x${result.height} ${result.base_type} ` +
         `${result.precision}, ${topLevelCount} top-level layer(s)${truncatedSuffix}, ` +
-        `${channels.length} channel(s).`);
+        `${channels.length} channel(s)` +
+        (channels.length > 0 ? `: ${channelsText(channels)}.` : '.') +
+        (layers.length > 0 ? ' Layers, top of stack first:' : ''), layers);
 }
 async function gimpInspect(gimp, rawArgs) {
     try {
@@ -75,6 +90,22 @@ async function gimpInspect(gimp, rawArgs) {
                 structuredContent: { what, documents },
             };
         }
+        if (what === 'fonts') {
+            const result = await gimp.call('fonts', pickSchemaDeclaredKeys(inspectSchema, args));
+            const shown = result.fonts.length;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `${result.total} font(s) installed` +
+                            (args.filter ? ` matching "${String(args.filter).slice(0, 100)}"` : '') +
+                            (shown < result.total ? `, showing the first ${shown}` : '') +
+                            `: ${result.fonts.join(', ') || '(none)'}.`,
+                    },
+                ],
+                structuredContent: { what, ...result },
+            };
+        }
         if (what === 'document' || what === 'layers' || what === 'channels' || what === 'filter') {
             const result = await gimp.call('describe', pickSchemaDeclaredKeys(inspectSchema, args));
             return {
@@ -100,8 +131,11 @@ export function createGimpInspectTools(gimp) {
                     "WITH coverage (selected_pixels/fraction), the cost 'document' skips, and can stop " +
                     'early on a document with many named channels (`truncated: true`, `channels_skipped`). ' +
                     "'filter' describes one filter by filter_id, in the same shape gimp_filter (op=list) " +
-                    'reports it in. Layer tree nodes are addressed by `layer_id` (canonical — GIMP allows ' +
-                    "duplicate layer names) and flag `is_text_layer`. 'document'/'layers' cap the tree at " +
+                    "reports it in. 'fonts' lists the installed font names (no image needed), sorted, " +
+                    'optionally narrowed by `filter` (substring), capped at 200 with a `total`. Layer tree ' +
+                    'nodes are addressed by `layer_id` (canonical — GIMP allows duplicate layer names) and ' +
+                    "flag `is_text_layer`; a text layer's node also reports its text, font, font_size " +
+                    "(points), color and alignment. 'document'/'layers' cap the tree at " +
                     '2000 nodes total and report `truncated: true` if the cap was hit, alongside ' +
                     '`top_level_count` and `total_nodes`; if it times out the GIMP session restarts and ' +
                     'unsaved work is lost, so save (gimp_save_xcf) first.',
@@ -110,6 +144,10 @@ export function createGimpInspectTools(gimp) {
                     type: 'object',
                     properties: {
                         what: { type: 'string' },
+                        fonts: { type: 'array', items: { type: 'string' } },
+                        total: { type: 'number' },
+                        returned: { type: 'number' },
+                        default: { type: ['string', 'null'] },
                         documents: {
                             type: 'array',
                             items: { type: 'object', properties: { image: { type: 'number' } } },

package/dist/tools/gimp-layer-tools.js

@@ -8,7 +8,6 @@ const LAYER_OPS = [
     'duplicate',
     'select',
     'set',
-    'move',
     'reorder',
     'merge_down',
     'flatten',
@@ -31,10 +30,7 @@ const layerSchema = {
                 'target for gimp_add_adjustment and friends when no layer is named) and is the one sub-op ' +
                 "that changes nothing else. 'set' changes opacity, mode, visible, and/or name (at least " +
                 'one required, name may not be empty) — mode is a blend mode from a fixed list, not a raw ' +
-                "GEGL/GIMP name. 'move' repositions a layer to an ABSOLUTE x/y (not a delta), bounded to " +
-                'stay near the canvas — REFUSED when the layer, or a group containing it, carries a ' +
-                "masked or unverifiable adjustment filter, since a filter's mask does not travel with " +
-                "content that moves beneath it. 'reorder' " +
+                "GEGL/GIMP name. 'reorder' " +
                 "changes a layer's stack position and/or moves it into a group (parent_group) or out to " +
                 'top-level (to_top_level: true) — neither given keeps the layer in its current group and ' +
                 'only changes `position`; REFUSED if parent_group would nest a group inside itself or one ' +
@@ -132,6 +128,8 @@ const layerSchema = {
                 'saturation',
                 'color',
                 'luminosity',
+                'grain_extract',
+                'grain_merge',
             ],
             description: 'set only. A fixed blend-mode list, not a raw GEGL/GIMP mode name.',
         },
@@ -139,14 +137,6 @@ const layerSchema = {
             type: 'boolean',
             description: 'set only.',
         },
-        x: {
-            type: 'integer',
-            description: "move only. The layer's new ABSOLUTE horizontal offset in document pixels (not a delta).",
-        },
-        y: {
-            type: 'integer',
-            description: "move only. The layer's new ABSOLUTE vertical offset in document pixels (not a delta).",
-        },
         discard_hidden: {
             type: 'boolean',
             default: false,
@@ -169,8 +159,6 @@ function layerSuccessText(op, result, args) {
             return `Duplicated as layer ${result.layer_id} ("${result.name}").`;
         case 'select':
             return `Selected layer ${result.layer_id} ("${result.name}").`;
-        case 'move':
-            return `Moved layer ${result.layer_id} to (${result.x}, ${result.y}).`;
         case 'reorder':
             return (`Reordered layer ${result.layer_id}` +
                 (result.parent_group != null
@@ -277,7 +265,7 @@ export function createGimpLayerTools(gimp) {
             tool: {
                 name: 'gimp_layer',
                 description: 'Headless GIMP: layer management. op: create | create_group | delete | duplicate | ' +
-                    'select | set | move | reorder | merge_down | flatten (a group is created, addressed, ' +
+                    'select | set | reorder | merge_down | flatten (a group is created, addressed, ' +
                     'and reordered the same as any other layer — there is no separate group tool). ' +
                     'Addressed by layer_id (canonical — an id from gimp_inspect or a prior gimp_layer/' +
                     'gimp_bake result) or layer (name; GIMP allows duplicate names, so layer_id is the only ' +
@@ -286,10 +274,7 @@ export function createGimpLayerTools(gimp) {
                     'first when in doubt. duplicate REFUSES outright when the layer (or, for a group, any ' +
                     "descendant) carries an Editmamei filter, since the copy's filter would collide with " +
                     "the original's own ledger record; bake it first (gimp_bake) or delete it, then " +
-                    'duplicate. move takes an ABSOLUTE x/y (not a delta) and REFUSES when the layer, or ' +
-                    'a group containing it, carries a masked or unverifiable adjustment filter — a ' +
-                    "filter's mask does not travel with content that moves beneath it, the same physics " +
-                    'gimp_transform_canvas refuses on. merge_down REFUSES outright when the SOURCE layer ' +
+                    'duplicate. merge_down REFUSES outright when the SOURCE layer ' +
                     'itself is hidden (GIMP cannot merge a hidden layer down); it and ' +
                     'flatten both bake every live filter they touch into pixels first (masked filters ' +
                     'included) and rasterize any VISIBLE text layer in the process (rasterized_text); ' +
@@ -308,8 +293,6 @@ export function createGimpLayerTools(gimp) {
                         opacity: { type: 'number' },
                         mode: { type: 'string' },
                         visible: { type: 'boolean' },
-                        x: { type: ['number', 'null'] },
-                        y: { type: ['number', 'null'] },
                         parent_group: { type: ['number', 'null'] },
                         rasterized_text: { type: 'boolean' },
                         has_alpha: { type: 'boolean' },
@@ -340,9 +323,9 @@ export function createGimpLayerTools(gimp) {
                     'filters; a text layer stays a text layer (baking never rasterizes one). A masked ' +
                     "filter's confinement survives the bake exactly. Defaults to the selected layer, or the " +
                     'topmost layer if none is selected, the same as any other gimp_layer addressing. Baking ' +
-                    'clears any masked-filter refusal (gimp_layer op=move, gimp_canvas, gimp_resize_image, ' +
+                    'clears any masked-filter refusal (gimp_canvas, gimp_resize_image, ' +
                     'gimp_transform_canvas) that filter would otherwise trigger — it is the sanctioned way ' +
-                    'to make a masked adjustment safe to move, resize, rotate, or flip around. all: true ' +
+                    'to make a masked adjustment safe to resize, rotate, or flip around. all: true ' +
                     'bakes every ordinary layer with a live filter at once; a group layer is always skipped, ' +
                     'even one that carries its own filter (GIMP cannot merge filters on a group item) — ' +
                     'reported under skipped_groups_with_filters rather than silently ignored. Targeting a ' +

package/dist/tools/gimp-match-tools.js

@@ -0,0 +1,133 @@
+import { GIMP_IMAGE_PROP, GIMP_LAYER_ID_PROP, GIMP_LAYER_PROP, runGimpTool, } from './gimp-shared.js';
+const matchSchema = {
+    type: 'object',
+    properties: {
+        image: GIMP_IMAGE_PROP,
+        layer: {
+            ...GIMP_LAYER_PROP,
+            description: 'Name of the pasted layer to match. Defaults to the selected layer, or the topmost layer ' +
+                'if none is selected. A layer inside a layer group can be named directly.',
+        },
+        layer_id: GIMP_LAYER_ID_PROP,
+        match: {
+            type: 'string',
+            enum: ['both', 'color', 'tone'],
+            default: 'both',
+            description: "'color' and 'both' write one curves filter each for red, green and blue (matching each " +
+                "channel's mean and spread also matches overall tone, so 'both' adds no separate value " +
+                "curve). 'tone' writes ONE value curve only, which moves brightness and contrast without " +
+                'shifting the colour balance.',
+        },
+        strength: {
+            type: 'number',
+            minimum: 0,
+            maximum: 100,
+            default: 70,
+            description: 'How far to move toward the reference, 0-100. 0 changes nothing (identity curves); 100 ' +
+                'matches the reference mean and spread (contrast gain is limited to 0.5-2x).',
+        },
+        reference: {
+            type: 'string',
+            enum: ['surround', 'below'],
+            default: 'surround',
+            description: "'surround': a ring of the composite beneath, just outside the layer's visible edge " +
+                "(the light the subject sits in). 'below': the whole composite beneath the layer's box.",
+        },
+        surround_px: {
+            type: 'integer',
+            minimum: 1,
+            maximum: 400,
+            description: "reference 'surround' only. Ring width in pixels. Default about 12% of the layer's " +
+                'longer side, clamped to 16-400.',
+        },
+        edge_contract_px: {
+            type: 'integer',
+            minimum: 0,
+            maximum: 20,
+            default: 0,
+            description: "Pull the layer's visible edge in by this many pixels, through its layer mask (one is " +
+                'made from its alpha if it has none) to hide a cut-out fringe. 0 leaves the edge alone.',
+        },
+        edge_feather_px: {
+            type: 'integer',
+            minimum: 0,
+            maximum: 50,
+            default: 0,
+            description: "Soften the layer's visible edge by this many pixels through its layer mask, after any " +
+                "contraction. 0 leaves the edge alone. The layer's own alpha is never changed.",
+        },
+    },
+    required: ['image'],
+};
+export function createGimpMatchTools(gimp) {
+    return [
+        {
+            tool: {
+                name: 'gimp_match_layer',
+                description: 'Headless GIMP: make a pasted or composited layer sit in its scene by pulling its colour ' +
+                    "and tone toward the surrounding pixels. Measures the layer's visible pixels (alpha and " +
+                    'layer mask) against a reference region of everything below it, then adds LIVE curves ' +
+                    'filters named "Match red/green/blue" (match: both or color) or "Match value" (match: ' +
+                    "tone) that move the layer's per-channel mean and spread toward the reference by " +
+                    '`strength`. The filters are ordinary ones: list, hide, re-edit or delete them with ' +
+                    'gimp_filter and gimp_add_adjustment (filter_id); nothing bakes until gimp_export. ' +
+                    'Calling it again REPLACES the previous match filters on that layer instead of stacking ' +
+                    'them. The layer is measured as it renders with its other filters, so run it after the ' +
+                    'layer is placed, cut out and transformed. Optional edge_contract_px / edge_feather_px ' +
+                    'refine the layer mask to hide a cut-out fringe. Refuses a layer group, a text layer ' +
+                    '(bake it first), a locked layer, a layer with no visible layers beneath it, and a ' +
+                    'region with fewer than 500 pixels. The result reports the filters made, each ' +
+                    "channel's before/after mean and std (0-255; `after` is the map's expected value) and " +
+                    'the pixel counts measured.',
+                inputSchema: matchSchema,
+                outputSchema: {
+                    type: 'object',
+                    properties: {
+                        layer: { type: 'string' },
+                        layer_id: { type: 'number' },
+                        match: { type: 'string' },
+                        reference: { type: 'string' },
+                        strength: { type: 'number' },
+                        surround_px: { type: ['number', 'null'] },
+                        filters: { type: 'array' },
+                        replaced_filter_ids: { type: 'array' },
+                        measured: { type: 'object' },
+                        channels: { type: 'object' },
+                        edge: { type: ['object', 'null'] },
+                    },
+                },
+                annotations: {
+                    title: 'Match GIMP Layer To Scene',
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: true,
+                },
+            },
+            handler: async (args) => runGimpTool({
+                gimp,
+                rawArgs: args,
+                schema: matchSchema,
+                op: 'match_layer',
+                errorPrefix: 'Error matching GIMP layer',
+                successText: (result) => {
+                    const r = result;
+                    const moved = Object.entries(r.channels)
+                        .map(([channel, c]) => `${channel} ${c.before.mean.toFixed(0)} -> ${c.after.mean.toFixed(0)} ` +
+                        `(reference ${c.reference.mean.toFixed(0)})`)
+                        .join(', ');
+                    return (`Matched "${r.layer}" to its ${r.reference} at ${r.strength}% (${r.match}): ` +
+                        `${r.filters.length} curves filter(s)` +
+                        (r.replaced_filter_ids.length
+                            ? `, replacing ${r.replaced_filter_ids.length} earlier`
+                            : '') +
+                        `. Means ${moved}.` +
+                        (r.edge
+                            ? ` Edge: contracted ${r.edge.contract_px} px, feathered ${r.edge.feather_px} px via the layer mask.`
+                            : ''));
+                },
+            }),
+        },
+    ];
+}
+export const MATCH_SCHEMA_FOR_TESTS = matchSchema;