editmamei 1.2.1 → 1.4.0

package/dist/telemetry/client.js

@@ -2,7 +2,7 @@ import { Logger } from '../utils/logger.js';
 import { EDITION } from '../edition.js';
 import { VERSION } from '../version.js';
 import { resolveInstallChannel } from '../install-channel.js';
-import { buildDiagnosticEvent, buildModuleStatus, buildSessionStart, buildSessionSummary, buildUsageEvent, dayBucket, isContentSafe, PS_VERSION_UNKNOWN, } from './events.js';
+import { buildDiagnosticEvent, buildModuleStatus, buildSessionStart, buildSessionSummary, buildUsageEvent, dayBucket, normalizeDayBucket, isContentSafe, PS_VERSION_UNKNOWN, } from './events.js';
 import { sanitizeMessage, sanitizeSnippet, sanitizeStderrTail } from './sanitize.js';
 import { httpTransport, resolveEndpoint } from './transport.js';
 import { appendOutboxSync, clearOutbox, clearSessionState, readOutbox, readSessionState, writeSessionStateSync, } from './outbox.js';
@@ -32,6 +32,7 @@ export class TelemetryClient {
     distinctTools = new Set();
     anyFailures = false;
     lastSessionPersistMs = 0;
+    startDayBucket = null;
     constructor(opts) {
         this.settings = opts.settings;
         this.transport = opts.transport ?? httpTransport();
@@ -70,6 +71,7 @@ export class TelemetryClient {
     recordCall(call) {
         if (!this.active || !this.settings.telemetry.usage)
             return;
+        this.ensureStartDayBucket();
         this.toolCallCount += 1;
         this.distinctTools.add(call.tool);
         if (!call.success)
@@ -81,6 +83,11 @@ export class TelemetryClient {
         const v = this.dims.getPsVersion();
         return v && v.length > 0 ? v : PS_VERSION_UNKNOWN;
     }
+    ensureStartDayBucket() {
+        if (this.startDayBucket === null)
+            this.startDayBucket = dayBucket(this.now());
+        return this.startDayBucket;
+    }
     persistSessionStateThrottled() {
         const nowMs = this.now().getTime();
         if (this.lastSessionPersistMs !== 0 &&
@@ -90,7 +97,7 @@ export class TelemetryClient {
         this.lastSessionPersistMs = nowMs;
         const state = {
             install_id: this.dims.install_id,
-            ts_bucket: dayBucket(this.now()),
+            ts_bucket: this.ensureStartDayBucket(),
             editmamei_version: this.dims.editmamei_version,
             edition: this.dims.edition,
             platform: this.dims.platform,
@@ -170,7 +177,7 @@ export class TelemetryClient {
                 tool_call_count: this.toolCallCount,
                 distinct_tools: this.distinctTools.size,
                 any_failures: this.anyFailures,
-            }, this.now()));
+            }, this.ensureStartDayBucket(), this.now()));
         }
         if (this.queue.length > 0) {
             appendOutboxSync(this.restampPsVersion(this.queue.splice(0)).filter(isContentSafe), this.outboxOpts);
@@ -225,7 +232,7 @@ function summaryFromState(s) {
         v: 2,
         type: 'session_summary',
         install_id: s.install_id,
-        ts_bucket: s.ts_bucket,
+        ts_bucket: normalizeDayBucket(s.ts_bucket, new Date()),
         editmamei_version: s.editmamei_version,
         edition: s.edition,
         platform: s.platform,

package/dist/telemetry/events.js

@@ -10,6 +10,9 @@ export function normalizeErrorClass(value) {
         .slice(0, 48);
     return cleaned.length > 0 ? cleaned : 'other';
 }
+export function normalizeDayBucket(value, now) {
+    return /^\d{4}-\d{2}-\d{2}$/.test(value) ? value : dayBucket(now);
+}
 function psVersionOf(dims) {
     const v = dims.getPsVersion();
     return v && v.length > 0 ? v : PS_VERSION_UNKNOWN;
@@ -30,12 +33,12 @@ export function buildUsageEvent(dims, call, now) {
         duration_ms: call.duration_ms,
     };
 }
-export function buildSessionSummary(dims, summary, now) {
+export function buildSessionSummary(dims, summary, tsBucket, now) {
     return {
         v: TELEMETRY_SCHEMA_VERSION,
         type: 'session_summary',
         install_id: dims.install_id,
-        ts_bucket: dayBucket(now),
+        ts_bucket: normalizeDayBucket(tsBucket, now),
         editmamei_version: dims.editmamei_version,
         edition: dims.edition,
         platform: dims.platform,

package/dist/tools/detection-tools.js

@@ -45,8 +45,8 @@ const detectSchema = {
         },
         annotate: {
             type: 'boolean',
-            default: true,
-            description: 'Return an annotated preview with the detected boxes drawn (faces cyan, objects magenta) so you can visually confirm the detections.',
+            default: false,
+            description: 'Also return an annotated preview JPEG with the detected boxes drawn (faces cyan, objects magenta). Default false: the labeled boxes returned by this call are already complete on their own — ask for the image only when you actually need to visually confirm a detection.',
         },
     },
 };
@@ -76,7 +76,7 @@ async function detect(connection, client, rawArgs, detectDeps) {
     try {
         const args = validateArgs(detectSchema, rawArgs);
         const target = args.target ?? 'both';
-        const annotate = args.annotate ?? true;
+        const annotate = args.annotate ?? false;
         const wantFaces = target === 'faces' || target === 'both';
         const wantObjects = target === 'objects' || target === 'both';
         const detectKey = JSON.stringify({
@@ -174,7 +174,7 @@ export function createDetectionTools(connection, _snippetClient, client = new On
         {
             tool: {
                 name: 'ps_detect',
-                description: 'The cheap, narrow read: labeled bounding boxes only — faces and/or COCO-80 objects (person, dog, car, chair, sofa, …) in DOCUMENT-pixel space, plus an annotated preview for visual confirmation. LOCAL on-device computer vision; the image is never sent anywhere. Use this for real coordinates before a spatially-targeted edit when boxes are all you need — far more reliable than estimating positions from a preview. For the full scene model (regions, horizon, tonal zones, composition, and a menu of selectable named regions), use ps_read_scene instead. `target` selects faces / objects / both. Read-only: renders a throwaway duplicate, never modifies the working document. Boxes are [x1, y1, x2, y2]. Validate surprising results against the annotated image before acting on them.',
+                description: 'The cheap, narrow read: labeled bounding boxes only — faces and/or COCO-80 objects (person, dog, car, chair, sofa, …) in DOCUMENT-pixel space. LOCAL on-device computer vision; the image is never sent anywhere. Use this for real coordinates before a spatially-targeted edit when boxes are all you need — far more reliable than estimating positions from a preview. For the full scene model (regions, horizon, tonal zones, composition, and a menu of selectable named regions), use ps_read_scene instead. `target` selects faces / objects / both. Read-only: renders a throwaway duplicate, never modifies the working document. Boxes are [x1, y1, x2, y2]. Pass `annotate:true` for an annotated preview JPEG (faces cyan, objects magenta) when you need to visually confirm a surprising result.',
                 inputSchema: detectSchema,
                 outputSchema: {
                     type: 'object',

package/dist/tools/document-tools.js

@@ -246,7 +246,6 @@ export function createDocumentTools(connection, snippetClient) {
                 },
                 annotations: {
                     title: 'List / Activate Documents',
-                    readOnlyHint: true,
                     idempotentHint: true,
                 },
             },

package/dist/tools/image-tools.js

@@ -29,7 +29,8 @@ const cropDocumentSchema = {
             ...PLACEMENT_SCHEMA,
             description: 'ANCHOR-RELATIONAL crop (preferred over guessing pixels): a REGION relation (inside/gap) → the crop is the ' +
                 'resolved region bounding box, verified by the gate. Crops ONLY if the gate PASSES. When set, ' +
-                'left/top/right/bottom are ignored. See ps_resolve_placement for the anchors + relation vocabulary.',
+                'left/top/right/bottom are ignored. See the placement-resolver tool, when this build has one, for the ' +
+                'anchors + relation vocabulary.',
         },
         left: {
             type: 'integer',

package/dist/tools/layer-transform-tools.js

@@ -82,7 +82,8 @@ const moveLayerSchema = {
             description: 'ANCHOR-RELATIONAL move (preferred over guessing a pixel): a POINT relation (centroid/midpoint/offset) → ' +
                 'the layer\'s CENTER is moved to the resolved, gate-verified point (e.g. "center this layer on the detected ' +
                 'subject" / "…in the gap between the two people"). Moves ONLY if the gate PASSES. When set, delta_*/' +
-                'absolute_*/center_on_* are ignored. See ps_resolve_placement for the anchors + relation vocabulary.',
+                'absolute_*/center_on_* are ignored. See the placement-resolver tool, when this build has one, for the ' +
+                'anchors + relation vocabulary.',
         },
     },
 };

package/dist/tools/path-tools.js

@@ -73,7 +73,7 @@ const pathInputSchema = {
         tool: {
             type: 'string',
             enum: SUPPORTED_BRUSH_TOOLS,
-            description: "stroke only: which brush-family tool paints the path. Default 'brush'. Same 16-tool set as ps_apply_brush_stroke.",
+            description: "stroke only: which brush-family tool paints the path (see this field's own enum for the full supported set). Default 'brush'.",
             default: 'brush',
         },
         color: {

package/dist/tools/preview-tools.js

@@ -162,7 +162,7 @@ const histogramSchema = {
         channel: {
             type: 'string',
             enum: ['composite', 'red', 'green', 'blue', 'luminosity', 'gray'],
-            description: 'Which channel to read. "composite" (default) is the visible flattened image; if the active layer is an adjustment/fill/shape layer the tool transparently switches to a pixel layer to read it. "red"/"green"/"blue" require an RGB doc; "gray" a grayscale doc. "luminosity" dispatches per doc mode — Lab uses the Lightness channel (exact), Grayscale uses Gray (exact), RGB synthesizes a Rec.709 weighted approximation from R+G+B (mean is exact; stdev/median are approximations). The result\'s `channel` field annotates which path landed when a fallback was used.',
+            description: 'Which channel to read. "composite" (default) is the visible flattened image; if the active layer is an adjustment/fill/shape layer the tool transparently switches to a pixel layer to read it. "red"/"green"/"blue" require an RGB doc; "gray" a grayscale doc. "luminosity" dispatches per doc mode — Lab uses the Lightness channel (exact), Grayscale uses Gray (exact), and RGB reads the per-pixel luminance Photoshop reports, weighted 0.30/0.59/0.11, so its shape and any clipping or percentile read taken from it are sound. Note that weighting is not Rec.709, so a luminosity mean will not match one computed as 0.2126/0.7152/0.0722. A channel value naming a marginal mixture means the document histogram was unavailable and the read fell back to combining the channel histograms: that mean is still sound, its shape is not. The result\'s `channel` field annotates which path landed when a fallback was used.',
             default: 'composite',
         },
     },

package/dist/tools/scene-tools.js

@@ -71,8 +71,8 @@ const sceneSchema = {
     properties: {
         annotate: {
             type: 'boolean',
-            default: true,
-            description: 'Return an annotated preview with subject boxes (magenta), faces (cyan), and the horizon line (yellow) drawn so you can visually confirm the scene model.',
+            default: false,
+            description: 'Also return an annotated preview JPEG with subject boxes (magenta), faces (cyan), and the horizon line (yellow) drawn. Default false: the structured scene model returned by this call is already complete on its own — ask for the image only when you actually need to see the annotation drawn.',
         },
         refresh: {
             type: 'boolean',
@@ -130,7 +130,9 @@ function summarizeScene(model) {
     const parts = [
         `${model.subjects.length} subject(s)${subjStr ? ` (${subjStr})` : ''}`,
         `${model.faces.length} face(s)`,
-        `horizon at y=${model.horizon.y} (${Math.round(model.horizon.placement * 100)}% down, conf ${model.horizon.confidence.toFixed(2)})`,
+        model.horizon.detected
+            ? `horizon at y=${model.horizon.y} (${Math.round(model.horizon.placement * 100)}% down, conf ${model.horizon.confidence.toFixed(2)})`
+            : `no horizon measured (${model.horizon.reason})`,
         `sky ~${Math.round((model.regions.find((r) => r.kind === 'sky')?.coverage ?? 0) * 100)}%`,
     ];
     if (main && cell)
@@ -140,7 +142,7 @@ function summarizeScene(model) {
 async function scene(connection, snippet, client, rawArgs, proRefine, hasPro = false, detectDeps) {
     try {
         const args = validateArgs(sceneSchema, rawArgs);
-        const annotate = args.annotate ?? true;
+        const annotate = args.annotate ?? false;
         const refresh = args.refresh ?? false;
         const saveRegions = args.save_regions ?? false;
         const built = await buildSceneModel(connection, snippet, client, {
@@ -177,7 +179,7 @@ async function scene(connection, snippet, client, rawArgs, proRefine, hasPro = f
             try {
                 const exportH = built.exportImage.height || 0;
                 const sy = model.doc.height > 0 ? exportH / model.doc.height : 1;
-                const horizonExportY = Math.round(model.horizon.y * sy);
+                const horizonExportY = model.horizon.detected ? Math.round(model.horizon.y * sy) : null;
                 const annotated = annotateScene(built.decoded, built.rawFaces, built.rawObjects.map((o) => o.bbox), horizonExportY);
                 content.push({
                     type: 'image',
@@ -391,7 +393,7 @@ export function createSceneTools(connection, snippetClient, opts = {}) {
         {
             tool: {
                 name: 'ps_read_scene',
-                description: 'The full scene model — run this before a spatially-targeted edit, not the cheaper ps_detect: detected subjects (with the main one flagged) and faces in document pixels, a coarse sky/ground region map, the horizon line (y + placement + confidence), tonal zones (shadow/midtone/highlight bands + coverage), composition geometry (which thirds cell the subject sits in, balance, headroom), plus an annotated preview and the menu of selectable named regions. Built using LOCAL on-device vision + classical CV; the image never leaves the machine. Select regions by name with ps_select_by_reference instead of guessing a rectangle. Read-only: renders a throwaway duplicate. Perception is cached per document state, so repeated reads are cheap.',
+                description: 'The full scene model — run this before a spatially-targeted edit, not the cheaper ps_detect: detected subjects (with the main one flagged) and faces in document pixels, a coarse sky/ground region map, the horizon line (y + placement + confidence), tonal zones (shadow/midtone/highlight bands + coverage), composition geometry (which thirds cell the subject sits in, balance, headroom), and the menu of selectable named regions. The structured model is complete on its own — pass `annotate:true` for an annotated preview JPEG when you actually need to see it drawn. Built using LOCAL on-device vision + classical CV; the image never leaves the machine. Select regions by name with ps_select_by_reference instead of guessing a rectangle. Read-only: renders a throwaway duplicate. Perception is cached per document state, so repeated reads are cheap.',
                 inputSchema: sceneSchema,
                 outputSchema: {
                     type: 'object',

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,9 +490,10 @@ 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 ps_resolve_placement for the vocabulary.',
+            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.',
         },
     },
     required: ['mode'],
@@ -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,