editmamei 1.7.0 → 1.8.0

package/dist/tools/adjustment-tools.js

@@ -1,6 +1,7 @@
 import { runScript } from '../utils/run-script.js';
 import { validateArgs } from '../utils/validate.js';
 import { toolErrorResult, runSnippetTool, applyToActiveLayerProp } from '../utils/tool-helpers.js';
+import { looksLikePath, requireLocalPath } from '../utils/local-path.js';
 import { getPendingRawDevelop } from '../core/raw-develop-state.js';
 import { CAMERA_RAW_TOOL } from '../core/tool-activity.js';
 const addAdjustmentLayerSchema = {
@@ -802,6 +803,11 @@ const FORWARDED_KEYS = new Set([
     'pos_levels',
     'thr_level',
 ]);
+function lutNameOrPath(value) {
+    return typeof value === 'string' && looksLikePath(value)
+        ? requireLocalPath('cl_lut_name', value)
+        : value;
+}
 async function addAdjustmentLayer(connection, snippetClient, rawArgs) {
     try {
         const args = validateArgs(addAdjustmentLayerSchema, rawArgs);
@@ -816,6 +822,8 @@ async function addAdjustmentLayer(connection, snippetClient, rawArgs) {
             if (args[key] !== undefined)
                 params[key] = args[key];
         }
+        if (typeof params.cl_lut_name === 'string')
+            params.cl_lut_name = lutNameOrPath(params.cl_lut_name);
         if (type === 'color_lookup' && !params.cl_lut_name) {
             return {
                 content: [
@@ -875,7 +883,7 @@ async function applyColorLookup(connection, snippetClient, rawArgs) {
         snippet: 'applyColorLookup',
         errorPrefix: 'Error applying color lookup',
         params: (args) => ({
-            lutName: args.cl_lut_name,
+            lutName: lutNameOrPath(args.cl_lut_name),
             applyToActiveLayer: args.apply_to_active_layer ?? false,
         }),
         successText: (result) => `Color Lookup applied (BAKE, experimental):\n${JSON.stringify(result, null, 2)}`,

package/dist/tools/document-tools.js

@@ -2,6 +2,7 @@ import { runScript } from '../utils/run-script.js';
 import { validateArgs } from '../utils/validate.js';
 import { OPEN_DOCUMENT_TIMEOUT_MS, OPEN_DOCUMENT_REPROBE_TIMEOUT_MS, } from '../utils/operation-timeouts.js';
 import { toolErrorResult, runSnippetTool } from '../utils/tool-helpers.js';
+import { checkOutputPath, recordOutputPath, requireLocalPath } from '../utils/local-path.js';
 import { purgeSceneChannels } from '../perception/region-precompute.js';
 import { Logger } from '../utils/logger.js';
 const logger = new Logger('document-tools');
@@ -76,7 +77,7 @@ const openDocumentSchema = {
     properties: {
         file_path: {
             type: 'string',
-            description: 'Absolute path to the file to open',
+            description: "Absolute path to the file to open, on this computer's own drives (network shares are refused).",
         },
         suppress_dialogs: {
             type: 'boolean',
@@ -96,7 +97,14 @@ const savePsdSchema = {
     properties: {
         output_path: {
             type: 'string',
-            description: 'Absolute output path including filename, e.g. E:\\Photos\\Edit\\shell_01.psd',
+            description: 'Absolute output path including filename, ending in .psd, e.g. E:\\Photos\\Edit\\shell_01.psd',
+        },
+        overwrite: {
+            type: 'boolean',
+            description: 'Replace an existing file at output_path that this session did not write. Default false: such a ' +
+                'save is refused, so an original is never replaced by accident. Set true only when the user asked ' +
+                'to replace that file. A file this session already wrote can be saved over without it.',
+            default: false,
         },
         maximize_compatibility: {
             type: 'boolean',
@@ -116,7 +124,14 @@ const exportJpegSchema = {
     properties: {
         output_path: {
             type: 'string',
-            description: 'Absolute output path including filename.',
+            description: 'Absolute output path including filename, ending in .jpg.',
+        },
+        overwrite: {
+            type: 'boolean',
+            description: 'Replace an existing file at output_path that this session did not write. Default false: such a ' +
+                'save is refused, so an original is never replaced by accident. Set true only when the user asked ' +
+                'to replace that file. A file this session already wrote can be saved over without it.',
+            default: false,
         },
         quality: {
             type: 'integer',
@@ -149,7 +164,14 @@ const exportPngSchema = {
     properties: {
         output_path: {
             type: 'string',
-            description: 'Absolute output path including filename.',
+            description: 'Absolute output path including filename, ending in .png.',
+        },
+        overwrite: {
+            type: 'boolean',
+            description: 'Replace an existing file at output_path that this session did not write. Default false: such a ' +
+                'save is refused, so an original is never replaced by accident. Set true only when the user asked ' +
+                'to replace that file. A file this session already wrote can be saved over without it.',
+            default: false,
         },
         transparent_background: {
             type: 'boolean',
@@ -531,7 +553,7 @@ async function openDocumentPipeline(connection, snippetClient, rawArgs) {
     let filePath;
     try {
         const args = validateArgs(openDocumentSchema, rawArgs);
-        filePath = args.file_path;
+        filePath = requireLocalPath('file_path', args.file_path);
         const suppressDialogs = args.suppress_dialogs;
         const bitDepth = args.bit_depth;
         const script = await snippetClient.build('openDocumentPipeline', {
@@ -581,8 +603,13 @@ async function openDocumentPipeline(connection, snippetClient, rawArgs) {
 }
 async function savePsdPipeline(connection, snippetClient, rawArgs) {
     let args;
+    let outputPath;
     try {
         args = validateArgs(savePsdSchema, rawArgs);
+        outputPath = checkOutputPath('output_path', args.output_path, {
+            extensions: ['.psd'],
+            overwrite: args.overwrite === true,
+        });
     }
     catch (error) {
         return toolErrorResult('Error saving PSD', error);
@@ -605,11 +632,13 @@ async function savePsdPipeline(connection, snippetClient, rawArgs) {
         snippet: 'savePsdAsCopy',
         errorPrefix: 'Error saving PSD',
         params: (args) => ({
-            outputPath: args.output_path,
+            outputPath,
             maximizeCompat: args.maximize_compatibility,
         }),
         successText: (result) => `PSD saved:\n${JSON.stringify(result, null, 2)}`,
     });
+    if (!res.isError)
+        recordOutputPath(outputPath);
     if (!res.isError && typeof res.structuredContent === 'object' && res.structuredContent !== null) {
         res.structuredContent.scene_channels_purged = purged;
     }
@@ -618,7 +647,10 @@ async function savePsdPipeline(connection, snippetClient, rawArgs) {
 async function exportJpegPipeline(connection, snippetClient, rawArgs) {
     try {
         const args = validateArgs(exportJpegSchema, rawArgs);
-        const outputPath = args.output_path;
+        const outputPath = checkOutputPath('output_path', args.output_path, {
+            extensions: ['.jpg'],
+            overwrite: args.overwrite === true,
+        });
         const qualityPct = args.quality;
         const quality = Math.round((qualityPct / 100) * 12);
         const longEdgePx = args.long_edge_px;
@@ -630,6 +662,7 @@ async function exportJpegPipeline(connection, snippetClient, rawArgs) {
         const script = await snippetClient.build('exportJpegPipeline', params);
         const result = (await runScript(connection, script));
         const structured = { ...result, quality: qualityPct, quality_ps_scale: quality };
+        recordOutputPath(outputPath);
         return {
             content: [
                 {
@@ -645,7 +678,8 @@ async function exportJpegPipeline(connection, snippetClient, rawArgs) {
     }
 }
 async function exportPngPipeline(connection, snippetClient, rawArgs) {
-    return runSnippetTool({
+    let outputPath;
+    const res = await runSnippetTool({
         connection,
         snippetClient,
         rawArgs,
@@ -654,8 +688,12 @@ async function exportPngPipeline(connection, snippetClient, rawArgs) {
         errorPrefix: 'Error exporting PNG',
         params: (args) => {
             const longEdgePx = args.long_edge_px;
+            outputPath = checkOutputPath('output_path', args.output_path, {
+                extensions: ['.png'],
+                overwrite: args.overwrite === true,
+            });
             const params = {
-                outputPath: args.output_path,
+                outputPath,
                 transparentBg: args.transparent_background,
                 compression: args.compression,
             };
@@ -665,4 +703,7 @@ async function exportPngPipeline(connection, snippetClient, rawArgs) {
         },
         successText: (result) => `PNG exported:\n${JSON.stringify(result, null, 2)}`,
     });
+    if (!res.isError && outputPath !== undefined)
+        recordOutputPath(outputPath);
+    return res;
 }

package/dist/tools/filter-tools.js

@@ -3,6 +3,7 @@ import { validateArgs } from '../utils/validate.js';
 import { OnnxLandmarkDetectionClient } from '../detection/landmark-detection-client.js';
 import { resolveGatedPlacement, PLACEMENT_SCHEMA } from '../perception/grounding-locate.js';
 import { toolErrorResult, runSnippetTool, applyToActiveLayerProp, asSmartFilterProp, unknownDiscriminator, } from '../utils/tool-helpers.js';
+import { requireLocalPath } from '../utils/local-path.js';
 import { LAYER_BLEND_MODES } from '../utils/blend-modes.js';
 import { runSmartFilterOp } from './smart-object-tools.js';
 const gaussianBlurSchema = {
@@ -1652,7 +1653,7 @@ async function applyDisplace(connection, snippetClient, rawArgs) {
         snippet: 'applyDisplace',
         errorPrefix: 'Error applying Displace',
         params: (args) => ({
-            mapPath: args.map_path,
+            mapPath: requireLocalPath('map_path', args.map_path),
             horizontalScale: args.horizontal_scale ?? 10,
             verticalScale: args.vertical_scale ?? 10,
             displacementMap: args.displacement_map ?? 'stretch_to_fit',

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

@@ -55,7 +55,7 @@ const adjustSchema = {
         },
         mask: {
             type: 'string',
-            description: 'Name of a mask channel from gimp_create_mask, confining a NEW filter to it. Only valid ' +
+            description: 'Name of a saved selection channel, confining a NEW filter to it. Only valid ' +
                 "when creating (no filter_id) — a filter's mask is fixed at creation. ORDER MATTERS: " +
                 'straighten / flip / resize the canvas first (gimp_transform_canvas, gimp_resize_image), ' +
                 'then crop, THEN add masked adjustments — rotate, flip, and resize all refuse outright ' +
@@ -348,11 +348,11 @@ export function createGimpAdjustmentTools(gimp) {
                     'separate filters for red and blue rather than one filter for both; points are [input, ' +
                     'output] 0-255 pairs including the endpoints. hue_saturation and color_balance likewise ' +
                     'carry ONE `range` per filter. gaussian_blur: radius in pixels at full resolution; ' +
-                    'combine with a mask from gimp_create_mask for soft-focus or background-blur effects. A ' +
+                    'combine with a saved-selection mask for soft-focus or background-blur effects. A ' +
                     "re-edit (filter_id) MERGES: any field you omit keeps the filter's existing value, so " +
                     "re-editing {contrast: 50} on a brightness_contrast filter doesn't reset brightness. Only " +
                     'filters Editmamei created can be re-edited; one added in the GIMP GUI is refused (delete ' +
-                    'and re-create it). `mask` (a channel name from gimp_create_mask) confines a NEW filter ' +
+                    'and re-create it). `mask` (a saved selection channel name) confines a NEW filter ' +
                     '— fixed at creation, cannot change on a re-edit. ORDER MATTERS: straighten / flip / ' +
                     'resize the canvas first, then crop, THEN add any masked adjustment — rotate, flip, and ' +
                     'resize all refuse outright once a masked adjustment filter exists, or any filter not ' +

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

@@ -145,13 +145,12 @@ workflow avoids.
 
 ## Masks
 
-\`gimp_create_mask\` builds a geometric mask (rectangle / ellipse /
-gradient) into a NAMED channel. Pass that name as \`mask\` when you
-CREATE a filter with \`gimp_add_adjustment\` or \`gimp_add_effect\` to
-confine it. A filter's
-mask is fixed at creation — re-editing it by \`filter_id\` cannot
-change which mask it uses; delete and re-create it with a new mask
-instead.
+A selection can be saved into a NAMED channel. Pass the name of a
+channel saved in the image as \`mask\` when you CREATE a filter
+with \`gimp_add_adjustment\` or \`gimp_add_effect\` to confine it.
+A filter's mask is fixed at creation — re-editing it by
+\`filter_id\` cannot change which mask it uses; delete and
+re-create it with a new mask instead.
 
 ## Order matters: geometry before masked adjustments
 
@@ -169,7 +168,7 @@ every geometry op.
 ## Layers and composites
 
 A filter applies to ONE layer. \`gimp_layer\` creates, groups, reorders,
-moves and restyles layers and merges or flattens them;
+and restyles layers and merges or flattens them;
 \`gimp_place_image\` adds another file as a new layer;
 \`gimp_create_document\` starts a blank canvas. Address layers by the
 \`layer_id\` these tools and \`gimp_inspect\` report — names can repeat.

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

@@ -40,7 +40,10 @@ async function gimpOpenDocument(gimp, rawArgs) {
                     type: 'text',
                     text: `Opened ${basename(filePath)} as image ${result.image} ` +
                         `(${result.width}x${result.height}, ${result.base_type}, ${result.precision}). ` +
-                        `${result.layers.length} layer(s): ${result.layers.join(', ') || '(none)'}.`,
+                        `${result.layers.length} layer(s): ${result.layers.join(', ') || '(none)'}.` +
+                        (result.orientation_applied !== undefined
+                            ? ` Rotated upright for EXIF orientation ${result.orientation_applied}.`
+                            : ''),
                 },
             ],
             structuredContent: result,

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

@@ -41,7 +41,7 @@ const effectSchema = {
         layer_id: GIMP_LAYER_ID_PROP,
         mask: {
             type: 'string',
-            description: 'Name of a mask channel from gimp_create_mask, confining a NEW filter to it. Only valid ' +
+            description: 'Name of a saved selection channel, confining a NEW filter to it. Only valid ' +
                 "when creating (no filter_id) — a filter's mask is fixed at creation. ORDER MATTERS: " +
                 'straighten / flip / resize the canvas first (gimp_transform_canvas, gimp_resize_image), ' +
                 'then crop, THEN add masked effects — rotate, flip, and resize all refuse outright once ' +
@@ -230,7 +230,7 @@ export function createGimpEffectTools(gimp) {
                     'or `layer`, else the selected or top layer), not to the flattened image. A re-edit ' +
                     "(filter_id) MERGES: any field you omit keeps the filter's existing value. Only " +
                     'filters Editmamei created can be re-edited; one added in the GIMP GUI is refused ' +
-                    '(delete and re-create it). `mask` (a channel name from gimp_create_mask) confines a ' +
+                    '(delete and re-create it). `mask` (a saved selection channel name) confines a ' +
                     'NEW filter — fixed at creation, cannot change on a re-edit. ORDER MATTERS: straighten ' +
                     '/ flip / resize the canvas first, then crop, THEN add any masked effect — rotate, ' +
                     'flip, and resize all refuse outright once a masked filter exists, or any filter not ' +

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,7 @@
 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'];
+const INSPECT_WHATS = ['documents', 'document', 'layers', 'channels', 'filter', 'fonts'];
 const inspectSchema = {
     type: 'object',
     properties: {
@@ -20,12 +20,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',
@@ -75,6 +82,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 +123,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 +136,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 ' +
@@ -139,14 +135,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 +157,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 +263,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 +272,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 +291,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 +321,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;