editmamei 1.1.0 → 1.2.1

package/dist/tools/document-tools.js

@@ -36,6 +36,17 @@ const createDocumentSchema = {
     },
     required: ['width', 'height'],
 };
+const documentTargetProps = {
+    name: {
+        type: 'string',
+        description: "Target an open document by its exact Photoshop name, INCLUDING the extension as shown in the tab (e.g. 'portrait.jpg', not 'portrait'). If two open documents share a name the call fails rather than guessing — target by id instead.",
+    },
+    id: {
+        type: 'integer',
+        minimum: 1,
+        description: 'Target an open document by its Photoshop document id. Unambiguous — prefer this when names collide.',
+    },
+};
 const closeDocumentSchema = {
     type: 'object',
     properties: {
@@ -44,8 +55,22 @@ const closeDocumentSchema = {
             description: 'Whether to save changes before closing',
             default: false,
         },
+        ...documentTargetProps,
     },
 };
+const DOCUMENT_OPS = ['list', 'activate'];
+const documentSchema = {
+    type: 'object',
+    properties: {
+        op: {
+            type: 'string',
+            enum: [...DOCUMENT_OPS],
+            description: 'list: every open document (index, id, name, path, saved, active, dimensions) — safe to call when NOTHING is open, which is the point. activate: make one of them the active document, by name or id.',
+        },
+        ...documentTargetProps,
+    },
+    required: ['op'],
+};
 const openDocumentSchema = {
     type: 'object',
     properties: {
@@ -180,10 +205,57 @@ export function createDocumentTools(connection, snippetClient) {
             },
             handler: async (args) => createDocument(connection, snippetClient, args),
         },
+        {
+            tool: {
+                name: 'ps_document',
+                description: "See and steer WHICH documents are open, without touching their content. op=list answers 'what is open, which one is active, and does it have unsaved changes' — and it is the one document tool that works when nothing is open at all, so it is the recovery read after a 'No document is open' failure. op=activate switches the active document by name or id, which is how you fix having edited the wrong one. Read-only with respect to pixels; use ps_open_document to load a file and ps_close_document to close one.",
+                inputSchema: documentSchema,
+                outputSchema: {
+                    type: 'object',
+                    properties: {
+                        op: { type: 'string' },
+                        count: { type: 'number' },
+                        documents: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    index: { type: 'number' },
+                                    id: { type: 'number' },
+                                    name: { type: 'string' },
+                                    path: {
+                                        type: ['string', 'null'],
+                                        description: 'Absolute path, or null for a document never saved to disk.',
+                                    },
+                                    saved: {
+                                        type: ['boolean', 'null'],
+                                        description: 'False when the document has unsaved changes. Null when Photoshop would not report it.',
+                                    },
+                                    active: { type: 'boolean' },
+                                    width_px: { type: ['number', 'null'] },
+                                    height_px: { type: ['number', 'null'] },
+                                },
+                            },
+                        },
+                        activated: { type: 'boolean' },
+                        id: { type: 'number' },
+                        name: { type: 'string' },
+                        context: { type: 'object' },
+                    },
+                    required: ['op'],
+                },
+                annotations: {
+                    title: 'List / Activate Documents',
+                    readOnlyHint: true,
+                    idempotentHint: true,
+                },
+            },
+            handler: async (args) => documentOp(connection, snippetClient, args),
+        },
         {
             tool: {
                 name: 'ps_close_document',
-                description: 'Close the active Photoshop document. Destructive if save=false and the document has unsaved changes. Returns the closed document name plus a fresh context block (which document, if any, is active afterwards).',
+                description: 'Close a Photoshop document — the active one by default, or a specific one by name or id. Destructive if save=false and the document has unsaved changes. If two open documents share the requested name the call fails rather than guessing. Returns the closed document name plus a fresh context block (which document, if any, is active afterwards).',
                 inputSchema: closeDocumentSchema,
                 outputSchema: {
                     type: 'object',
@@ -340,11 +412,80 @@ async function createDocument(connection, snippetClient, rawArgs) {
         successText: (_result, args) => `Document created: ${args.width}x${args.height}px at ${args.resolution}dpi (${args.color_mode})`,
     });
 }
+function documentTargetArgs(args) {
+    const out = {};
+    if (typeof args.name === 'string' && args.name !== '')
+        out.name = args.name;
+    if (typeof args.id === 'number')
+        out.id = args.id;
+    return out;
+}
+function emptySelectorError(args) {
+    if (typeof args.name === 'string' && args.name === '') {
+        return 'name was an empty string. Pass a real document name, or omit name entirely to act on the active document.';
+    }
+    return null;
+}
+async function documentOp(connection, snippetClient, rawArgs) {
+    let errorPrefix = 'Error reading documents';
+    try {
+        const args = validateArgs(documentSchema, rawArgs);
+        const op = args.op;
+        const target = documentTargetArgs(args);
+        if (op === 'activate') {
+            errorPrefix = 'Error activating document';
+            const empty = emptySelectorError(args);
+            if (empty !== null)
+                return toolErrorResult(errorPrefix, new Error(empty));
+            if (Object.keys(target).length === 0) {
+                return toolErrorResult(errorPrefix, new Error('op=activate needs a name or an id. Call op=list to see what is open.'));
+            }
+            const script = await snippetClient.build('activateDocument', target);
+            const result = (await runScript(connection, script));
+            return {
+                content: [{ type: 'text', text: `Activated "${result.name}" (id ${result.id}).` }],
+                structuredContent: {
+                    op,
+                    activated: true,
+                    id: result.id,
+                    name: result.name,
+                    context: result.context,
+                },
+            };
+        }
+        const script = await snippetClient.build('listDocuments', {});
+        const result = (await runScript(connection, script));
+        const docs = result.documents ?? [];
+        const summary = docs.length
+            ? `${docs.length} open document(s): ${docs
+                .map((d) => `${d.name} (id ${d.id}${d.active ? ', ACTIVE' : ''}${d.saved === false ? ', unsaved changes' : ''})`)
+                .join('; ')}.`
+            : 'No documents are open in Photoshop. Open one with ps_open_document, or create one with ps_create_document.';
+        return {
+            content: [{ type: 'text', text: summary }],
+            structuredContent: {
+                op,
+                count: docs.length,
+                documents: docs,
+                context: result.context,
+            },
+        };
+    }
+    catch (error) {
+        return toolErrorResult(errorPrefix, error);
+    }
+}
 async function closeDocument(connection, snippetClient, rawArgs) {
     try {
         const args = validateArgs(closeDocumentSchema, rawArgs);
         const save = args.save;
-        const script = await snippetClient.build('closeDocument', { save });
+        const empty = emptySelectorError(args);
+        if (empty !== null)
+            return toolErrorResult('Error closing document', new Error(empty));
+        const script = await snippetClient.build('closeDocument', {
+            save,
+            ...documentTargetArgs(args),
+        });
         const result = (await runScript(connection, script));
         return {
             content: [

package/dist/tools/filter-tools.js

@@ -1010,20 +1010,6 @@ export function createFilterTools(connection, snippetClient, client = new OnnxLa
             },
             handler: async (args) => runFilterTool(connection, snippetClient, client, args),
         },
-        {
-            tool: {
-                name: 'ps_apply_filter',
-                description: `DEPRECATED — use ps_filter instead (kept for one release for backward compatibility, identical behaviour). ${FILTER_DESCRIPTION}`,
-                inputSchema: FILTER_INPUT_SCHEMA,
-                outputSchema: FILTER_OUTPUT_SCHEMA,
-                annotations: {
-                    title: 'Apply Filter',
-                    destructiveHint: true,
-                    idempotentHint: false,
-                },
-            },
-            handler: async (args) => runFilterTool(connection, snippetClient, client, args),
-        },
     ];
 }
 async function runFilterTool(connection, snippetClient, detClient, rawArgs) {

package/dist/tools/group-tools.js

@@ -41,7 +41,7 @@ const moveLayerToGroupSchema = {
     properties: {
         layer_name: {
             type: 'string',
-            description: 'Name of the layer to move (recursive search).',
+            description: 'Name of the layer to move (recursive search). A layer is preferred over a group of the same name; a group is moved only when no layer matches, which is how one group is nested inside another.',
         },
         group_name: {
             type: 'string',
@@ -187,102 +187,6 @@ export function createGroupTools(connection, snippetClient) {
             },
             handler: async (args) => groupDispatch(connection, snippetClient, args),
         },
-        {
-            tool: {
-                name: 'ps_create_group',
-                description: `DEPRECATED — use ps_group(op=create) instead (kept for one release for backward compatibility, identical behaviour). Create a new layer group (LayerSet) above the active layer with the given name — hoisted out of the active layer's group by default even though Photoshop's own Mk-layerSection placement rule would otherwise nest it INSIDE that group (pass into_active_group:true to keep that native nesting; this is why groups created one after another land as siblings rather than nested, so bottom-to-top group creation is safe). Optionally moves existing layers into it in one step. Non-destructive. Foundational for structured non-destructive editing — e.g. group all adjustment layers into an "edits" group so you can A/B toggle the whole stack via group visibility.`,
-                inputSchema: createGroupSchema,
-                outputSchema: {
-                    type: 'object',
-                    properties: {
-                        created: { type: 'boolean' },
-                        groupName: { type: 'string' },
-                        moved_count: { type: 'number' },
-                        not_found: { type: 'array', items: { type: 'string' } },
-                        hoisted: {
-                            type: 'boolean',
-                            description: 'True when the new group 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' },
-                    },
-                },
-                annotations: {
-                    title: 'Create Layer Group',
-                    idempotentHint: false,
-                },
-            },
-            handler: async (args) => createGroup(connection, snippetClient, args),
-        },
-        {
-            tool: {
-                name: 'ps_move_layer_to_group',
-                description: 'DEPRECATED — use ps_group(op=add_layer) instead (kept for one release for backward compatibility, identical behaviour). Move a named layer into a named group. The layer is placed at the top of the group stack. Both layer_name and group_name are looked up recursively. Throws if either is not found, or if the layer IS the group itself.',
-                inputSchema: moveLayerToGroupSchema,
-                outputSchema: {
-                    type: 'object',
-                    properties: {
-                        moved: { type: 'boolean' },
-                        layerName: { type: 'string' },
-                        groupName: { type: 'string' },
-                        context: { type: 'object' },
-                    },
-                },
-                annotations: {
-                    title: 'Move Layer Into Group',
-                    idempotentHint: false,
-                },
-            },
-            handler: async (args) => moveLayerToGroup(connection, snippetClient, args),
-        },
-        {
-            tool: {
-                name: 'ps_set_group_blend_mode',
-                description: "DEPRECATED — use ps_group(op=set_blend_mode) instead (kept for one release for backward compatibility, identical behaviour). Set a group's blend mode. The default for new groups is PASSTHROUGH (adjustments inside affect layers below the group). Change to NORMAL when treating the group as a single composite — required for masking a stack of adjustments with one mask.",
-                inputSchema: setGroupBlendModeSchema,
-                outputSchema: {
-                    type: 'object',
-                    properties: {
-                        set: { type: 'boolean' },
-                        groupName: { type: 'string' },
-                        blendMode: { type: 'string' },
-                        context: { type: 'object' },
-                    },
-                },
-                annotations: {
-                    title: 'Set Group Blend Mode',
-                    idempotentHint: true,
-                },
-            },
-            handler: async (args) => setGroupBlendMode(connection, snippetClient, args),
-        },
-        {
-            tool: {
-                name: 'ps_ungroup',
-                description: 'DEPRECATED — use ps_group(op=ungroup) instead (kept for one release for backward compatibility, identical behaviour). DESTRUCTIVE structural change: Dissolve a group, leaving its contents at the parent level in their existing stack order. The group itself is removed. Requires confirm:true. Recoverable only via Edit > Undo.',
-                inputSchema: ungroupSchema,
-                outputSchema: {
-                    type: 'object',
-                    properties: {
-                        ungrouped: { type: 'boolean' },
-                        groupName: { type: 'string' },
-                        children_promoted: { type: 'number' },
-                        child_names: { type: 'array', items: { type: 'string' } },
-                        context: { type: 'object' },
-                    },
-                },
-                annotations: {
-                    title: 'Ungroup Layer Set (destructive structural change)',
-                    destructiveHint: true,
-                    idempotentHint: false,
-                },
-            },
-            handler: async (args) => ungroup(connection, snippetClient, args),
-        },
         {
             tool: {
                 name: 'ps_clipping_mask',
@@ -305,28 +209,6 @@ export function createGroupTools(connection, snippetClient) {
             },
             handler: async (args) => clippingMask(connection, snippetClient, args),
         },
-        {
-            tool: {
-                name: 'ps_delete_group',
-                description: 'DEPRECATED — use ps_group(op=delete) instead (kept for one release for backward compatibility, identical behaviour). DESTRUCTIVE: Delete a group AND ALL its contents (including nested groups and their layers). Requires confirm:true because the destructive scope is much larger than a single-layer delete. Recoverable only via Edit > Undo. To dissolve a group while keeping its contents, use ps_ungroup instead.',
-                inputSchema: deleteGroupSchema,
-                outputSchema: {
-                    type: 'object',
-                    properties: {
-                        deleted: { type: 'boolean' },
-                        groupName: { type: 'string' },
-                        descendants_deleted: { type: 'number' },
-                        context: { type: 'object' },
-                    },
-                },
-                annotations: {
-                    title: 'Delete Group (destructive, recursive)',
-                    destructiveHint: true,
-                    idempotentHint: false,
-                },
-            },
-            handler: async (args) => deleteGroup(connection, snippetClient, args),
-        },
     ];
 }
 async function clippingMask(connection, snippetClient, rawArgs) {

package/dist/tools/layer-tools.js

@@ -220,7 +220,7 @@ export function createLayerTools(connection, snippetClient) {
         {
             tool: {
                 name: 'ps_delete_layer',
-                description: 'DESTRUCTIVE: Delete a layer. With no arg, deletes the currently active layer (backward-compatible). With `name`, recurses into groups and deletes the first layer matching that name — useful for cleanup workflows where the dead layer is not currently active. Recoverable only via Edit > Undo. To delete a group and all its contents, use ps_delete_group.',
+                description: 'DESTRUCTIVE: Delete a layer. With no arg, deletes the currently active layer (backward-compatible). With `name`, recurses into groups and deletes the first LAYER matching that name — useful for cleanup workflows where the dead layer is not currently active. A name that matches a group is refused rather than deleted; use ps_group(op=delete) to delete a group and all its contents. Recoverable only via Edit > Undo.',
                 inputSchema: deleteLayerSchema,
                 outputSchema: {
                     type: 'object',
@@ -238,29 +238,6 @@ export function createLayerTools(connection, snippetClient) {
             },
             handler: async (args) => deleteLayer(connection, snippetClient, args),
         },
-        {
-            tool: {
-                name: 'ps_create_text_layer',
-                description: 'DEPRECATED — use ps_text(op=create) instead (kept for one release for backward compatibility, identical behaviour). Create a new text layer with the given content, position, and font size. The text is editable (vector). Use ps_text (op=set_font / set_color / set_alignment) afterwards to style.',
-                inputSchema: createTextLayerSchema,
-                outputSchema: {
-                    type: 'object',
-                    properties: {
-                        created: { type: 'boolean' },
-                        layerName: { type: 'string' },
-                        text: { type: 'string' },
-                        position: { type: 'object' },
-                        fontSize: { type: 'number' },
-                        context: { type: 'object' },
-                    },
-                },
-                annotations: {
-                    title: 'Create Text Layer',
-                    idempotentHint: false,
-                },
-            },
-            handler: async (args) => createTextLayer(connection, snippetClient, args),
-        },
         {
             tool: {
                 name: 'ps_fill_layer',

package/dist/tools/scene-tools.js

@@ -4,7 +4,7 @@ import { OnnxDetectionClient } from '../detection/detection-client.js';
 import { ANNOTATED_PREVIEW_JPEG_QUALITY } from '../utils/jpeg-quality.js';
 import { buildSceneModel } from '../perception/scene-model.js';
 import { resolveSelection, SELECT_REFERENCE_TARGETS, } from '../perception/select-recipes.js';
-import { precomputeRegions, loadPrecomputedRegion, saveSelectionAsSceneChannel, CHANNEL_PREFIX, } from '../perception/region-precompute.js';
+import { precomputeRegions, candidateMenu, invalidateSceneChannelsIfStale, loadPrecomputedRegion, saveSelectionAsSceneChannel, CHANNEL_PREFIX, } from '../perception/region-precompute.js';
 import { toolErrorResult } from '../utils/tool-helpers.js';
 import { Logger } from '../utils/logger.js';
 import { isProEntitled } from '../license/entitlement.js';
@@ -54,7 +54,6 @@ function faceMenuFor(model, hasPro) {
         key: `${CHANNEL_PREFIX}${target}`,
         target,
         method: 'face_mesh',
-        confidence: 1,
         bounds: null,
         on_demand: true,
     }));
@@ -82,8 +81,8 @@ const sceneSchema = {
         },
         save_regions: {
             type: 'boolean',
-            default: true,
-            description: 'Precompute every confident region (sky/ground/shadows/highlights/skin/subject/face — and, on a Pro host with a face, the face-feature set scene:face_skin/_eyes/_brows/_lips/_teeth/_nose/_under_eye/_cheeks) and SAVE each as a managed `scene:*` alpha channel, returning the `regions` MENU of what is confidently selectable (each with its method + confidence). ps_select_by_reference then loads the saved channel instantly. Set false for a light read with no channels. The `scene:` channel-name prefix is RESERVED: channels matching it are treated as derived and are deleted on the next scene read and on ps_save_psd, so do not give a channel you want to keep a `scene:`-prefixed name.',
+            default: false,
+            description: 'EAGERLY derive every region (sky/ground/shadows/highlights/skin/subject/face) up front and SAVE each confident one as a managed `scene:*` alpha channel, so the returned menu carries a verified method + confidence for each. Costs one derive per target — measured at ~21s on a 4898x3265 layered document, against a 30s script timeout — so it is OFF by default. Leave it off unless you specifically need every region scored in one call: the default advertises the same menu as `on_demand` entries and ps_select_by_reference derives whichever region you actually ask for (then saves its channel, so repeats of THAT region are instant). The `scene:` channel-name prefix is RESERVED: channels matching it are treated as derived and are deleted on the next scene read and on ps_save_psd, so do not give a channel you want to keep a `scene:`-prefixed name.',
         },
         composition_context: {
             type: 'object',
@@ -143,7 +142,7 @@ async function scene(connection, snippet, client, rawArgs, proRefine, hasPro = f
         const args = validateArgs(sceneSchema, rawArgs);
         const annotate = args.annotate ?? true;
         const refresh = args.refresh ?? false;
-        const saveRegions = args.save_regions ?? true;
+        const saveRegions = args.save_regions ?? false;
         const built = await buildSceneModel(connection, snippet, client, {
             useCache: !refresh,
             maxDimension: args.max_dimension,
@@ -165,6 +164,14 @@ async function scene(connection, snippet, client, rawArgs, proRefine, hasPro = f
                 precomputeOk = false;
             }
         }
+        else {
+            try {
+                await invalidateSceneChannelsIfStale(connection, model.provenance.cache_key);
+            }
+            catch {
+            }
+            regions = [...candidateMenu(model), ...faceMenuFor(model, hasPro)];
+        }
         const content = [];
         if (annotate && built.decoded) {
             try {
@@ -181,19 +188,25 @@ async function scene(connection, snippet, client, rawArgs, proRefine, hasPro = f
             catch {
             }
         }
-        const menuText = !saveRegions
-            ? ''
-            : regions.length
+        const named = (r) => `${r.target}${r.label ? `:${r.label}` : ''}`;
+        const menuText = !regions.length
+            ? saveRegions
+                ? ' No confident named regions detected here.'
+                : ''
+            : saveRegions
                 ? ` Confident regions (select by name): ${regions
-                    .map((r) => `${r.target}${r.label ? `:${r.label}` : ''} ${r.confidence.toFixed(2)}`)
+                    .map((r) => `${named(r)}${r.confidence === undefined ? '' : ` ${r.confidence.toFixed(2)}`}`)
                     .join(', ')}.`
-                : ' No confident named regions detected here.';
+                :
+                    ` Selectable by name (each resolved when you ask for it, not yet scored): ${regions
+                        .map(named)
+                        .join(', ')}.`;
         content.push({ type: 'text', text: summarizeScene(model) + menuText });
         return {
             content,
             structuredContent: {
                 ...model,
-                regions: reconcileRegions(model, regions, saveRegions && precomputeOk),
+                regions: reconcileRegions(model, regions, saveRegions ? (precomputeOk ? 'resolved' : 'unresolved') : 'candidate'),
                 region_menu: regions,
             },
         };
@@ -202,15 +215,23 @@ async function scene(connection, snippet, client, rawArgs, proRefine, hasPro = f
         return toolErrorResult('Error reading scene', error);
     }
 }
-function reconcileRegions(model, menu, resolved) {
+export const SELECTABLE_STATES = [
+    'selectable',
+    'not_selectable',
+    'candidate',
+    'not_resolved',
+];
+function reconcileRegions(model, menu, mode) {
     return model.regions.map((r) => {
         const base = r;
-        if (!resolved) {
+        if (mode !== 'resolved') {
+            const advertised = mode === 'candidate' && menu.some((m) => m.target === r.kind);
             return {
                 ...base,
                 coverage_is_estimate: true,
                 selectable: null,
-                selectable_state: 'not_resolved',
+                selectable_state: advertised ? 'candidate' : 'not_resolved',
+                ...(advertised ? { selectable_via: 'on_demand' } : {}),
             };
         }
         const hit = menu.find((m) => m.target === r.kind);
@@ -290,14 +311,17 @@ async function selectByReference(connection, snippet, client, rawArgs, proRefine
         const args = validateArgs(selectByReferenceSchema, rawArgs);
         const target = args.target;
         const refresh = args.refresh ?? false;
-        if (!refresh) {
+        const discriminated = args.label !== undefined ||
+            args.instance !== undefined ||
+            args.composition_context !== undefined;
+        if (!refresh && !discriminated) {
             const loaded = await loadPrecomputedRegion(connection, target);
             if (loaded) {
                 return {
                     content: [
                         {
                             type: 'text',
-                            text: `Selected "${target}" from the saved scene:${target} channel (precomputed by ps_read_scene). Verify with ps_get_selection_preview.`,
+                            text: `Selected "${target}" from the saved scene:${target} channel (cached by an earlier derive). If the image changed since, re-run with refresh:true. Verify with ps_get_selection_preview.`,
                         },
                     ],
                     structuredContent: {
@@ -326,7 +350,7 @@ async function selectByReference(connection, snippet, client, rawArgs, proRefine
             proRefine,
             skyCtx: skyCtxFrom(built),
         });
-        if (res.passed && target.startsWith('face_')) {
+        if (res.passed && !discriminated) {
             try {
                 await saveSelectionAsSceneChannel(connection, target);
             }
@@ -392,12 +416,12 @@ export function createSceneTools(connection, snippetClient, opts = {}) {
                                     },
                                     selectable_state: {
                                         type: 'string',
-                                        enum: ['selectable', 'not_selectable', 'not_resolved'],
-                                        description: '`selectable`: a precomputed channel is ready to load. `not_selectable`: resolution ran and this region did not pass the confidence gate. `not_resolved`: precompute did not run or failed, so absence here is NOT evidence the region is unavailable.',
+                                        enum: [...SELECTABLE_STATES],
+                                        description: '`selectable`: a precomputed channel is ready to load. `not_selectable`: resolution ran and this region did not pass the confidence gate. `candidate`: the DEFAULT read advertised this region without deriving it — ps_select_by_reference scores it when you ask, and it may still turn out not to pass. `not_resolved`: an eagerly-requested precompute did not run or failed, so absence here is NOT evidence the region is unavailable.',
                                     },
                                     selectable_via: {
                                         type: 'string',
-                                        description: 'The method that resolved it (only when selectable).',
+                                        description: "The method that resolved it, when one did. Reads 'on_demand' for a `candidate` — nothing has resolved it yet and the method is chosen at derive time.",
                                     },
                                     selectable_confidence: { type: 'number' },
                                 },
@@ -421,7 +445,7 @@ export function createSceneTools(connection, snippetClient, opts = {}) {
         {
             tool: {
                 name: 'ps_select_by_reference',
-                description: 'Select a region by NAME instead of coordinates — the natural-mask alternative to a rectangle — with a CONFIDENCE GATE. target=sky/ground/foliage/subject/face/shadows/highlights/skin/above_horizon resolves through the right Photoshop-native method (threshold for sky, invert-sky−subjects for ground, luminance for shadows/highlights, skin-tone colour ∩ the subject box, the detected face/subject box) and is SCORED before it is offered: a clean region is left selected; an unconfident one is NOT selected and reported as honest absence (the city with no real sky gets no sky). Pro adds precise FACE-FEATURE targets backed by the face mesh — face_skin (the retouch mask: face minus eyes/brows/lips), face_eyes, face_brows, face_lips, face_teeth (mouth opening), face_nose, face_under_eye, face_cheeks — each a real geometry-following selection, loaded instantly from the scene:face_* channel ps_read_scene precomputes. `passed`/`confidence` are returned. The structural floor (coherence, horizon alignment) is never tuned; for an artistic/non-standard shot pass `composition_context` (e.g. profile:big_sky) to relax the compositional priors so a legitimately large sky is not rejected. For target=subject with several present, pass `label` and/or `instance`. Build/inspect with ps_read_scene first; verify with ps_get_selection_preview (the red-overlay is the human/agent oversight view). Prefer this over a rectangle for any real-world region.',
+                description: 'Select a region by NAME instead of coordinates — the natural-mask alternative to a rectangle — with a CONFIDENCE GATE. target=sky/ground/foliage/subject/face/shadows/highlights/skin/above_horizon resolves through the right Photoshop-native method (threshold for sky, invert-sky−subjects for ground, luminance for shadows/highlights, skin-tone colour ∩ the subject box, the detected face/subject box) and is SCORED before it is offered: a clean region is left selected; an unconfident one is NOT selected and reported as honest absence (the city with no real sky gets no sky). Pro adds precise FACE-FEATURE targets backed by the face mesh — face_skin (the retouch mask: face minus eyes/brows/lips), face_eyes, face_brows, face_lips, face_teeth (mouth opening), face_nose, face_under_eye, face_cheeks — each a real geometry-following selection, derived on first request and then saved as a scene:face_* channel so repeats load instantly. `passed`/`confidence` are returned. A region derived here is cached as a `scene:*` channel keyed by TARGET ONLY, so a later call for the same target loads it by name; pass `refresh:true` to force a fresh derive after an edit that changes what the region means, and note that narrowing a call with `label`/`instance`/`composition_context` always derives (it neither reads nor writes that shared channel). The structural floor (coherence, horizon alignment) is never tuned; for an artistic/non-standard shot pass `composition_context` (e.g. profile:big_sky) to relax the compositional priors so a legitimately large sky is not rejected. For target=subject with several present, pass `label` and/or `instance`. Build/inspect with ps_read_scene first; verify with ps_get_selection_preview (the red-overlay is the human/agent oversight view). Prefer this over a rectangle for any real-world region.',
                 inputSchema: selectByReferenceSchema,
                 outputSchema: {
                     type: 'object',

package/dist/tools/selection-tools.js

@@ -5,7 +5,7 @@ import { validateArgs } from '../utils/validate.js';
 import { toolErrorResult, runSnippetTool, unknownDiscriminator } from '../utils/tool-helpers.js';
 import { OnnxLandmarkDetectionClient } from '../detection/landmark-detection-client.js';
 import { resolveExpectedPlacement, PLACEMENT_SCHEMA } from '../perception/grounding-locate.js';
-import { SELECT_SUBJECT_TIMEOUT_MS, SELECT_SKY_TIMEOUT_MS } from '../utils/operation-timeouts.js';
+import { SELECT_SUBJECT_TIMEOUT_MS, SELECT_SKY_TIMEOUT_MS, SELECT_FOCUS_AREA_TIMEOUT_MS, } from '../utils/operation-timeouts.js';
 export const SELECTION_TYPE_ENUM = ['replace', 'add', 'subtract', 'intersect'];
 export const selectionTypeFragment = {
     type: 'string',
@@ -817,6 +817,42 @@ 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 = {
@@ -841,6 +877,41 @@ 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,
+    },
+};
+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) => ({
+            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`,
+    });
+}
 async function selectSubject(connection, snippetClient, rawArgs) {
     return runSnippetTool({
         connection,