editmamei 1.8.0 → 1.9.0

package/dist/core/server.js

@@ -66,6 +66,14 @@ export const FIRST_RUN_DISCLOSURE = 'First run: Editmamei collects content-free
     '`editmamei config set telemetry.usage false` (or edit ~/.editmamei/settings.json). ' +
     'Opt in to sanitized diagnostics: `editmamei config set telemetry.diagnostics true`.';
 export const BACKGROUND_VERSION_PROBE_TIMEOUT_MS = 3_000;
+const PING_ROUND_TRIP_CLASSES = new Set([
+    'timeout',
+    'ps_modal_blocking',
+    'ps_not_running',
+    'ps_general_error',
+    'file_io',
+]);
+const PHOTOSHOP_PATH_DOCS_URL = 'https://github.com/editmamei/editmamei/blob/main/docs/installation.md#optional-pin-a-specific-photoshop-install';
 export class EditmameiServer {
     server;
     logger;
@@ -83,6 +91,7 @@ export class EditmameiServer {
     }
     psVersion = null;
     lastPingReachedPs = null;
+    lastPingFailure = null;
     lastTelemetryCallKeyHash = null;
     lastPsLocale = null;
     lastDocDepth = null;
@@ -169,8 +178,13 @@ export class EditmameiServer {
                 });
                 const telemetrySuccess = entry.tool === 'ps_ping' && this.lastPingReachedPs === false ? false : entry.success;
                 const isPingDowngrade = entry.tool === 'ps_ping' && !telemetrySuccess && entry.error === undefined;
+                const pingFailure = isPingDowngrade ? this.lastPingFailure : null;
                 const errorClass = classifyError(entry.error) ??
-                    (telemetrySuccess ? null : isPingDowngrade ? 'ps_not_running' : NO_ERROR_TEXT_CLASS);
+                    (telemetrySuccess
+                        ? null
+                        : isPingDowngrade
+                            ? (pingFailure?.errorClass ?? 'ps_not_running')
+                            : NO_ERROR_TEXT_CLASS);
                 const telemetryCallKeyHash = hashRetryKey(entry.tool, entry.args);
                 const isTelemetryRetry = telemetryCallKeyHash !== null && telemetryCallKeyHash === this.lastTelemetryCallKeyHash;
                 if (telemetryCallKeyHash !== null)
@@ -189,7 +203,7 @@ export class EditmameiServer {
                         error_class: errorClass ?? NO_ERROR_TEXT_CLASS,
                         error_message: entry.error ||
                             (isPingDowngrade
-                                ? 'ps_ping did not reach Photoshop'
+                                ? (pingFailure?.message ?? 'ps_ping did not reach Photoshop')
                                 : 'tool reported failure with no message'),
                         ...(this.lastPsLocale !== null ? { ps_locale: this.lastPsLocale } : {}),
                         ...(this.lastDocDepth !== null ? { doc_depth: this.lastDocDepth } : {}),
@@ -493,8 +507,15 @@ export class EditmameiServer {
             }
         })();
     }
+    markPingUnreachable(errorClass, message) {
+        this.lastPingReachedPs = false;
+        this.lastPingFailure = { errorClass, message };
+        this.lastDocDepth = null;
+        this.lastDocMode = null;
+    }
     async pingPhotoshop() {
         this.lastPingReachedPs = null;
+        this.lastPingFailure = null;
         this.refreshLicenseOnPing();
         if (this.updateCheck)
             await this.updateCheck;
@@ -515,17 +536,41 @@ export class EditmameiServer {
         const degraded = [];
         let versionIsLive = false;
         let pingStateObserved = false;
+        let detectError = null;
         try {
             const detected = await connection.getVersion();
             if (detected)
                 version = detected;
         }
-        catch {
+        catch (err) {
+            detectError = err instanceof Error ? err.message : String(err);
+        }
+        if (connection.getPhotoshopInfo() === null && unsupportedHostReason() === null) {
+            this.markPingUnreachable('ps_not_detected', detectError ?? 'No Photoshop install was detected');
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: withAdvisory('Editmamei could not find a Photoshop install on this computer. Photoshop must be ' +
+                            'installed on the same computer as Editmamei. ' +
+                            (process.env.PHOTOSHOP_PATH?.trim()
+                                ? 'PHOTOSHOP_PATH is set, but does not point at a Photoshop install: check it '
+                                : 'If it is installed in a custom location, set PHOTOSHOP_PATH to its full path ') +
+                            "in your MCP client's Editmamei config (see " +
+                            PHOTOSHOP_PATH_DOCS_URL +
+                            '), restart the client, then call ps_ping again.' +
+                            update.note),
+                    },
+                ],
+                structuredContent: {
+                    connected: false,
+                    update_available: this.updateInfo,
+                    notify_user: update.notify,
+                },
+            };
         }
         if (connection.getPhotoshopInfo() !== null && !(await connection.isCurrentlyRunning())) {
-            this.lastPingReachedPs = false;
-            this.lastDocDepth = null;
-            this.lastDocMode = null;
+            this.markPingUnreachable('ps_not_running', 'Photoshop is installed but no Photoshop process is running');
             return {
                 content: [
                     {
@@ -550,9 +595,7 @@ export class EditmameiServer {
             const alive = await connection.ping().catch(() => false);
             if (!alive) {
                 const reason = unsupportedHostReason();
-                this.lastPingReachedPs = false;
-                this.lastDocDepth = null;
-                this.lastDocMode = null;
+                this.markPingUnreachable('ps_not_running', reason ?? 'pingState snippet build failed and the fallback ping did not reach Photoshop');
                 return {
                     content: [
                         {
@@ -575,10 +618,12 @@ export class EditmameiServer {
                 state = (await runScript(connection, pingStateSnippet));
             }
             catch (err) {
-                this.logger.warn(`pingState snippet failed: ${err instanceof Error ? err.message : String(err)}`);
-                this.lastPingReachedPs = false;
-                this.lastDocDepth = null;
-                this.lastDocMode = null;
+                const message = err instanceof Error ? err.message : String(err);
+                this.logger.warn(`pingState snippet failed: ${message}`);
+                const errorClass = classifyError(message);
+                this.markPingUnreachable(errorClass !== null && PING_ROUND_TRIP_CLASSES.has(errorClass)
+                    ? errorClass
+                    : 'ps_not_running', message);
                 return {
                     content: [
                         {

package/dist/core/tool-activity.js

@@ -129,6 +129,8 @@ export const MUTATING_TOOLS = new Set([
     'gimp_layer_mask',
     'gimp_transform_layer',
     'gimp_match_layer',
+    'gimp_retouch',
+    'gimp_fill',
 ]);
 export const RAW_DEVELOP_TOOL = 'ps_develop_raw';
 export const CAMERA_RAW_TOOL = 'ps_apply_camera_raw';

package/dist/core/tool-groups.js

@@ -201,6 +201,8 @@ export const TOOL_GROUPS = {
     gimp_layer_mask: 'masks',
     gimp_get_selection_preview: 'verify',
     gimp_match_layer: 'layers',
+    gimp_retouch: 'layers',
+    gimp_fill: 'layers',
 };
 export function groupOf(toolName) {
     const group = TOOL_GROUPS[toolName];

package/dist/core/tool-tiers.js

@@ -115,10 +115,12 @@ export const TOOL_TIERS = {
     gimp_text: 'community',
     gimp_convert_image_mode: 'community',
     gimp_select: 'community',
-    gimp_modify_selection: 'dev',
+    gimp_modify_selection: 'community',
     gimp_layer_mask: 'community',
     gimp_get_selection_preview: 'community',
     gimp_match_layer: 'dev',
+    gimp_retouch: 'dev',
+    gimp_fill: 'dev',
 };
 export function tierOf(toolName) {
     const tier = TOOL_TIERS[toolName];

package/dist/delivery/client.js

@@ -157,6 +157,9 @@ export class DeliveryClient {
         if (status === 404) {
             return new DeliveryError('Requested module/version was not found.', 404, 'not_found');
         }
+        if (status === 451) {
+            return new DeliveryError("Editmamei Pro downloads aren't available in your region.", 451, 'unavailable_in_region');
+        }
         return new DeliveryError(`Delivery request failed (HTTP ${status}).`, status, 'server', retryAfterMs);
     }
 }

package/dist/modules/gimp/index.js

@@ -16,6 +16,8 @@ import { createGimpComposeTools } from '../../tools/gimp-compose-tools.js';
 import { createGimpTextTools } from '../../tools/gimp-text-tools.js';
 import { createGimpSelectionTools } from '../../tools/gimp-selection-tools.js';
 import { createGimpMatchTools } from '../../tools/gimp-match-tools.js';
+import { createGimpRetouchTools } from '../../tools/gimp-retouch-tools.js';
+import { createGimpFillTools } from '../../tools/gimp-fill-tools.js';
 export const gimpFactories = [
     createGimpCoreTools,
     createGimpDocumentTools,
@@ -32,6 +34,8 @@ export const gimpFactories = [
     createGimpTextTools,
     createGimpSelectionTools,
     createGimpMatchTools,
+    createGimpRetouchTools,
+    createGimpFillTools,
 ];
 export const gimpModule = {
     manifest: { id: 'gimp', name: 'Editmamei GIMP Tools', abi: KERNEL_ABI },

package/dist/tools/document-tools.js

@@ -1,6 +1,7 @@
+import { statSync } from 'node:fs';
 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 { OPEN_DOCUMENT_TIMEOUT_MS, OPEN_DOCUMENT_REPROBE_TIMEOUT_MS, SAVE_PSD_REPROBE_TIMEOUT_MS, getToolTimeoutMs, } 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';
@@ -349,6 +350,15 @@ export function createDocumentTools(connection, snippetClient) {
                         saved_to: { type: 'string' },
                         document_name: { type: 'string' },
                         layers: { type: 'number' },
+                        reprobed: {
+                            type: 'boolean',
+                            description: 'Present when the save outran its time budget and a follow-up check confirmed the file was written. document_name, layers and context are absent then.',
+                        },
+                        bytes: {
+                            type: 'number',
+                            description: 'Size of the written file. Present only with reprobed.',
+                        },
+                        scene_channels_purged: { type: 'number' },
                         context: { type: 'object' },
                     },
                     required: ['success'],
@@ -601,6 +611,40 @@ async function openDocumentPipeline(connection, snippetClient, rawArgs) {
         return toolErrorResult('Error opening document', error);
     }
 }
+async function reprobeSavedPsd(connection, outputPath, startedAt) {
+    try {
+        await runScript(connection, 'return { ready: true };', SAVE_PSD_REPROBE_TIMEOUT_MS);
+    }
+    catch {
+        return null;
+    }
+    let size;
+    let modifiedMs;
+    try {
+        const stats = statSync(outputPath);
+        if (!stats.isFile())
+            return null;
+        size = stats.size;
+        modifiedMs = stats.mtimeMs;
+    }
+    catch {
+        return null;
+    }
+    if (size === 0 || modifiedMs < startedAt - 2_000)
+        return null;
+    const payload = { success: true, saved_to: outputPath, bytes: size, reprobed: true };
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `PSD saved (the save ran past the ${getToolTimeoutMs('ps_save_psd')}ms budget and was reported as a ` +
+                    `timeout, but a post-timeout check confirmed the file was written):\n` +
+                    JSON.stringify(payload, null, 2),
+            },
+        ],
+        structuredContent: payload,
+    };
+}
 async function savePsdPipeline(connection, snippetClient, rawArgs) {
     let args;
     let outputPath;
@@ -624,19 +668,31 @@ async function savePsdPipeline(connection, snippetClient, rawArgs) {
                 `${err instanceof Error ? err.message : String(err)}`);
         }
     }
-    const res = await runSnippetTool({
-        connection,
-        snippetClient,
-        rawArgs,
-        schema: savePsdSchema,
-        snippet: 'savePsdAsCopy',
-        errorPrefix: 'Error saving PSD',
-        params: (args) => ({
+    const startedAt = Date.now();
+    let res;
+    try {
+        const script = await snippetClient.build('savePsdAsCopy', {
             outputPath,
             maximizeCompat: args.maximize_compatibility,
-        }),
-        successText: (result) => `PSD saved:\n${JSON.stringify(result, null, 2)}`,
-    });
+        });
+        const result = await runScript(connection, script, getToolTimeoutMs('ps_save_psd'));
+        res = {
+            content: [{ type: 'text', text: `PSD saved:\n${JSON.stringify(result, null, 2)}` }],
+            structuredContent: result,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (isScriptTimeoutError(message)) {
+            res =
+                (await reprobeSavedPsd(connection, outputPath, startedAt)) ??
+                    toolErrorResult('Error saving PSD', new Error(`${message} Photoshop may still be writing the file: check whether ${outputPath} ` +
+                        'was just modified before saving again.'));
+        }
+        else {
+            res = toolErrorResult('Error saving PSD', error);
+        }
+    }
     if (!res.isError)
         recordOutputPath(outputPath);
     if (!res.isError && typeof res.structuredContent === 'object' && res.structuredContent !== null) {

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

@@ -278,9 +278,10 @@ const adjustSchema = {
             maximum: 100,
             description: 'vibrance only. THE vibrance control — a vibrance adjustment must set this field, not ' +
                 '`saturation` (a separate, plain multiplier for this type that normally stays at its ' +
-                'default). Positive values boost muted/less-saturated colours more than already-saturated ' +
-                'ones (skin tones move less than a bright sky); negative desaturates the same way in ' +
-                'reverse. Default (when creating): 0.',
+                "default). The scale follows Photoshop's Vibrance: +10 to +30 is a natural boost, +50 a " +
+                "strong one; negative values desaturate. Unlike Photoshop's, it lifts already-saturated " +
+                'colors (a blue sky, a bright shirt) about as much as muted ones, so check those areas ' +
+                'with a histogram above about +50. Default (when creating): 0.',
         },
         amount: {
             type: 'number',

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

@@ -6,6 +6,7 @@ import { validateArgs } from '../utils/validate.js';
 import { toolGimpErrorResult, unknownDiscriminator } from '../utils/tool-helpers.js';
 import { GimpError } from '../backends/gimp/errors.js';
 import { GIMP_IMAGE_PROP } from './gimp-shared.js';
+import { capLines, quoted } from './gimp-result-text.js';
 export const MAX_CHECKPOINTS_PER_IMAGE = 5;
 export const MAX_CHECKPOINTS_TOTAL = 20;
 const checkpointSchema = {
@@ -303,7 +304,12 @@ async function checkpointList(gimp, args, store) {
         content: [
             {
                 type: 'text',
-                text: `${checkpoints.length} checkpoint(s)${scopedNote}.${goneNote}`,
+                text: `${checkpoints.length} checkpoint(s)${scopedNote}.${goneNote}` +
+                    capLines(checkpoints.map((c) => `- ${quoted(c.checkpoint_id)}: image ${c.image}` +
+                        `${c.open ? '' : ' (gone)'}${c.pending ? ', still being created' : ''}, ` +
+                        `${c.created_at}, ${c.bytes.toLocaleString('en-US')} bytes`))
+                        .map((line) => `\n${line}`)
+                        .join(''),
             },
         ],
         structuredContent: { checkpoints },

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

@@ -90,9 +90,9 @@ in the real GIMP GUI afterward to see it directly.
    stacking a second one for the same correction (see "Curve laws"
    below).
 6. **Finish** — \`gimp_save_xcf\` keeps every filter live and
-   re-editable; \`gimp_export\` writes a flattened deliverable. Do both
-   when the user wants to keep working on it later AND ship a JPEG/PNG
-   now.
+   re-editable; \`gimp_export\` writes a flattened deliverable, or a
+   layered .psd for finishing in Photoshop. Do both when the user wants
+   to keep working on it later AND ship a JPEG/PNG now.
 
 ## Curve laws (gimp_add_adjustment type=curves)
 

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

@@ -66,7 +66,7 @@ const saveXcfSchema = {
             type: 'string',
             description: 'Absolute path ending in .xcf. Saves the LIVE GIMP document — every filter stays in ' +
                 "place and re-editable afterward (matches ps_save_psd's framing for .psd). For a " +
-                'flattened deliverable, use gimp_export instead.',
+                'deliverable (flattened, or a layered .psd), use gimp_export instead.',
         },
         overwrite: {
             type: 'boolean',
@@ -81,7 +81,7 @@ async function gimpSaveXcf(gimp, rawArgs) {
         const args = validateArgs(saveXcfSchema, rawArgs);
         const filePath = requireAbsoluteGimpPath('file_path', args.file_path);
         if (extname(filePath).toLowerCase() !== '.xcf') {
-            throw new GimpError('invalid_argument', `"file_path" must end in .xcf, got "${filePath}" — use gimp_export for a flattened deliverable.`);
+            throw new GimpError('invalid_argument', `"file_path" must end in .xcf, got "${filePath}" — use gimp_export for a deliverable.`);
         }
         refuseExistingGimpFile(filePath, args.overwrite, existsSync);
         const result = await gimp.call('export', {
@@ -102,16 +102,22 @@ async function gimpSaveXcf(gimp, rawArgs) {
         return toolGimpErrorResult('Error saving GIMP document', error);
     }
 }
-const EXPORT_FORMAT_EXTENSIONS = ['.jpg', '.jpeg', '.png', '.webp', '.tif', '.tiff'];
+const FLAT_EXPORT_FORMAT_EXTENSIONS = ['.jpg', '.jpeg', '.png', '.webp', '.tif', '.tiff'];
+const LAYERED_EXPORT_FORMAT_EXTENSIONS = ['.psd'];
+const EXPORT_FORMAT_EXTENSIONS = [
+    ...FLAT_EXPORT_FORMAT_EXTENSIONS,
+    ...LAYERED_EXPORT_FORMAT_EXTENSIONS,
+];
 const exportSchema = {
     type: 'object',
     properties: {
         image: GIMP_IMAGE_PROP,
         file_path: {
             type: 'string',
-            description: 'Absolute path. The extension picks the format: jpg/jpeg, png, webp, tif/tiff. Refuses ' +
-                ".xcf outright — that is gimp_save_xcf's job. Metadata (EXIF/XMP/IPTC/GPS, thumbnail) is " +
-                'ALWAYS stripped on export, unconditionally — never carried over from the source.',
+            description: 'Absolute path. The extension picks the format: jpg/jpeg, png, webp, tif/tiff (flattened), ' +
+                "or psd (layered). Refuses .xcf outright — that is gimp_save_xcf's job. Metadata " +
+                '(EXIF/XMP/IPTC/GPS, thumbnail) is ALWAYS stripped on export, unconditionally — never ' +
+                'carried over from the source.',
         },
         overwrite: {
             type: 'boolean',
@@ -151,23 +157,59 @@ const exportSchema = {
             type: 'integer',
             enum: [8, 16],
             default: 8,
-            description: 'PNG/TIFF only: output bit depth. JPEG/WebP are always 8-bit.',
+            description: 'PNG/TIFF/PSD only: output bit depth. JPEG/WebP are always 8-bit.',
+        },
+        keep_alpha: {
+            type: 'boolean',
+            default: false,
+            description: 'PNG/WebP only: keep transparency. The visible layers are merged onto a transparent ' +
+                'canvas, so areas no layer covers (a cut-out, say) stay transparent. Default false ' +
+                'flattens onto white. Refused for JPEG and TIFF.',
         },
     },
     required: ['image', 'file_path'],
 };
+const LAYER_NAMES_SHOWN = 10;
+function layerNames(names) {
+    const shown = names.slice(0, LAYER_NAMES_SHOWN).map((n) => `"${n}"`);
+    const more = names.length - shown.length;
+    return more > 0 ? `${shown.join(', ')} and ${more} more` : shown.join(', ');
+}
+function layeredExportText(result) {
+    const parts = [
+        `Exported ${result.bytes.toLocaleString()} bytes to ${result.path} as a layered PSD with ` +
+            `${result.layers} layers. Live filters were baked into their layers' pixels.`,
+    ];
+    if (result.merged_groups.length > 0) {
+        parts.push(`Groups merged into one layer each, because PSD cannot store a filter on a group: ` +
+            `${layerNames(result.merged_groups)}.`);
+    }
+    if (result.rasterized_text.length > 0) {
+        parts.push(`Text layers written as pixels, not editable text: ${layerNames(result.rasterized_text)}.`);
+    }
+    if (result.may_blend_differently.length > 0) {
+        parts.push('Photoshop blends partly transparent layers and blend modes in gamma space, so these ' +
+            `may look slightly different there: ${layerNames(result.may_blend_differently)}.`);
+    }
+    parts.push('Metadata (EXIF/XMP/IPTC/GPS, thumbnail) was stripped.');
+    return parts.join(' ');
+}
 async function gimpExport(gimp, rawArgs) {
     try {
         const args = validateArgs(exportSchema, rawArgs);
         const filePath = requireAbsoluteGimpPath('file_path', args.file_path);
         const ext = extname(filePath).toLowerCase();
         if (ext === '.xcf') {
-            throw new GimpError('invalid_argument', '"file_path" must not be a .xcf file — gimp_export writes a flattened deliverable; use ' +
+            throw new GimpError('invalid_argument', '"file_path" must not be a .xcf file — gimp_export writes a deliverable; use ' +
                 'gimp_save_xcf to save the live, re-editable document.');
         }
         if (!EXPORT_FORMAT_EXTENSIONS.includes(ext)) {
             throw new GimpError('invalid_argument', `"file_path" must end in ${EXPORT_FORMAT_EXTENSIONS.join(', ')}, got "${ext || '(none)'}".`);
         }
+        const keepAlpha = args.keep_alpha === true;
+        if (keepAlpha && ext !== '.png' && ext !== '.webp') {
+            throw new GimpError('invalid_argument', `"keep_alpha" only works with a .png or .webp file_path, got "${ext}".`);
+        }
         refuseExistingGimpFile(filePath, args.overwrite, existsSync);
         const bridgeArgs = { image: args.image, path: filePath };
         if (ext === '.jpg' || ext === '.jpeg') {
@@ -185,8 +227,20 @@ async function gimpExport(gimp, rawArgs) {
             bridgeArgs.compression = args.tiff_compression;
             bridgeArgs.bit_depth = args.bit_depth;
         }
-        const result = await gimp.call('export', bridgeArgs);
+        else if (ext === '.psd') {
+            bridgeArgs.bit_depth = args.bit_depth;
+        }
+        if (keepAlpha)
+            bridgeArgs.keep_alpha = true;
         const format = ext.replace('.', '');
+        if (ext === '.psd') {
+            const result = await gimp.call('export', bridgeArgs);
+            return {
+                content: [{ type: 'text', text: layeredExportText(result) }],
+                structuredContent: { ...result, format },
+            };
+        }
+        const result = await gimp.call('export', bridgeArgs);
         return {
             content: [
                 {
@@ -243,7 +297,7 @@ export function createGimpDocumentTools(gimp) {
             tool: {
                 name: 'gimp_close_document',
                 description: 'Headless GIMP: close an image WITHOUT saving. Save first with gimp_save_xcf (keeps filters live) or ' +
-                    'gimp_export (flattened deliverable) if the work should be kept.',
+                    'gimp_export (deliverable) if the work should be kept.',
                 inputSchema: closeSchema,
                 outputSchema: { type: 'object', properties: { closed: { type: 'number' } } },
                 annotations: {
@@ -274,7 +328,8 @@ export function createGimpDocumentTools(gimp) {
                     'to overwrite an existing file unless overwrite: true. Save early: on a very large ' +
                     'document a save can take tens of seconds, and if any call times out the GIMP session ' +
                     'restarts and every unsaved open image and filter is lost — save before long operations, ' +
-                    'not after. For a flattened, shippable copy with metadata stripped, use gimp_export instead.',
+                    'not after. For a shippable copy with metadata stripped (flattened, or a layered .psd), ' +
+                    'use gimp_export instead.',
                 inputSchema: saveXcfSchema,
                 outputSchema: {
                     type: 'object',
@@ -293,12 +348,20 @@ export function createGimpDocumentTools(gimp) {
         {
             tool: {
                 name: 'gimp_export',
-                description: 'Headless GIMP: write a FLATTENED deliverable to disk — every live filter is baked in, ' +
-                    'and ALL metadata (EXIF/XMP/IPTC/GPS, thumbnail) is stripped unconditionally, never ' +
-                    'carried over from the source. Format is picked from the file_path extension (jpg/jpeg, ' +
-                    'png, webp, tif/tiff); any other extension is refused, and .xcf is refused outright — ' +
-                    'use gimp_save_xcf for the live, re-editable document instead. Refuses to overwrite an ' +
-                    'existing file unless overwrite: true (with it, the existing file is replaced).',
+                description: 'Headless GIMP: write a deliverable to disk — every live filter is baked in, and ALL ' +
+                    'metadata (EXIF/XMP/IPTC/GPS, thumbnail) is stripped unconditionally, never carried ' +
+                    'over from the source. Format is picked from the file_path extension: jpg/jpeg, png, ' +
+                    'webp and tif/tiff write a FLATTENED image; psd writes a LAYERED file for finishing in ' +
+                    'Photoshop or another editor. In a PSD, layers keep their masks, opacity, blend modes, ' +
+                    'visibility and groups; filters are baked into each layer; a group with its own filter ' +
+                    'is merged into one layer; text layers become pixels. Photoshop blends partly ' +
+                    'transparent layers and blend modes in gamma space, so those can look slightly ' +
+                    'different there — the result lists them. Any other extension is refused, and .xcf is ' +
+                    'refused outright — use gimp_save_xcf for the live, re-editable document instead. ' +
+                    'Refuses to overwrite an existing file unless overwrite: true (with it, the existing ' +
+                    'file is replaced). A flattened image is composited onto white by default; keep_alpha: ' +
+                    'true (png or webp only) keeps transparency, so a cut-out exports with a transparent ' +
+                    'background.',
                 inputSchema: exportSchema,
                 outputSchema: {
                     type: 'object',
@@ -306,6 +369,22 @@ export function createGimpDocumentTools(gimp) {
                         path: { type: 'string' },
                         bytes: { type: 'number' },
                         format: { type: ['string', 'null'] },
+                        layers: { type: 'number', description: 'PSD only: layers written, groups included.' },
+                        merged_groups: {
+                            type: 'array',
+                            items: { type: 'string' },
+                            description: 'PSD only: groups merged into one layer to keep their own filter.',
+                        },
+                        rasterized_text: {
+                            type: 'array',
+                            items: { type: 'string' },
+                            description: 'PSD only: text layers written as pixels.',
+                        },
+                        may_blend_differently: {
+                            type: 'array',
+                            items: { type: 'string' },
+                            description: 'PSD only: visible layers below 100% opacity or with a non-normal blend mode.',
+                        },
                     },
                 },
                 annotations: {