editmamei 1.7.1 → 1.8.0

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;

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

@@ -0,0 +1,374 @@
+import { randomUUID } from 'node:crypto';
+import { rm } from 'node:fs/promises';
+import { validateArgs } from '../utils/validate.js';
+import { toolGimpErrorResult } from '../utils/tool-helpers.js';
+import { GIMP_IMAGE_PROP, GIMP_LAYER_ID_PROP, GIMP_LAYER_PROP, GIMP_MAX_PX_PROP, readRender, defaultPreviewsAllowed, pickSchemaDeclaredKeys, runGimpTool, } from './gimp-shared.js';
+const maskResultSchema = {
+    type: 'object',
+    properties: {
+        channel: { type: 'string' },
+        selected_pixels: { type: 'number' },
+        fraction: { type: 'number' },
+    },
+};
+const maskText = (result) => {
+    const r = result;
+    return `Channel "${r.channel}" — ${(r.fraction * 100).toFixed(1)}% of pixels selected.`;
+};
+const layerMaskResultSchema = {
+    type: 'object',
+    properties: {
+        layer: { type: 'string' },
+        layer_id: { type: 'integer' },
+        op: { type: 'string' },
+        has_mask: { type: 'boolean' },
+    },
+};
+const selectionPreviewResultSchema = {
+    type: 'object',
+    properties: {
+        width: { type: 'number' },
+        height: { type: 'number' },
+    },
+};
+const selectSchema = {
+    type: 'object',
+    properties: {
+        image: GIMP_IMAGE_PROP,
+        mode: {
+            type: 'string',
+            enum: [
+                'all',
+                'rectangle',
+                'ellipse',
+                'polygon',
+                'color_range',
+                'magic_wand',
+                'alpha',
+                'channel',
+                'gradient_linear',
+                'gradient_radial',
+            ],
+            description: 'rectangle/ellipse: x, y, width, height. polygon: points (>=3 [x,y] pairs). color_range: ' +
+                'every pixel near `color` (hex) or the colour at a sample point x,y, anywhere in the ' +
+                "image. magic_wand: the contiguous region around x,y. alpha: a layer's opaque pixels. " +
+                'channel: copy another saved selection (`source`). gradient_linear: a ramp from (x1,y1) ' +
+                'to (x2,y2), default the full image width. gradient_radial: a ramp from full effect at ' +
+                "the center (cx,cy) fading to none at radius, default centered at the image's own center " +
+                'with radius = half the shorter side.',
+        },
+        name: {
+            type: 'string',
+            default: 'Selection',
+            minLength: 1,
+            description: 'Channel to save the selection in (replaced).',
+        },
+        combine: {
+            type: 'string',
+            enum: ['replace', 'add', 'subtract', 'intersect'],
+            default: 'replace',
+            description: 'Combine with the existing saved selection of the same `name` (like shift/alt in a ' +
+                'GUI). `invert`/`feather_px` apply to the NEW shape alone, before it is combined.',
+        },
+        x: {
+            type: 'number',
+            description: "rectangle/ellipse/magic_wand, or color_range's sample point: left edge or point x, in " +
+                'image pixels from the canvas origin, also when `layer` names a layer that sits at an ' +
+                "offset (never counted from that layer's own corner).",
+        },
+        y: {
+            type: 'number',
+            description: "rectangle/ellipse/magic_wand, or color_range's sample point: top edge or point y, in " +
+                'image pixels from the canvas origin, also when `layer` names a layer that sits at an ' +
+                "offset (never counted from that layer's own corner).",
+        },
+        width: { type: 'number', description: 'rectangle/ellipse: width, document pixels.' },
+        height: { type: 'number', description: 'rectangle/ellipse: height, document pixels.' },
+        points: {
+            type: 'array',
+            minItems: 3,
+            maxItems: 10_000,
+            items: { type: 'array', minItems: 2, maxItems: 2, items: { type: 'number' } },
+            description: 'polygon: 3-10,000 [x, y] pairs, document pixels.',
+        },
+        color: {
+            type: 'string',
+            pattern: '^#[0-9a-fA-F]{6}$',
+            description: 'color_range: a hex colour like "#c0392b".',
+        },
+        threshold: {
+            type: 'number',
+            minimum: 0,
+            maximum: 255,
+            default: 15,
+            description: 'color_range/magic_wand tolerance, 0-255.',
+        },
+        sample_merged: {
+            type: 'boolean',
+            default: true,
+            description: 'color_range/magic_wand: sample the visible composite. false samples the one named/' +
+                "selected layer's own raw pixels instead.",
+        },
+        source: {
+            type: 'string',
+            minLength: 1,
+            description: 'mode=channel: the saved selection to copy.',
+        },
+        layer: {
+            ...GIMP_LAYER_PROP,
+            description: GIMP_LAYER_PROP.description +
+                ' alpha: which layer. color_range/magic_wand: only matters when sample_merged:false ' +
+                '(otherwise the visible composite is sampled, and which layer this names makes no ' +
+                'difference to the result).',
+        },
+        layer_id: {
+            ...GIMP_LAYER_ID_PROP,
+            description: GIMP_LAYER_ID_PROP.description +
+                ' alpha: which layer. color_range/magic_wand: only matters when sample_merged:false.',
+        },
+        invert: {
+            type: 'boolean',
+            default: false,
+            description: 'Applied to the NEW shape alone, before any `combine`. rectangle/ellipse/polygon/' +
+                'color_range/magic_wand/alpha/channel: invert the selection. gradient_linear/' +
+                'gradient_radial: swap which end is black vs white.',
+        },
+        feather_px: {
+            type: 'number',
+            minimum: 0,
+            maximum: 1000,
+            default: 0,
+            description: 'Feather radius in document pixels, applied to the NEW shape alone before any `combine`. ' +
+                'Refused (nonzero) on gradient_linear/gradient_radial -- already a continuous ramp, ' +
+                'nothing to feather.',
+        },
+        x1: {
+            type: 'number',
+            description: 'gradient_linear: start point x, document pixels. Default 0.',
+        },
+        y1: {
+            type: 'number',
+            description: 'gradient_linear: start point y, document pixels. Default 0.',
+        },
+        x2: {
+            type: 'number',
+            description: "gradient_linear: end point x, document pixels. Default the image's width.",
+        },
+        y2: {
+            type: 'number',
+            description: 'gradient_linear: end point y, document pixels. Default 0.',
+        },
+        cx: {
+            type: 'number',
+            description: "gradient_radial: center x, document pixels. Default the image's own center.",
+        },
+        cy: {
+            type: 'number',
+            description: "gradient_radial: center y, document pixels. Default the image's own center.",
+        },
+        radius: {
+            type: 'number',
+            description: 'gradient_radial: radius, document pixels. Default half the shorter image side.',
+        },
+    },
+    required: ['image', 'mode'],
+};
+const modifySelectionSchema = {
+    type: 'object',
+    properties: {
+        image: GIMP_IMAGE_PROP,
+        channel: { type: 'string', minLength: 1, description: 'The saved selection to modify.' },
+        op: {
+            type: 'string',
+            enum: ['expand', 'contract', 'border', 'feather', 'smooth', 'invert', 'harden'],
+            description: 'expand/contract/border/feather require `px` (> 0). harden: threshold a soft mask at ' +
+                '50%. smooth: round off jagged edges (`px` optional, floors at 1px).',
+        },
+        px: {
+            type: 'number',
+            minimum: 0,
+            maximum: 1000,
+            description: 'Radius in document pixels, rounded to the nearest whole pixel. Required (> 0) for ' +
+                'expand/contract/border/feather; optional for smooth; unused otherwise. expand/contract/' +
+                'border cap at 150 on an ordinary document, LOWER on a very large one (morphological ' +
+                "ops whose cost scales with both the radius and the document's own megapixels — the " +
+                'error names the actual cap for that document when a value is refused); feather has no ' +
+                'such cap up to 1000 (a GEGL blur, flat cost regardless of radius).',
+        },
+        output: {
+            type: 'string',
+            minLength: 1,
+            description: 'Write to this saved selection instead of modifying `channel` in place.',
+        },
+    },
+    required: ['image', 'channel', 'op'],
+};
+const layerMaskSchema = {
+    type: 'object',
+    properties: {
+        image: GIMP_IMAGE_PROP,
+        op: {
+            type: 'string',
+            enum: ['create', 'delete', 'apply', 'invert'],
+            description: "create replaces any existing mask. apply bakes the mask into the layer's alpha.",
+        },
+        source: {
+            type: 'string',
+            enum: ['channel', 'white', 'black', 'alpha', 'grayscale'],
+            default: 'channel',
+            description: 'create: where the mask comes from.',
+        },
+        channel: {
+            type: 'string',
+            minLength: 1,
+            description: 'source=channel: the saved selection to use.',
+        },
+        invert: { type: 'boolean', default: false, description: 'create: invert the new mask.' },
+        layer: GIMP_LAYER_PROP,
+        layer_id: GIMP_LAYER_ID_PROP,
+    },
+    required: ['image', 'op'],
+};
+const selectionPreviewSchema = {
+    type: 'object',
+    properties: {
+        image: GIMP_IMAGE_PROP,
+        channel: { type: 'string', minLength: 1, description: 'The saved selection to show.' },
+        style: {
+            type: 'string',
+            enum: ['overlay', 'mask'],
+            default: 'overlay',
+            description: 'overlay: the image with red over what is NOT selected. mask: white = selected.',
+        },
+        max_px: GIMP_MAX_PX_PROP,
+    },
+    required: ['image', 'channel'],
+};
+async function selectionPreview(gimp, rawArgs, previewsAllowedFn) {
+    try {
+        const args = validateArgs(selectionPreviewSchema, rawArgs);
+        await gimp.prepare();
+        const out = gimp.tempPath(`selection-preview-${randomUUID()}.jpg`);
+        try {
+            const bridgeArgs = pickSchemaDeclaredKeys(selectionPreviewSchema, args);
+            const r = await gimp.call('mask_preview', { ...bridgeArgs, out_path: out });
+            const allowed = previewsAllowedFn();
+            const content = [];
+            if (allowed) {
+                const bytes = await readRender(out);
+                content.push({
+                    type: 'image',
+                    data: bytes.toString('base64'),
+                    mimeType: 'image/jpeg',
+                });
+            }
+            const unmirroredNote = r.unmirrored_filters && r.unmirrored_filters.length > 0
+                ? ` WARNING: ${r.unmirrored_filters.join(', ')} could not be rendered on this proxy and ` +
+                    `${r.unmirrored_filters.length === 1 ? 'is' : 'are'} missing from it.`
+                : '';
+            content.push({
+                type: 'text',
+                text: `Selection "${String(args.channel)}" ${r.width}x${r.height}.` +
+                    (allowed
+                        ? ''
+                        : ' privacy.send_previews_to_llm is false — image not returned to the model.') +
+                    unmirroredNote,
+            });
+            return { content, structuredContent: { width: r.width, height: r.height } };
+        }
+        finally {
+            await rm(out, { force: true }).catch(() => undefined);
+        }
+    }
+    catch (error) {
+        return toolGimpErrorResult('Error previewing GIMP selection', error);
+    }
+}
+const annotations = (title, readOnly = false) => ({
+    title,
+    readOnlyHint: readOnly,
+    destructiveHint: !readOnly,
+    idempotentHint: false,
+    openWorldHint: true,
+});
+export function createGimpSelectionTools(gimp, deps = {}) {
+    const previewsAllowedFn = deps.previewsAllowed ?? defaultPreviewsAllowed;
+    return [
+        {
+            tool: {
+                name: 'gimp_select',
+                description: 'Headless GIMP: make a selection, saved as a NAMED channel (no live selection ' +
+                    'persists between calls): rectangle/ellipse/polygon/colour range/magic wand/layer ' +
+                    'alpha/gradient/another channel. Combine add/subtract/intersect by reusing a name. ' +
+                    "Use the channel as gimp_add_adjustment's " +
+                    '`mask` when creating a filter, or gimp_layer_mask for a real layer mask. Make ' +
+                    'selections after straighten/resize/crop.',
+                inputSchema: selectSchema,
+                outputSchema: maskResultSchema,
+                annotations: annotations('Select (GIMP)'),
+            },
+            handler: (args) => runGimpTool({
+                gimp,
+                rawArgs: args,
+                schema: selectSchema,
+                op: 'select',
+                errorPrefix: 'Error selecting',
+                successText: maskText,
+            }),
+        },
+        {
+            tool: {
+                name: 'gimp_modify_selection',
+                description: 'Headless GIMP: expand, contract, border, feather, smooth, invert or harden a saved ' +
+                    'selection. Refused if the target channel already confines a filter.',
+                inputSchema: modifySelectionSchema,
+                outputSchema: maskResultSchema,
+                annotations: annotations('Modify Selection (GIMP)'),
+            },
+            handler: (args) => runGimpTool({
+                gimp,
+                rawArgs: args,
+                schema: modifySelectionSchema,
+                op: 'modify_mask',
+                errorPrefix: 'Error modifying selection',
+                successText: maskText,
+            }),
+        },
+        {
+            tool: {
+                name: 'gimp_layer_mask',
+                description: 'Headless GIMP: a real layer mask (moves with the layer). create from a saved ' +
+                    'selection (e.g. from gimp_select) or white/black/alpha/grayscale; delete; apply (bake ' +
+                    'into alpha — a cut-out); invert. For a cut-out composite: place the photo as a ' +
+                    'layer, select on that layer, then create its mask from the channel.',
+                inputSchema: layerMaskSchema,
+                outputSchema: layerMaskResultSchema,
+                annotations: annotations('Layer Mask (GIMP)'),
+            },
+            handler: (args) => runGimpTool({
+                gimp,
+                rawArgs: args,
+                schema: layerMaskSchema,
+                op: 'layer_mask',
+                errorPrefix: 'Error on layer mask',
+                successText: (r) => {
+                    const x = r;
+                    return `Layer "${x.layer}": ${x.op} done (${x.has_mask ? 'has' : 'no'} mask).`;
+                },
+            }),
+        },
+        {
+            tool: {
+                name: 'gimp_get_selection_preview',
+                description: 'Headless GIMP: see a saved selection — overlay (red over what is NOT selected, Quick ' +
+                    'Mask style) or the mask itself. Always check a selection before using it. Respects ' +
+                    'privacy.send_previews_to_llm: when disabled, no image bytes are returned, only the ' +
+                    'dimensions.',
+                inputSchema: selectionPreviewSchema,
+                outputSchema: selectionPreviewResultSchema,
+                annotations: annotations('Selection Preview (GIMP)', true),
+            },
+            handler: (args) => selectionPreview(gimp, args, previewsAllowedFn),
+        },
+    ];
+}

package/dist/tools/gimp-shared.js

@@ -1,3 +1,6 @@
+import { readFile } from 'node:fs/promises';
+import { loadSettings } from '../core/settings.js';
+import { GimpError } from '../backends/gimp/errors.js';
 import { validateArgs } from '../utils/validate.js';
 import { toolGimpErrorResult } from '../utils/tool-helpers.js';
 export const GIMP_IMAGE_PROP = {
@@ -42,6 +45,15 @@ export function pickSchemaDeclaredKeys(schema, args) {
     }
     return out;
 }
+export async function readRender(path) {
+    try {
+        return await readFile(path);
+    }
+    catch {
+        throw new GimpError('gimp_op_failed', 'GIMP reported success but the render was not written');
+    }
+}
+export const defaultPreviewsAllowed = () => loadSettings().settings.privacy.send_previews_to_llm;
 export async function runGimpTool(spec) {
     try {
         const args = validateArgs(spec.schema, spec.rawArgs);