editmamei 0.22.4 → 0.24.1

package/dist/platform/macos-executor.js

@@ -3,14 +3,15 @@ import { promisify } from 'util';
 import { Logger } from '../utils/logger.js';
 import { TempDir } from '../utils/temp.js';
 import { runChildWithTimeout } from './run-child.js';
+import { ScriptQueue } from './executor-queue.js';
 const execAsync = promisify(exec);
 export class MacOSExecutor {
     logger;
-    scriptQueue = [];
-    isProcessing = false;
+    queue;
     appName = 'Adobe Photoshop 2025';
     constructor() {
         this.logger = new Logger('MacOSExecutor');
+        this.queue = new ScriptQueue(this.logger);
     }
     setAppName(appName) {
         if (/["\\\r\n\t]/.test(appName)) {
@@ -20,91 +21,41 @@ export class MacOSExecutor {
         this.logger.debug(`App name set to: ${appName}`);
     }
     async execute(script, timeout = 30000) {
-        return new Promise((resolve, reject) => {
-            const task = {
-                run: () => this.executeScript(script, timeout),
-                resolve,
-                reject,
-                cancelled: false,
-                settled: false,
-                timeoutId: null,
-            };
-            const QUEUE_SLACK_MS = 3500;
-            task.timeoutId = setTimeout(() => {
-                if (task.settled)
-                    return;
-                task.cancelled = true;
-                task.settled = true;
-                task.timeoutId = null;
-                reject(new Error('Script execution timeout'));
-            }, timeout + QUEUE_SLACK_MS);
-            this.scriptQueue.push(task);
-            void this.processQueue();
-        });
-    }
-    settleTask(task, fn) {
-        if (task.settled)
-            return;
-        task.settled = true;
-        if (task.timeoutId !== null) {
-            clearTimeout(task.timeoutId);
-            task.timeoutId = null;
-        }
-        fn();
-    }
-    async processQueue() {
-        if (this.isProcessing)
-            return;
-        this.isProcessing = true;
-        try {
-            while (this.scriptQueue.length > 0) {
-                const task = this.scriptQueue.shift();
-                if (task.cancelled)
-                    continue;
-                try {
-                    const result = await task.run();
-                    this.settleTask(task, () => task.resolve(result));
-                }
-                catch (error) {
-                    if (task.settled) {
-                        this.logger.error('Script execution failed after settle:', error);
-                    }
-                    else {
-                        this.settleTask(task, () => task.reject(error));
-                    }
-                }
-            }
-        }
-        finally {
-            this.isProcessing = false;
-        }
+        return this.queue.enqueue(() => this.executeScript(script, timeout), timeout);
     }
     async executeScript(script, timeout) {
         const dir = await TempDir.create('editmamei-mac-');
         try {
             const jsxPath = await dir.write('script.jsx', script);
-            const wrapperPath = await dir.write('wrapper.scpt', this.createAppleScriptWrapper(jsxPath));
-            const { stdout, stderr } = await runChildWithTimeout('osascript', [wrapperPath], {
+            const wrapperPath = await dir.write('wrapper.scpt', this.createAppleScriptWrapper(jsxPath, timeout));
+            const { stdout, stderr, exitCode } = await runChildWithTimeout('osascript', [wrapperPath], {
                 timeout,
                 diagLabel: 'osascript wrapper.scpt',
             });
             if (stderr) {
                 this.logger.warn('Script execution warning:', stderr);
             }
+            if (exitCode !== 0) {
+                throw new Error(`osascript exited with code ${exitCode}: ${stderr.trim() || '(no stderr)'}`);
+            }
             return this.parseResult(stdout);
         }
         finally {
             await dir.cleanup();
         }
     }
-    createAppleScriptWrapper(jsxPath) {
+    createAppleScriptWrapper(jsxPath, timeoutMs = 30000) {
         const posixPath = jsxPath.replace(/\\/g, '/');
-        if (posixPath.includes('"') || posixPath.includes("'") || posixPath.includes('\n')) {
+        if (posixPath.includes('"') || posixPath.includes('\n')) {
             throw new Error('jsxPath contains a character that would break AppleScript interpolation');
         }
-        return `tell application "${this.appName}"
-\tdo javascript "$.evalFile(decodeURI('${encodeURI(posixPath)}'))"
-end tell`;
+        const timeoutSeconds = Number.isFinite(timeoutMs) && timeoutMs > 0 ? Math.max(1, Math.ceil(timeoutMs / 1000)) : 1;
+        const encodedPath = encodeURI(posixPath).replace(/'/g, '%27');
+        return `with timeout of ${timeoutSeconds} seconds
+\ttell application "${this.appName}"
+\t\tdo javascript "$.evalFile(decodeURI('${encodedPath}'))"
+\tend tell
+end timeout`;
     }
     parseResult(output) {
         const trimmed = output.trim();

package/dist/platform/run-child.js

@@ -87,9 +87,12 @@ export async function runChildWithTimeout(command, args, options) {
         });
         child.on('exit', (code, signal) => {
             if (timedOut) {
-                settle(() => reject(new Error(`Script execution timeout after ${timeout}ms (${diagLabel}). The child process was killed; ` +
-                    `if Photoshop has a modal dialog open (license, missing font, GPU init, "Discard?" prompt), ` +
-                    `dismiss it in Photoshop and retry.`)));
+                settle(() => reject(new Error(`Script execution timeout after ${timeout}ms (${diagLabel}). The child process was killed, ` +
+                    `but Photoshop runs as a separate process and may have kept executing — the operation ` +
+                    `could still have completed. Check Photoshop's actual state before retrying. Common ` +
+                    `causes: a genuinely slow operation (e.g. a large RAW file's first Camera Raw engine ` +
+                    `init) exceeding the timeout, or a modal dialog open in Photoshop (license, missing ` +
+                    `font, GPU init, "Discard?" prompt) — dismiss it if present.`)));
                 return;
             }
             if (overflowed) {

package/dist/platform/windows-detector.js

@@ -26,11 +26,9 @@ export class WindowsDetector {
             this.logger.warn('Registry detection failed:', error);
         }
         const commonPaths = this.getCommonPaths();
-        for (const path of commonPaths) {
-            const info = await this.checkPath(path);
-            if (info)
-                return info;
-        }
+        const commonPathInfo = await this.checkCommonPaths(commonPaths);
+        if (commonPathInfo)
+            return commonPathInfo;
         throw new Error('Photoshop not found on this system');
     }
     async detectFromRegistry() {
@@ -107,12 +105,21 @@ export class WindowsDetector {
         const programFiles = process.env.ProgramFiles || 'C:\\Program Files';
         const programFilesX86 = process.env['ProgramFiles(x86)'] || 'C:\\Program Files (x86)';
         const paths = [];
-        for (let year = 2025; year >= 2012; year--) {
+        const maxYear = Math.max(new Date().getFullYear() + 1, 2026);
+        for (let year = maxYear; year >= 2012; year--) {
             paths.push(`${programFiles}\\Adobe\\Adobe Photoshop ${year}\\Photoshop.exe`, `${programFilesX86}\\Adobe\\Adobe Photoshop ${year}\\Photoshop.exe`, `${programFiles}\\Adobe\\Adobe Photoshop CC ${year}\\Photoshop.exe`, `${programFilesX86}\\Adobe\\Adobe Photoshop CC ${year}\\Photoshop.exe`);
         }
         paths.push(`${programFiles}\\Adobe\\Adobe Photoshop CC\\Photoshop.exe`, `${programFiles}\\Adobe\\Photoshop CC\\Photoshop.exe`);
         return paths;
     }
+    async checkCommonPaths(paths) {
+        const results = await Promise.all(paths.map((path) => this.checkPath(path)));
+        const selected = results.find((result) => result !== null) ?? null;
+        if (selected) {
+            this.logger.info(`Found Photoshop at: ${selected.path}`);
+        }
+        return selected;
+    }
     async checkPath(path) {
         try {
             let cleanPath = path.trim().replace(/^"|"$/g, '');
@@ -121,7 +128,7 @@ export class WindowsDetector {
             }
             await access(cleanPath, constants.F_OK);
             const version = this.extractVersionFromPath(cleanPath);
-            this.logger.info(`Found Photoshop at: ${cleanPath}`);
+            this.logger.debug(`Found Photoshop at: ${cleanPath}`);
             return {
                 version,
                 path: cleanPath,

package/dist/platform/windows-executor.js

@@ -4,73 +4,17 @@ import { exec } from 'child_process';
 import { Logger } from '../utils/logger.js';
 import { TempDir } from '../utils/temp.js';
 import { runChildWithTimeout } from './run-child.js';
+import { ScriptQueue } from './executor-queue.js';
 const execAsync = promisify(exec);
 export class WindowsExecutor {
     logger;
-    scriptQueue = [];
-    isProcessing = false;
+    queue;
     constructor() {
         this.logger = new Logger('WindowsExecutor');
+        this.queue = new ScriptQueue(this.logger);
     }
     async execute(script, timeout = 30000) {
-        return new Promise((resolve, reject) => {
-            const task = {
-                run: () => this.executeScript(script, timeout),
-                resolve,
-                reject,
-                cancelled: false,
-                settled: false,
-                timeoutId: null,
-            };
-            const QUEUE_SLACK_MS = 3500;
-            task.timeoutId = setTimeout(() => {
-                if (task.settled)
-                    return;
-                task.cancelled = true;
-                task.settled = true;
-                task.timeoutId = null;
-                reject(new Error('Script execution timeout'));
-            }, timeout + QUEUE_SLACK_MS);
-            this.scriptQueue.push(task);
-            void this.processQueue();
-        });
-    }
-    settleTask(task, fn) {
-        if (task.settled)
-            return;
-        task.settled = true;
-        if (task.timeoutId !== null) {
-            clearTimeout(task.timeoutId);
-            task.timeoutId = null;
-        }
-        fn();
-    }
-    async processQueue() {
-        if (this.isProcessing)
-            return;
-        this.isProcessing = true;
-        try {
-            while (this.scriptQueue.length > 0) {
-                const task = this.scriptQueue.shift();
-                if (task.cancelled)
-                    continue;
-                try {
-                    const result = await task.run();
-                    this.settleTask(task, () => task.resolve(result));
-                }
-                catch (error) {
-                    if (task.settled) {
-                        this.logger.error('Script execution failed after settle:', error);
-                    }
-                    else {
-                        this.settleTask(task, () => task.reject(error));
-                    }
-                }
-            }
-        }
-        finally {
-            this.isProcessing = false;
-        }
+        return this.queue.enqueue(() => this.executeScript(script, timeout), timeout);
     }
     async executeScript(script, timeout) {
         const dir = await TempDir.create('editmamei-win-');
@@ -91,8 +35,8 @@ export class WindowsExecutor {
         }
     }
     createVBSWrapper(jsxPath) {
-        if (jsxPath.includes('"') || jsxPath.includes("'")) {
-            throw new Error('jsxPath contains a quote character — refusing to compose VBS');
+        if (jsxPath.includes('"')) {
+            throw new Error('jsxPath contains a double-quote — refusing to compose VBS');
         }
         return `
 On Error Resume Next
@@ -104,8 +48,9 @@ If Err.Number <> 0 Then
     WScript.Quit 1
 End If
 
-' Execute the JSX script. The path is the mkdtemp temp file (quote-free by the
-' guard above), but its single backslashes must be DOUBLED here: this string is
+' Execute the JSX script. The path is the mkdtemp temp file (double-quote-free
+' by the guard above; apostrophes are fine here), but its single backslashes
+' must be DOUBLED here: this string is
 ' handed to DoJavaScript as ExtendScript SOURCE, and a backslash inside a quoted
 ' path there is a JS string-literal escape (a Users/Temp segment would be parsed
 ' as an escape sequence and corrupt the path). The VBS Replace doubles each

package/dist/tools/adjustment-tools.js

@@ -1,5 +1,6 @@
 import { runScript } from '../utils/run-script.js';
 import { validateArgs } from '../utils/validate.js';
+import { toolErrorResult, runSnippetTool, applyToActiveLayerProp } from '../utils/tool-helpers.js';
 const addAdjustmentLayerSchema = {
     type: 'object',
     properties: {
@@ -495,6 +496,11 @@ const addAdjustmentLayerSchema = {
             description: 'Only meaningful when mask_from_selection is true AND there is an active selection. If true, the resulting mask is inverted — so the adjustment affects EVERYTHING OUTSIDE the selection rather than inside. Common idiom: "I selected the sky but want to adjust everything else." Defaults to false.',
             default: false,
         },
+        into_active_group: {
+            type: 'boolean',
+            description: "Photoshop's Mk-AdjL descriptor carries no placement target, so with a GROUP active it would natively nest the new layer INSIDE that group. Default false hoists the new layer back out so it lands above the active layer/group as a sibling, matching this tool's documented placement. Pass true to keep the new layer nested inside the active group instead.",
+            default: false,
+        },
     },
     required: ['type'],
 };
@@ -505,22 +511,14 @@ const colorLookupBakeSchema = {
             type: 'string',
             description: 'Leaf name of a 3DLUT file in PS\'s Presets/3DLUTs/ folder (e.g. "TealOrangePlusContrast.3DL", "FallColors.look", "Kodak 5205 Fuji 3510 (by Adobe).cube") OR an absolute path to a .3DL / .look / .cube file. Extension-agnostic leaf-name resolution (the same base name with a different extension still matches).',
         },
-        apply_to_active_layer: {
-            type: 'boolean',
-            description: 'If false (default), runs on a DUPLICATE of the active layer; the original is preserved. If true, bakes into the active layer in place.',
-            default: false,
-        },
+        apply_to_active_layer: applyToActiveLayerProp('the color lookup'),
     },
     required: ['cl_lut_name'],
 };
 const equalizeSchema = {
     type: 'object',
     properties: {
-        apply_to_active_layer: {
-            type: 'boolean',
-            description: 'If false (default), the operation runs on a DUPLICATE of the active layer and the original is preserved. If true, bakes into the active layer in place. Use false unless you specifically want the destructive-in-place behavior.',
-            default: false,
-        },
+        apply_to_active_layer: applyToActiveLayerProp('the equalize'),
     },
 };
 const shadowsHighlightsSchema = {
@@ -596,11 +594,7 @@ const shadowsHighlightsSchema = {
             maximum: 50,
             default: 0.01,
         },
-        apply_to_active_layer: {
-            type: 'boolean',
-            description: 'If false (default), the op is applied to a duplicate of the active layer named "Shadows/Highlights (<Original Name>)" — original preserved. If true, bakes directly into the active layer.',
-            default: false,
-        },
+        apply_to_active_layer: applyToActiveLayerProp('the op'),
     },
 };
 const APPLY_ADJUSTMENT_TYPES = ['shadows_highlights', 'equalize', 'color_lookup'];
@@ -660,7 +654,7 @@ export function createAdjustmentTools(connection, snippetClient) {
         {
             tool: {
                 name: 'ps_add_adjustment_layer',
-                description: "Create a non-destructive adjustment layer above the active layer. Supports the full real-Photoshop tonal/color surface: Curves (with S-curve presets), Levels, Hue/Saturation, Brightness/Contrast, Black & White (with optional tint), Color Balance, Photo Filter (preset or custom color), Vibrance, Channel Mixer, Selective Color, Gradient Map (preset), Exposure (stops + offset + gamma), Color Lookup (3DLUT presets or custom file path), and Invert. Values are editable, maskable, and removable. This is the canonical entry point for ALL tonal/color adjustments; the old destructive bake tools (auto_levels / auto_contrast / desaturate / invert) were removed on 2026-05-31 — if you genuinely need a pixel bake, follow this call with `photoshop_merge_visible_layers`. Optionally clips the adjustment to only affect the layer directly below it. If a selection is active at call time, the new layer is automatically masked by it (toggle with mask_from_selection / mask_inverted). For destructive ops that don't have an adjustment-layer equivalent in Photoshop (Shadows/Highlights — single-pass shadow/highlight recovery), use `photoshop_apply_shadows_highlights` which auto-duplicates the active layer to keep the original intact. Returns context — the new adjustment layer becomes active.",
+                description: "Create a non-destructive adjustment layer above the active layer — hoisted out of the active layer's group by default even though Photoshop's own Mk-AdjL placement rule would otherwise nest it INSIDE that group (pass into_active_group:true to keep that native nesting). Supports the full real-Photoshop tonal/color surface: Curves (with S-curve presets), Levels, Hue/Saturation, Brightness/Contrast, Black & White (with optional tint), Color Balance, Photo Filter (preset or custom color), Vibrance, Channel Mixer, Selective Color, Gradient Map (preset), Exposure (stops + offset + gamma), Color Lookup (3DLUT presets or custom file path), and Invert. Values are editable, maskable, and removable. This is the canonical entry point for ALL tonal/color adjustments; the old destructive bake tools (auto_levels / auto_contrast / desaturate / invert) were removed on 2026-05-31 — if you genuinely need a pixel bake, follow this call with `ps_merge` (mode=visible). Optionally clips the adjustment to only affect the layer directly below it. If a selection is active at call time, the new layer is automatically masked by it (toggle with mask_from_selection / mask_inverted). For destructive ops that don't have an adjustment-layer equivalent in Photoshop (Shadows/Highlights — single-pass shadow/highlight recovery), use `ps_apply_adjustment` (type=shadows_highlights) which auto-duplicates the active layer to keep the original intact. Returns context (the new adjustment layer becomes active) plus parent_path — the actual containing-group chain, so placement is never silent.",
                 inputSchema: addAdjustmentLayerSchema,
                 outputSchema: {
                     type: 'object',
@@ -677,6 +671,15 @@ export function createAdjustmentTools(connection, snippetClient) {
                         mask_inverted: { type: 'boolean' },
                         mask_inversion_error: { type: ['string', 'null'] },
                         clipError: { type: 'string' },
+                        hoisted: {
+                            type: 'boolean',
+                            description: 'True when the new layer had to be moved back out of the previously-active group to honor into_active_group:false (the default). False when it landed correctly on its own, or when the move-back itself failed — check the layer tree if this matters and hoisted is false.',
+                        },
+                        parent_path: {
+                            type: ['array', 'null'],
+                            items: { type: 'string' },
+                            description: 'The containing-group name chain (outermost first), empty array at the document root.',
+                        },
                         context: { type: 'object' },
                     },
                 },
@@ -785,6 +788,7 @@ async function addAdjustmentLayer(connection, snippetClient, rawArgs) {
         const name = args.name;
         const maskFromSelection = args.mask_from_selection ?? true;
         const maskInverted = args.mask_inverted ?? false;
+        const intoActiveGroup = args.into_active_group ?? false;
         const params = {};
         for (const key of FORWARDED_KEYS) {
             if (args[key] !== undefined)
@@ -806,6 +810,7 @@ async function addAdjustmentLayer(connection, snippetClient, rawArgs) {
             clip_to_below: clipToBelow,
             mask_from_selection: maskFromSelection,
             mask_inverted: maskInverted,
+            into_active_group: intoActiveGroup,
             ...params,
         };
         if (name !== undefined)
@@ -823,125 +828,68 @@ async function addAdjustmentLayer(connection, snippetClient, rawArgs) {
         };
     }
     catch (error) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error adding adjustment layer: ${error instanceof Error ? error.message : String(error)}`,
-                },
-            ],
-            isError: true,
-        };
+        return toolErrorResult('Error adding adjustment layer', error);
     }
 }
 async function applyColorLookup(connection, snippetClient, rawArgs) {
-    try {
-        const args = validateArgs(colorLookupBakeSchema, rawArgs);
-        const lutName = args.cl_lut_name;
-        const applyToActiveLayer = args.apply_to_active_layer ?? false;
-        const script = await snippetClient.build('applyColorLookup', { lutName, applyToActiveLayer });
-        const result = await runScript(connection, script);
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Color Lookup applied (BAKE, experimental):\n${JSON.stringify(result, null, 2)}`,
-                },
-            ],
-            structuredContent: result,
-        };
-    }
-    catch (error) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error applying color lookup: ${error instanceof Error ? error.message : String(error)}`,
-                },
-            ],
-            isError: true,
-        };
-    }
+    return runSnippetTool({
+        connection,
+        snippetClient,
+        rawArgs,
+        schema: colorLookupBakeSchema,
+        snippet: 'applyColorLookup',
+        errorPrefix: 'Error applying color lookup',
+        params: (args) => ({
+            lutName: args.cl_lut_name,
+            applyToActiveLayer: args.apply_to_active_layer ?? false,
+        }),
+        successText: (result) => `Color Lookup applied (BAKE, experimental):\n${JSON.stringify(result, null, 2)}`,
+    });
 }
 async function applyEqualize(connection, snippetClient, rawArgs) {
-    try {
-        const args = validateArgs(equalizeSchema, rawArgs);
-        const applyToActiveLayer = args.apply_to_active_layer ?? false;
-        const script = await snippetClient.build('applyEqualize', { applyToActiveLayer });
-        const result = await runScript(connection, script);
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Equalize applied:\n${JSON.stringify(result, null, 2)}`,
-                },
-            ],
-            structuredContent: result,
-        };
-    }
-    catch (error) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error applying equalize: ${error instanceof Error ? error.message : String(error)}`,
-                },
-            ],
-            isError: true,
-        };
-    }
+    return runSnippetTool({
+        connection,
+        snippetClient,
+        rawArgs,
+        schema: equalizeSchema,
+        snippet: 'applyEqualize',
+        errorPrefix: 'Error applying equalize',
+        params: (args) => ({
+            applyToActiveLayer: args.apply_to_active_layer ?? false,
+        }),
+        successText: (result) => `Equalize applied:\n${JSON.stringify(result, null, 2)}`,
+    });
 }
 async function applyShadowsHighlights(connection, snippetClient, rawArgs) {
-    try {
-        const args = validateArgs(shadowsHighlightsSchema, rawArgs);
-        const shadowAmount = args.shadow_amount ?? 35;
-        const shadowWidth = args.shadow_width ?? 50;
-        const shadowRadius = args.shadow_radius ?? 30;
-        const highlightAmount = args.highlight_amount ?? 0;
-        const highlightWidth = args.highlight_width ?? 50;
-        const highlightRadius = args.highlight_radius ?? 30;
-        const colorCorrection = args.color_correction ?? 20;
-        const midtoneContrast = args.midtone_contrast ?? 0;
-        const blackClip = args.black_clip ?? 0.01;
-        const whiteClip = args.white_clip ?? 0.01;
-        const applyToActiveLayer = args.apply_to_active_layer ?? false;
-        const script = await snippetClient.build('applyShadowsHighlights', {
-            shadowAmount,
-            shadowWidth,
-            shadowRadius,
-            highlightAmount,
-            highlightWidth,
-            highlightRadius,
-            colorCorrection,
-            midtoneContrast,
-            blackClip,
-            whiteClip,
-            applyToActiveLayer,
-        });
-        const result = await runScript(connection, script);
-        const r = result;
-        const target = r.target_was_copy
-            ? `new copy "${r.target_layer_name ?? '?'}"`
-            : 'active layer (in place)';
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Shadows/Highlights applied to ${target} (shadow ${shadowAmount}, highlight ${highlightAmount}, color ${colorCorrection}).`,
-                },
-            ],
-            structuredContent: result,
-        };
-    }
-    catch (error) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error applying shadows/highlights: ${error instanceof Error ? error.message : String(error)}`,
-                },
-            ],
-            isError: true,
-        };
-    }
+    return runSnippetTool({
+        connection,
+        snippetClient,
+        rawArgs,
+        schema: shadowsHighlightsSchema,
+        snippet: 'applyShadowsHighlights',
+        errorPrefix: 'Error applying shadows/highlights',
+        params: (args) => ({
+            shadowAmount: args.shadow_amount ?? 35,
+            shadowWidth: args.shadow_width ?? 50,
+            shadowRadius: args.shadow_radius ?? 30,
+            highlightAmount: args.highlight_amount ?? 0,
+            highlightWidth: args.highlight_width ?? 50,
+            highlightRadius: args.highlight_radius ?? 30,
+            colorCorrection: args.color_correction ?? 20,
+            midtoneContrast: args.midtone_contrast ?? 0,
+            blackClip: args.black_clip ?? 0.01,
+            whiteClip: args.white_clip ?? 0.01,
+            applyToActiveLayer: args.apply_to_active_layer ?? false,
+        }),
+        successText: (result, args) => {
+            const r = result;
+            const target = r.target_was_copy
+                ? `new copy "${r.target_layer_name ?? '?'}"`
+                : 'active layer (in place)';
+            const shadowAmount = args.shadow_amount ?? 35;
+            const highlightAmount = args.highlight_amount ?? 0;
+            const colorCorrection = args.color_correction ?? 20;
+            return `Shadows/Highlights applied to ${target} (shadow ${shadowAmount}, highlight ${highlightAmount}, color ${colorCorrection}).`;
+        },
+    });
 }

package/dist/tools/brush-tools.js

@@ -1,6 +1,7 @@
 import { SUPPORTED_BRUSH_TOOLS } from '../api/brush-tool-names.js';
 import { runScript } from '../utils/run-script.js';
 import { validateArgs } from '../utils/validate.js';
+import { toolErrorResult, applyToActiveLayerProp } from '../utils/tool-helpers.js';
 import { OnnxLandmarkDetectionClient } from '../detection/landmark-detection-client.js';
 import { resolveExpectedPlacement, PLACEMENT_SCHEMA } from '../perception/grounding-locate.js';
 const TOOLS_REQUIRING_SOURCE = ['clone_stamp', 'healing_brush'];
@@ -109,11 +110,7 @@ const applyBrushStrokeSchema = {
             maximum: 50,
             default: 0,
         },
-        apply_to_active_layer: {
-            type: 'boolean',
-            description: 'If false (default), the stroke runs on a duplicate named "Brush Stroke (<original name>)" — the original is preserved, undo is delete-the-copy (Bundle O pattern). If true, the stroke bakes into the active layer directly.',
-            default: false,
-        },
+        apply_to_active_layer: applyToActiveLayerProp('the stroke'),
     },
     required: ['tool', 'brush_size'],
 };
@@ -292,15 +289,7 @@ async function applyBrushStroke(connection, snippetClient, client, rawArgs) {
         };
     }
     catch (error) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error applying brush stroke: ${error instanceof Error ? error.message : String(error)}`,
-                },
-            ],
-            isError: true,
-        };
+        return toolErrorResult('Error applying brush stroke', error);
     }
 }
 function deterministicNoise(i, anchorSeed, axisSalt) {