editmamei 1.3.0 → 1.4.0

package/dist/tools/selection-tools.js

@@ -316,6 +316,24 @@ const selectPolygonSchema = {
     },
     required: ['points'],
 };
+const selectFocusAreaSchema = {
+    type: 'object',
+    properties: {
+        in_focus_radius: {
+            type: 'number',
+            description: 'How much blur still counts as "in focus", in pixels. Higher pulls more of the soft transition zone into the selection; lower keeps only the crisply resolved plane. 4.07 is the Photoshop dialog default and a sane starting point. The useful band is narrow, and a radius well above the default selects the entire frame — so move in small steps and CHECK the returned area_percent and whole_canvas_selected: a selection covering essentially everything means the radius is too high and the result is worthless, even though the call reports success.',
+            default: 4.07,
+            minimum: 0.1,
+            maximum: 15,
+        },
+        soft_mask: {
+            type: 'boolean',
+            description: 'False (default) yields a hard-edged selection — every pixel fully in or fully out, which is what you want before ps_modify_selection feathering. True lets Photoshop feather the focus falloff itself, useful when the subject edge is genuinely gradual (hair, fur, motion).',
+            default: false,
+        },
+        selection_type: selectionTypeFragment,
+    },
+};
 const modifyEdgeSchema = {
     type: 'object',
     properties: {
@@ -376,6 +394,12 @@ const selectionPreviewSchema = {
             maximum: 4096,
             default: 800,
         },
+        image: {
+            type: 'string',
+            enum: ['overlay', 'mask', 'both'],
+            default: 'overlay',
+            description: "Which rendered image(s) to return inline. 'overlay' (default): a 50% red wash over the selected area (Quick Mask-style — most intuitive). 'mask': a B/W mask (black=selected, white=not) instead. 'both': the overlay followed by the mask, for when you need to compare them side by side. selection_info is returned regardless of this choice.",
+        },
     },
 };
 const saveSelectionToChannelSchema = {
@@ -437,6 +461,7 @@ const SELECT_MODES = [
     'skin_tones',
     'out_of_gamut',
     'polygon',
+    'focus_area',
 ];
 const SELECT_INPUT_SCHEMA = {
     type: 'object',
@@ -455,8 +480,9 @@ const SELECT_INPUT_SCHEMA = {
                 'skin_tones: select skin-coloured pixels (+fuzziness; use_faces=true adds face-aware refinement). ' +
                 'out_of_gamut: select colours outside the printable CMYK gamut (no params). ' +
                 'polygon: points [{x,y},...] in ABSOLUTE document pixels (min 3, auto-closes) — covers polygonal/freehand lasso. Coordinate-driven: you must know the pixel positions (use ps_inspect / ps_get_preview to aim, or ps_path create_from_placement → load_as_selection for a grounded outline). ' +
+                'focus_area: select what the lens rendered SHARP by depth of field, not by subject or colour (+in_focus_radius, soft_mask) — takes no coordinates; check whole_canvas_selected in the result before trusting it. ' +
                 'rectangle/ellipse/magic_wand also take a grounded `placement` instead of raw coords (region → the bbox; point → the wand click). ' +
-                'rectangle/ellipse/polygon/color_range/luminance_range/magic_wand/skin_tones/out_of_gamut also take selection_type to combine with an existing selection.',
+                'rectangle/ellipse/polygon/focus_area/color_range/luminance_range/magic_wand/skin_tones/out_of_gamut also take selection_type to combine with an existing selection.',
         },
         ...selectRectangleSchema.properties,
         ...selectColorRangeSchema.properties,
@@ -464,6 +490,7 @@ const SELECT_INPUT_SCHEMA = {
         ...magicWandSchema.properties,
         ...colorPresetSchema.properties,
         ...selectPolygonSchema.properties,
+        ...selectFocusAreaSchema.properties,
         placement: {
             ...PLACEMENT_SCHEMA,
             description: 'Grounded coordinates (rectangle/ellipse/magic_wand): NAME anchors + a relation instead of guessing pixels. rectangle/ellipse ← a REGION relation (inside/gap) → the selection bounding box; magic_wand ← a POINT relation (centroid/extremum/grid) → the click. Verified by the objective gate; wins over the raw edges/x-y. See the placement-resolver tool, when this build has one, for the vocabulary.',
@@ -580,7 +607,7 @@ export function createSelectionTools(connection, snippetClient, client = new Onn
         {
             tool: {
                 name: 'ps_select',
-                description: 'Create a NEW selection — choose with `mode`. (To edit the CURRENT selection instead — including growing it by colour similarity — use ps_modify_selection.) `all` selects the canvas; `none` deselects; `inverse` inverts the current selection (e.g. select the subject, then inverse to act on the background). `rectangle` (left/top/right/bottom, optional feather_px to avoid hard block-edges in smooth sky). `ellipse` (left/top/right/bottom bounding box + anti_alias — circles/ovals). `color_range` (target red/green/blue + fuzziness — "select all the red / skin tones"). `luminance_range` (highlights/shadows/midtones — foundation for glow / dodge-burn). `magic_wand` (click x/y + tolerance, contiguous). `grow` / `similar` are DEPRECATED here (they act on the CURRENT selection, not a new one) — use ps_modify_selection(op=grow|similar) instead; kept for one release for backward compatibility, identical behaviour. rectangle/ellipse/magic_wand also accept a grounded `placement` (NAME a region/point instead of guessing pixels — resolved + gate-verified). The geometric/color/wand modes take selection_type (replace|add|subtract|intersect) to combine with an existing selection and return a rich selection_info bundle — verify it (or ps_get_selection_preview) before committing to a mask.',
+                description: 'Create a NEW selection — choose with `mode`. (To edit the CURRENT selection instead — including growing it by colour similarity — use ps_modify_selection.) `all` selects the canvas; `none` deselects; `inverse` inverts the current selection (e.g. select the subject, then inverse to act on the background). `rectangle` (left/top/right/bottom, optional feather_px to avoid hard block-edges in smooth sky). `ellipse` (left/top/right/bottom bounding box + anti_alias — circles/ovals). `color_range` (target red/green/blue + fuzziness — "select all the red / skin tones"). `luminance_range` (highlights/shadows/midtones — foundation for glow / dodge-burn). `magic_wand` (click x/y + tolerance, contiguous). `focus_area` selects by depth of field rather than subject or colour (+in_focus_radius, soft_mask) — check whole_canvas_selected/warning in the result before trusting it. `grow` / `similar` are DEPRECATED here (they act on the CURRENT selection, not a new one) — use ps_modify_selection(op=grow|similar) instead; kept for one release for backward compatibility, identical behaviour. rectangle/ellipse/magic_wand also accept a grounded `placement` (NAME a region/point instead of guessing pixels — resolved + gate-verified). The geometric/color/wand modes take selection_type (replace|add|subtract|intersect) to combine with an existing selection and return a rich selection_info bundle — verify it (or ps_get_selection_preview) before committing to a mask.',
                 inputSchema: SELECT_INPUT_SCHEMA,
                 outputSchema: {
                     type: 'object',
@@ -606,6 +633,24 @@ export function createSelectionTools(connection, snippetClient, client = new Onn
                         preset: { type: 'string' },
                         point_count: { type: 'number' },
                         placement: { type: 'object' },
+                        strategy_used: {
+                            type: 'string',
+                            description: 'mode=focus_area: "executeAction:focusMask".',
+                        },
+                        in_focus_radius: { type: 'number', description: 'mode=focus_area: radius used.' },
+                        soft_mask: { type: 'boolean', description: 'mode=focus_area: soft_mask used.' },
+                        active_layer_temporarily_changed: {
+                            type: 'boolean',
+                            description: 'mode=focus_area: true if the active layer was not an ordinary pixel layer and detection was temporarily retargeted to the bottom layer. Restored before return.',
+                        },
+                        whole_canvas_selected: {
+                            type: 'boolean',
+                            description: 'mode=focus_area: true when the RAW detection (before any selection_type combine) covered essentially the entire canvas — usually a non-result. selection_info reports the FINAL, post-combine selection and the two can legitimately disagree.',
+                        },
+                        warning: {
+                            type: ['string', 'null'],
+                            description: 'mode=focus_area: set when whole_canvas_selected is true.',
+                        },
                         selection_info: selectionInfoFragment,
                     },
                 },
@@ -660,7 +705,7 @@ export function createSelectionTools(connection, snippetClient, client = new Onn
         {
             tool: {
                 name: 'ps_get_selection_preview',
-                description: 'Render TWO inline JPEGs so the agent can visually verify what is currently selected: (1) an OVERLAY of the document with a 50% red wash over the selected area (Quick Mask-style — most intuitive); (2) a B/W MASK where black = selected, white = not. Heavier than the selection_info bundle (~2-4s) — call this when the stats look off or before committing a mask. Does NOT modify the source document.',
+                description: "Render an inline JPEG so the agent can visually verify what is currently selected: by default a red-wash OVERLAY (50% red over the selected area, Quick Mask-style — most intuitive); pass `image:'mask'` for a B/W MASK (black = selected, white = not) instead, or `image:'both'` for both. selection_info is always returned regardless of `image`. Heavier than the selection_info bundle alone (~2-4s) — call this when the stats look off or before committing a mask. Does NOT modify the source document.",
                 inputSchema: selectionPreviewSchema,
                 outputSchema: {
                     type: 'object',
@@ -673,7 +718,7 @@ export function createSelectionTools(connection, snippetClient, client = new Onn
                     },
                 },
                 annotations: {
-                    title: 'Get Selection Preview (overlay + mask)',
+                    title: 'Get Selection Preview',
                     readOnlyHint: true,
                     idempotentHint: true,
                 },
@@ -817,42 +862,6 @@ export function createSelectionTools(connection, snippetClient, client = new Onn
             },
             handler: async (args) => selectSky(connection, snippetClient, args),
         },
-        {
-            tool: {
-                name: 'ps_select_focus_area',
-                description: "Run Photoshop's \"Focus Area\" — select what the lens rendered SHARP, by depth of field rather than by subject or colour. Use it when the thing you want is defined by focus and not by what it is: lifting a subject off a bokeh background, masking the in-focus plane of a macro shot, or grabbing a shallow-depth foreground that Select Subject splits badly. Takes NO coordinates. in_focus_radius widens (higher) or narrows (lower) what counts as sharp; soft_mask=true gives feathered edges instead of a hard boundary. Analyses the ACTIVE layer, so target the photographic pixels you mean. If the active layer is not a raster layer at all (adjustment, smart object, text, shape), detection is retargeted to the bottom layer and active_layer_temporarily_changed comes back true — check it, because the analysed layer was then NOT the one you selected. An EMPTY raster layer cannot be told apart by kind, so it is not retargeted; it surfaces instead as an error or as whole_canvas_selected. whole_canvas_selected and warning diagnose Focus Area's RAW detection, measured BEFORE any selection_type combine — a uniformly sharp image (or too high an in_focus_radius) trips them even when combining then folds the result down to something small. Check whole_canvas_selected first; selection_info separately reports the FINAL, post-combine selection and can disagree with it by design (e.g. selection_type='subtract' against an existing selection), so read selection_info for what actually got selected, not as a substitute for whole_canvas_selected.",
-                inputSchema: selectFocusAreaSchema,
-                outputSchema: {
-                    type: 'object',
-                    properties: {
-                        selected: { type: 'boolean' },
-                        method: { type: 'string' },
-                        strategy_used: { type: 'string' },
-                        in_focus_radius: { type: 'number' },
-                        soft_mask: { type: 'boolean' },
-                        active_layer_temporarily_changed: {
-                            type: 'boolean',
-                            description: 'True if the active layer was not an ordinary pixel layer and detection was temporarily retargeted to the bottom layer. The original active layer is restored before return.',
-                        },
-                        whole_canvas_selected: {
-                            type: 'boolean',
-                            description: "True when Focus Area's RAW detection covered essentially the entire canvas — usually a non-result (radius too high, or nothing photographic to analyse). Measured BEFORE combining with any prior selection, so it describes the detection step, not the final selection: selection_info reports the FINAL, post-combine result and the two can legitimately disagree, e.g. selection_type='subtract' against an existing selection can leave this true while selection_info.area_percent is well under 100.",
-                        },
-                        warning: {
-                            type: ['string', 'null'],
-                            description: 'Set when whole_canvas_selected is true. Also describes the RAW detection, not the final post-combine selection.',
-                        },
-                        selection_type: { type: 'string' },
-                        selection_info: selectionInfoFragment,
-                    },
-                },
-                annotations: {
-                    title: 'Select Focus Area',
-                    idempotentHint: true,
-                },
-            },
-            handler: async (args) => selectFocusArea(connection, snippetClient, args),
-        },
     ];
 }
 const selectSubjectSchema = {
@@ -877,72 +886,77 @@ const selectSkySchema = {
         selection_type: selectionTypeFragment,
     },
 };
-const selectFocusAreaSchema = {
-    type: 'object',
-    properties: {
-        in_focus_radius: {
-            type: 'number',
-            description: 'How much blur still counts as "in focus", in pixels. Higher pulls more of the soft transition zone into the selection; lower keeps only the crisply resolved plane. 4.07 is the Photoshop dialog default and a sane starting point. The useful band is narrow, and a radius well above the default selects the entire frame — so move in small steps and CHECK the returned area_percent and whole_canvas_selected: a selection covering essentially everything means the radius is too high and the result is worthless, even though the call reports success.',
-            default: 4.07,
-            minimum: 0.1,
-            maximum: 15,
-        },
-        soft_mask: {
-            type: 'boolean',
-            description: 'False (default) yields a hard-edged selection — every pixel fully in or fully out, which is what you want before ps_modify_selection feathering. True lets Photoshop feather the focus falloff itself, useful when the subject edge is genuinely gradual (hair, fur, motion).',
-            default: false,
-        },
-        selection_type: selectionTypeFragment,
-    },
-};
+function selectionInfoOf(result) {
+    return result.selection_info;
+}
 async function selectFocusArea(connection, snippetClient, rawArgs) {
-    return runSnippetTool({
-        connection,
-        snippetClient,
-        rawArgs,
-        schema: selectFocusAreaSchema,
-        snippet: 'selectFocusArea',
-        errorPrefix: 'Error running Focus Area selection',
-        timeoutMs: SELECT_FOCUS_AREA_TIMEOUT_MS,
-        params: (args) => ({
+    try {
+        const args = validateArgs(selectFocusAreaSchema, rawArgs);
+        const selectionType = normalizeSelectionType(args.selection_type);
+        const script = await snippetClient.build('selectFocusArea', {
             inFocusRadius: args.in_focus_radius ?? 4.07,
             softMask: args.soft_mask ?? false,
-            selectionType: normalizeSelectionType(args.selection_type),
-        }),
-        successText: (_result, args) => `Focus Area selection (${normalizeSelectionType(args.selection_type)}) complete`,
-    });
+            selectionType,
+        });
+        const result = (await runScript(connection, script, SELECT_FOCUS_AREA_TIMEOUT_MS));
+        let text = describeSelectionFacts(`Focus Area selection (${selectionType})`, selectionInfoOf(result));
+        if (result.warning) {
+            text += ` WARNING: ${String(result.warning)}`;
+        }
+        return {
+            content: [{ type: 'text', text }],
+            structuredContent: result,
+        };
+    }
+    catch (error) {
+        return toolErrorResult('Error running Focus Area selection', error);
+    }
 }
 async function selectSubject(connection, snippetClient, rawArgs) {
-    return runSnippetTool({
-        connection,
-        snippetClient,
-        rawArgs,
-        schema: selectSubjectSchema,
-        snippet: 'selectSubject',
-        errorPrefix: 'Error running Select Subject',
-        timeoutMs: SELECT_SUBJECT_TIMEOUT_MS,
-        params: (args) => ({
+    try {
+        const args = validateArgs(selectSubjectSchema, rawArgs);
+        const selectionType = normalizeSelectionType(args.selection_type);
+        const script = await snippetClient.build('selectSubject', {
             sampleAllLayers: args.sample_all_layers ?? true,
-            selectionType: normalizeSelectionType(args.selection_type),
-        }),
-        successText: (_result, args) => `Select Subject (${normalizeSelectionType(args.selection_type)}) complete`,
-    });
+            selectionType,
+        });
+        const result = (await runScript(connection, script, SELECT_SUBJECT_TIMEOUT_MS));
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: describeSelectionFacts(`Select Subject (${selectionType})`, selectionInfoOf(result)),
+                },
+            ],
+            structuredContent: result,
+        };
+    }
+    catch (error) {
+        return toolErrorResult('Error running Select Subject', error);
+    }
 }
 async function selectSky(connection, snippetClient, rawArgs) {
-    return runSnippetTool({
-        connection,
-        snippetClient,
-        rawArgs,
-        schema: selectSkySchema,
-        snippet: 'selectSky',
-        errorPrefix: 'Error running Select Sky',
-        timeoutMs: SELECT_SKY_TIMEOUT_MS,
-        params: (args) => ({
+    try {
+        const args = validateArgs(selectSkySchema, rawArgs);
+        const selectionType = normalizeSelectionType(args.selection_type);
+        const script = await snippetClient.build('selectSky', {
             sampleAllLayers: args.sample_all_layers ?? true,
-            selectionType: normalizeSelectionType(args.selection_type),
-        }),
-        successText: (_result, args) => `Select Sky (${normalizeSelectionType(args.selection_type)}) complete`,
-    });
+            selectionType,
+        });
+        const result = (await runScript(connection, script, SELECT_SKY_TIMEOUT_MS));
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: describeSelectionFacts(`Select Sky (${selectionType})`, selectionInfoOf(result)),
+                },
+            ],
+            structuredContent: result,
+        };
+    }
+    catch (error) {
+        return toolErrorResult('Error running Select Sky', error);
+    }
 }
 async function select(connection, snippetClient, detClient, rawArgs) {
     const mode = rawArgs.mode;
@@ -974,6 +988,8 @@ async function select(connection, snippetClient, detClient, rawArgs) {
             return selectColorPreset(connection, snippetClient, 'out_of_gamut', rest);
         case 'polygon':
             return selectPolygon(connection, snippetClient, rest);
+        case 'focus_area':
+            return selectFocusArea(connection, snippetClient, rest);
         default:
             return unknownDiscriminator('select mode', mode, SELECT_MODES);
     }
@@ -1038,6 +1054,25 @@ export function normalizeSelectionType(raw) {
         ? v
         : 'replace';
 }
+async function readSelectionInfo(connection, snippetClient) {
+    const script = await snippetClient.build('getSelectionState');
+    return (await runScript(connection, script));
+}
+function describeSelectionFacts(label, info) {
+    if (!info || typeof info.has_selection !== 'boolean') {
+        return `${label} complete — selection facts unknown (the result carried no readable selection_info).`;
+    }
+    if (!info.has_selection) {
+        return `${label} completed but the resulting selection is empty.`;
+    }
+    if (!info.bounds) {
+        const reason = typeof info.error === 'string' ? ` (${info.error})` : '';
+        return `${label} complete — a selection exists but its bounds/coverage could not be measured${reason}.`;
+    }
+    const b = info.bounds;
+    const pct = (info.area_percent ?? 0).toFixed(1);
+    return `${label} complete — selection (${b.left}, ${b.top}) to (${b.right}, ${b.bottom}), ${pct}% of canvas.`;
+}
 function describeMaskOutcome(result) {
     if (result.maskCreated)
         return 'Layer mask created from selection';
@@ -1395,8 +1430,7 @@ async function magicWand(connection, snippetClient, detClient, rawArgs) {
 }
 export async function getSelectionInfoHandler(connection, snippetClient) {
     try {
-        const script = await snippetClient.build('getSelectionState');
-        const result = (await runScript(connection, script));
+        const result = (await readSelectionInfo(connection, snippetClient));
         const summary = result.has_selection
             ? `Active selection: ${(result.area_percent ?? 0).toFixed(1)}% of canvas (${(result.pixel_count ?? 0).toLocaleString()} px), bounds-fill ratio ${(result.bounds_fill_ratio ?? 0).toFixed(2)}, edge complexity ${(result.edge_complexity ?? 0).toFixed(2)}`
             : 'No active selection.';
@@ -1413,6 +1447,7 @@ async function getSelectionPreview(connection, snippetClient, rawArgs) {
     try {
         const args = validateArgs(selectionPreviewSchema, rawArgs);
         const maxDimension = args.max_dimension ?? 800;
+        const image = args.image ?? 'overlay';
         const dir = await TempDir.create('editmamei-sel-preview-');
         try {
             const overlayPath = dir.path('overlay.jpg');
@@ -1436,17 +1471,28 @@ async function getSelectionPreview(connection, snippetClient, rawArgs) {
             }
             const overlayBytes = await readFile(overlayPath);
             const maskBytes = await readFile(maskPath);
-            const overlayB64 = overlayBytes.toString('base64');
-            const maskB64 = maskBytes.toString('base64');
+            const text = image === 'both'
+                ? `Selection preview rendered. Image 1 = overlay (red wash on selected area). Image 2 = mask (black=selected, white=not).`
+                : image === 'mask'
+                    ? `Selection preview rendered. Image 1 = mask (black=selected, white=not).`
+                    : `Selection preview rendered. Image 1 = overlay (red wash on selected area).`;
+            const content = [{ type: 'text', text }];
+            if (image === 'overlay' || image === 'both') {
+                content.push({
+                    type: 'image',
+                    data: overlayBytes.toString('base64'),
+                    mimeType: 'image/jpeg',
+                });
+            }
+            if (image === 'mask' || image === 'both') {
+                content.push({
+                    type: 'image',
+                    data: maskBytes.toString('base64'),
+                    mimeType: 'image/jpeg',
+                });
+            }
             return {
-                content: [
-                    {
-                        type: 'text',
-                        text: `Selection preview rendered. Image 1 = overlay (red wash on selected area). Image 2 = mask (black=selected, white=not).`,
-                    },
-                    { type: 'image', data: overlayB64, mimeType: 'image/jpeg' },
-                    { type: 'image', data: maskB64, mimeType: 'image/jpeg' },
-                ],
+                content,
                 structuredContent: {
                     rendered: true,
                     max_dimension: result.max_dimension ?? maxDimension,