editmamei 0.24.1 → 1.0.0

package/dist/tools/document-tools.js

@@ -75,7 +75,7 @@ const savePsdSchema = {
         },
         keep_scene_channels: {
             type: 'boolean',
-            description: "Keep the managed scene:* alpha channels ps_read_scene precomputes. Default false — they are DERIVED masks (rebuilt by the next scene read) and each is a full-resolution channel, so baking them into the .psd bloats it badly (~51MB per channel on a 51MP document). Set true only if you want the saved file to carry the masks. The result reports scene_channels_purged either way, so it's never silent.",
+            description: "Keep the managed scene:* alpha channels ps_read_scene precomputes. Default false — they are DERIVED masks (rebuilt by the next scene read) and each is a full-resolution channel, so baking them into the .psd bloats it badly (~51MB per channel on a 51MP document). Set true only if you want the saved file to carry the masks. The result reports scene_channels_purged either way, so it's never silent. NOTE: the `scene:` channel-name prefix is RESERVED — the purge matches on the prefix alone, so a hand-made channel named e.g. `scene:mine` is deleted along with the derived ones. Name your own channels anything else.",
             default: false,
         },
     },
@@ -415,8 +415,15 @@ async function openDocumentPipeline(connection, snippetClient, rawArgs) {
     }
 }
 async function savePsdPipeline(connection, snippetClient, rawArgs) {
+    let args;
+    try {
+        args = validateArgs(savePsdSchema, rawArgs);
+    }
+    catch (error) {
+        return toolErrorResult('Error saving PSD', error);
+    }
     let purged = 0;
-    if (rawArgs.keep_scene_channels !== true) {
+    if (args.keep_scene_channels !== true) {
         try {
             purged = await purgeSceneChannels(connection);
         }

package/dist/tools/filter-tools.js

@@ -928,7 +928,7 @@ export function createFilterTools(connection, snippetClient, client = new OnnxLa
         {
             tool: {
                 name: 'ps_apply_filter',
-                description: 'Apply a Photoshop filter to a DUPLICATE of the active layer by default (auto-duplicate-first per Bundle O — the original is preserved, undo by deleting the copy). Pass `apply_to_active_layer: true` to bake into the original. Auto-rasterizes text/smart-object layers. Choose the filter with `type`; each type takes its own parameters (see the `type` field). Covers blur (gaussian_blur/motion_blur/lens_blur/radial_blur), sharpen (`sharpen`=Unsharp Mask, `smart_sharpen`), noise (`noise`=Add Noise, `reduce_noise`), high_pass, pixelate, distort, displace, and oil_paint.',
+                description: 'Apply a Photoshop filter to a DUPLICATE of the active layer by default (auto-duplicate-first — the original is preserved, undo by deleting the copy). Pass `apply_to_active_layer: true` to bake into the original. Auto-rasterizes text/smart-object layers. Choose the filter with `type`; each type takes its own parameters (see the `type` field). Covers blur (gaussian_blur/motion_blur/lens_blur/radial_blur), sharpen (`sharpen`=Unsharp Mask, `smart_sharpen`), noise (`noise`=Add Noise, `reduce_noise`), high_pass, pixelate, distort, displace, and oil_paint.',
                 inputSchema: FILTER_INPUT_SCHEMA,
                 outputSchema: FILTER_OUTPUT_SCHEMA,
                 annotations: {

package/dist/tools/layer-tools.js

@@ -79,20 +79,106 @@ const addFillLayerSchema = {
     properties: {
         fill_type: {
             type: 'string',
-            enum: ['solid_color'],
-            description: 'Fill-layer type. Currently solid_color (gradient / pattern fills planned).',
+            enum: ['solid_color', 'gradient'],
+            description: 'Fill-layer type. solid_color takes red/green/blue (required for that type); gradient takes the gradient_* params + stops (pattern fills still planned).',
             default: 'solid_color',
         },
-        red: { type: 'integer', description: 'Solid color red (0-255).', minimum: 0, maximum: 255 },
-        green: { type: 'integer', description: 'Solid color green (0-255).', minimum: 0, maximum: 255 },
-        blue: { type: 'integer', description: 'Solid color blue (0-255).', minimum: 0, maximum: 255 },
+        red: {
+            type: 'integer',
+            description: 'fill_type=solid_color: red (0-255). Required for solid_color.',
+            minimum: 0,
+            maximum: 255,
+        },
+        green: {
+            type: 'integer',
+            description: 'fill_type=solid_color: green (0-255). Required for solid_color.',
+            minimum: 0,
+            maximum: 255,
+        },
+        blue: {
+            type: 'integer',
+            description: 'fill_type=solid_color: blue (0-255). Required for solid_color.',
+            minimum: 0,
+            maximum: 255,
+        },
+        gradient_type: {
+            type: 'string',
+            enum: ['linear', 'radial', 'angle', 'reflected', 'diamond'],
+            description: 'fill_type=gradient: gradient geometry. linear for skies/fades, radial for vignettes/glows.',
+            default: 'linear',
+        },
+        angle: {
+            type: 'number',
+            minimum: -180,
+            maximum: 180,
+            description: 'fill_type=gradient: gradient angle in degrees (Photoshop convention: 90 runs the first stop from the bottom up; 0 runs it left to right).',
+            default: 90,
+        },
+        scale: {
+            type: 'number',
+            minimum: 10,
+            maximum: 150,
+            description: 'fill_type=gradient: gradient scale percent (compress/stretch the ramp).',
+            default: 100,
+        },
+        reverse: {
+            type: 'boolean',
+            description: 'fill_type=gradient: reverse the stop order.',
+            default: false,
+        },
+        dither: {
+            type: 'boolean',
+            description: 'fill_type=gradient: dither to reduce banding.',
+            default: true,
+        },
+        offset_x: {
+            type: 'number',
+            minimum: -100,
+            maximum: 100,
+            description: 'fill_type=gradient: horizontal center offset percent.',
+            default: 0,
+        },
+        offset_y: {
+            type: 'number',
+            minimum: -100,
+            maximum: 100,
+            description: 'fill_type=gradient: vertical center offset percent.',
+            default: 0,
+        },
+        stops: {
+            type: 'array',
+            description: 'fill_type=gradient: color stops, each {red,green,blue (0-255), location (0-100 along the ramp), midpoint (5-95, default 50)}. At least 2 when supplied; sorted by location. Default: black at 0 → white at 100.',
+            items: {
+                type: 'object',
+                properties: {
+                    red: { type: 'integer', minimum: 0, maximum: 255 },
+                    green: { type: 'integer', minimum: 0, maximum: 255 },
+                    blue: { type: 'integer', minimum: 0, maximum: 255 },
+                    location: { type: 'number', minimum: 0, maximum: 100 },
+                    midpoint: { type: 'number', minimum: 5, maximum: 95, default: 50 },
+                },
+                required: ['red', 'green', 'blue', 'location'],
+            },
+        },
+        opacity_stops: {
+            type: 'array',
+            description: 'fill_type=gradient: opacity stops, each {opacity (0-100), location (0-100), midpoint (5-95, default 50)}. Use e.g. 100→0 for a fade-to-transparent wash. Default: fully opaque.',
+            items: {
+                type: 'object',
+                properties: {
+                    opacity: { type: 'number', minimum: 0, maximum: 100 },
+                    location: { type: 'number', minimum: 0, maximum: 100 },
+                    midpoint: { type: 'number', minimum: 5, maximum: 95, default: 50 },
+                },
+                required: ['opacity', 'location'],
+            },
+        },
         into_active_group: {
             type: 'boolean',
             description: "Photoshop's Mk-contentLayer descriptor carries no placement target, so with a GROUP active it would natively nest the new fill layer INSIDE that group. Default false hoists the new layer back out so it lands above the active layer/group as a sibling. Pass true to keep it nested inside the active group instead.",
             default: false,
         },
     },
-    required: ['red', 'green', 'blue'],
 };
 const selectLayerSchema = {
     type: 'object',
@@ -198,7 +284,7 @@ export function createLayerTools(connection, snippetClient) {
         {
             tool: {
                 name: 'ps_add_fill_layer',
-                description: "Add a non-destructive SOLID COLOR fill layer (an editable, re-colorable content layer — distinct from ps_fill_layer, which bakes color into the active pixel layer). Hoisted out of the active layer's group by default even though Photoshop's own Mk-contentLayer placement rule would otherwise nest it INSIDE that group (pass into_active_group:true to keep that native nesting). The new fill layer becomes active. Use for color washes, base backgrounds, and clipped color overlays. (Gradient and pattern fill types are planned.)",
+                description: "Add a non-destructive SOLID COLOR or GRADIENT fill layer (an editable content layer — distinct from ps_fill_layer, which bakes color into the active pixel layer). fill_type=gradient is the go-to for sky fades, color washes, and vignettes (radial + reverse + multiply blend); combine with opacity_stops 100→0 for fade-to-transparent, or ps_bake_layer to rasterize. For fading a layer out via its MASK use ps_layer_mask op=gradient instead. Hoisted out of the active layer's group by default (pass into_active_group:true to keep Photoshop's native nesting). The new fill layer becomes active.",
                 inputSchema: addFillLayerSchema,
                 outputSchema: {
                     type: 'object',
@@ -206,6 +292,11 @@ export function createLayerTools(connection, snippetClient) {
                         created: { type: 'boolean' },
                         fill_type: { type: 'string' },
                         color: { type: 'object' },
+                        gradient_type: { type: 'string' },
+                        angle: { type: 'number' },
+                        scale: { type: 'number' },
+                        reverse: { type: 'boolean' },
+                        stop_count: { type: 'number' },
                         layer_name: { type: 'string' },
                         hoisted: {
                             type: 'boolean',
@@ -325,6 +416,40 @@ async function fillLayer(connection, snippetClient, rawArgs) {
     });
 }
 async function addFillLayer(connection, snippetClient, rawArgs) {
+    if (rawArgs.fill_type === 'gradient') {
+        return runSnippetTool({
+            connection,
+            snippetClient,
+            rawArgs,
+            schema: addFillLayerSchema,
+            snippet: 'addGradientFillLayer',
+            errorPrefix: 'Error adding gradient fill layer',
+            params: (args) => {
+                const params = {
+                    gradient_type: args.gradient_type ?? 'linear',
+                    angle: args.angle ?? 90,
+                    scale: args.scale ?? 100,
+                    reverse: args.reverse ?? false,
+                    dither: args.dither ?? true,
+                    offset_x: args.offset_x ?? 0,
+                    offset_y: args.offset_y ?? 0,
+                    into_active_group: args.into_active_group ?? false,
+                };
+                if (args.stops !== undefined)
+                    params.stops = args.stops;
+                if (args.opacity_stops !== undefined)
+                    params.opacity_stops = args.opacity_stops;
+                return params;
+            },
+            successText: (result, args) => {
+                const stopCount = result.stop_count;
+                return `Gradient fill layer added: ${args.gradient_type ?? 'linear'}, angle ${args.angle ?? 90}${stopCount !== undefined ? `, ${stopCount} stops` : ''}`;
+            },
+        });
+    }
+    if (rawArgs.red === undefined || rawArgs.green === undefined || rawArgs.blue === undefined) {
+        return toolErrorResult('Error adding fill layer', new Error('fill_type=solid_color requires red, green, and blue (0-255).'));
+    }
     return runSnippetTool({
         connection,
         snippetClient,

package/dist/tools/path-tools.js

@@ -113,7 +113,7 @@ export function createPathTools(connection, snippetClient, client = new OnnxLand
         {
             tool: {
                 name: 'ps_path',
-                description: 'Work with editable vector PATHS — the connective tissue between selections, brush strokes, and clipping. One op-discriminated tool: `create_from_selection` (selection → work path), `create_from_placement` (NAME a curve → editable saved path, the grounded pen), `save` (name the work path), `list`, `delete`, `load_as_selection` (path → selection), `stroke` (paint a brush-family tool along a path), `fill` (fill a path region), `set_clipping` (mark a saved path as the clipping path). **Reach for this when**: tracing a named curve (an edge, a landmark contour) into an editable path, turning a precise selection into a reusable/strokeable outline, converting a saved path back to a selection, or outlining/filling a shape exactly. create_from_selection and load_as_selection are an exact round-trip. stroke/fill bake pixels and auto-duplicate the target layer (Bundle O). Every op returns path_info (counts + per-path subpath/anchor totals) so you can verify the path landed; load_as_selection also returns selection_info.',
+                description: 'Work with editable vector PATHS — the connective tissue between selections, brush strokes, and clipping. One op-discriminated tool: `create_from_selection` (selection → work path), `create_from_placement` (NAME a curve → editable saved path, the grounded pen), `save` (name the work path), `list`, `delete`, `load_as_selection` (path → selection), `stroke` (paint a brush-family tool along a path), `fill` (fill a path region), `set_clipping` (mark a saved path as the clipping path). **Reach for this when**: tracing a named curve (an edge, a landmark contour) into an editable path, turning a precise selection into a reusable/strokeable outline, converting a saved path back to a selection, or outlining/filling a shape exactly. create_from_selection and load_as_selection are an exact round-trip. stroke/fill bake pixels and auto-duplicate the target layer. Every op returns path_info (counts + per-path subpath/anchor totals) so you can verify the path landed; load_as_selection also returns selection_info.',
                 inputSchema: pathInputSchema,
                 outputSchema: {
                     type: 'object',

package/dist/tools/preview-tools.js

@@ -200,7 +200,7 @@ export function createPreviewTools(connection, snippetClient) {
         {
             tool: {
                 name: 'ps_get_preview',
-                description: 'Render the active Photoshop document as a flattened, downscaled image and return it inline so the calling AI can see the current visual state. Use this to verify edits visually, judge whether adjustments went too far or not far enough, and decide what to do next. Read-only with respect to the working document (renders a duplicate that is closed immediately). The optional `annotations` array draws overlays in document-space coordinates: `rectangle` / `guide` / `point` / `selection` for spatial verification (Bundle Q, 2026-06-02), and `grid` / `composition` for coordinate readout and compositional evaluation (added 2026-06-09 — grid styles `every` / `thirds` / `quarters` / `phi`, composition styles `diagonals` / `triangles` / `fibonacci_grid` / `golden_spiral`). Use spatial annotations to verify ("did the placed image land inside the frame interior?") — pass both target and actual bounds in different colors. Use grid / composition annotations to EVALUATE composition (balance, thirds, leading lines, focal-point placement) — not to read a coordinate for a tool call. To place or select precisely, do NOT read a pixel off a grid (unreliable) — NAME the intent to the on-device perception tools instead: `ps_detect` (COCO objects → real document-pixel boxes), `ps_select_by_reference` (a named target → a real selection, not a guessed rectangle), plus any spatial-grounding locator / selection tools present in `tools/list`. Without annotations, behaves identically to a plain preview.',
+                description: 'Render the active Photoshop document as a flattened, downscaled image and return it inline so the calling AI can see the current visual state. Use this to verify edits visually, judge whether adjustments went too far or not far enough, and decide what to do next. Read-only with respect to the working document (renders a duplicate that is closed immediately). The optional `annotations` array draws overlays in document-space coordinates: `rectangle` / `guide` / `point` / `selection` for spatial verification, and `grid` / `composition` for coordinate readout and compositional evaluation (added 2026-06-09 — grid styles `every` / `thirds` / `quarters` / `phi`, composition styles `diagonals` / `triangles` / `fibonacci_grid` / `golden_spiral`). Use spatial annotations to verify ("did the placed image land inside the frame interior?") — pass both target and actual bounds in different colors. Use grid / composition annotations to EVALUATE composition (balance, thirds, leading lines, focal-point placement) — not to read a coordinate for a tool call. To place or select precisely, do NOT read a pixel off a grid (unreliable) — NAME the intent to the on-device perception tools instead: `ps_detect` (COCO objects → real document-pixel boxes), `ps_select_by_reference` (a named target → a real selection, not a guessed rectangle), plus any spatial-grounding locator / selection tools present in `tools/list`. Without annotations, behaves identically to a plain preview.',
                 inputSchema: previewSchema,
                 outputSchema: {
                     type: 'object',
@@ -224,7 +224,7 @@ export function createPreviewTools(connection, snippetClient) {
         {
             tool: {
                 name: 'ps_get_layer_bounds_diff',
-                description: 'Numeric verification: compute the per-edge pixel deltas between a layer\'s actual bounds and a target rectangle. Returns left/top/right/bottom deltas (actual − target), scale ratio (actual_size / target_size), centroid offset, and a one-word verdict ("aligned", "shifted right", "layer too small", etc.). Use this AFTER place_image / scale_layer / move_layer to confirm the operation produced the intended result — far more reliable than eyeballing a preview for fine alignment. Read-only. Layers nested in groups are found by name recursively. Bundle Q (2026-06-02).',
+                description: 'Numeric verification: compute the per-edge pixel deltas between a layer\'s actual bounds and a target rectangle. Returns left/top/right/bottom deltas (actual − target), scale ratio (actual_size / target_size), centroid offset, and a one-word verdict ("aligned", "shifted right", "layer too small", etc.). Use this AFTER place_image / scale_layer / move_layer to confirm the operation produced the intended result — far more reliable than eyeballing a preview for fine alignment. Read-only. Layers nested in groups are found by name recursively.',
                 inputSchema: boundsDiffSchema,
                 outputSchema: {
                     type: 'object',
@@ -283,7 +283,7 @@ export function createPreviewTools(connection, snippetClient) {
         {
             tool: {
                 name: 'ps_compare_regions',
-                description: 'Quantitative region comparison — the NUMERIC verification answer when "does it look right?" via get_preview is too subjective. Captures the histogram of two rectangular regions on the same document and reports per-channel mean / stdev / median for each region plus the deltas. **Reach for this when**: (a) "did the placed image match the room\'s lighting?" — sample a region of the placed image vs a region of the surrounding wall; (b) "did this adjustment do anything visible in the shadows?" — sample the same dark region before and after; (c) "is region A noticeably warmer/cooler than region B?" — read the channel means directly. Single-pixel sampling via a 1×1 rect is supported. Read-only. Bundle Q (2026-06-02).',
+                description: 'Quantitative region comparison — the NUMERIC verification answer when "does it look right?" via get_preview is too subjective. Captures the histogram of two rectangular regions on the same document and reports per-channel mean / stdev / median for each region plus the deltas. **Reach for this when**: (a) "did the placed image match the room\'s lighting?" — sample a region of the placed image vs a region of the surrounding wall; (b) "did this adjustment do anything visible in the shadows?" — sample the same dark region before and after; (c) "is region A noticeably warmer/cooler than region B?" — read the channel means directly. Single-pixel sampling via a 1×1 rect is supported. Read-only.',
                 inputSchema: compareRegionsSchema,
                 outputSchema: {
                     type: 'object',
@@ -359,7 +359,7 @@ function buildAnnotationsScript(annotations) {
         }
     }
     return `
-        // ANNOTATIONS BLOCK (Bundle Q)
+        // ANNOTATIONS BLOCK
         (function () {
           var docW = dup.width.as('px');
           var docH = dup.height.as('px');
@@ -643,7 +643,7 @@ function buildAnnotationsScript(annotations) {
           // it's just not a mathematically-perfect golden spiral when
           // the canvas isn't golden. maxLevels capped at 8 to keep the
           // total fill count bounded for the 90s annotated-preview
-          // timeout (Bundle Q hotfix 3).
+          // timeout.
           function drawFibonacciOverlay(startCorner, c, sw, drawSpiral) {
             try {
               // Track the active rectangle as we shrink it.
@@ -779,7 +779,7 @@ async function getPreview(connection, rawArgs) {
         ${getContextInfo}
 
         if (app.documents.length === 0) {
-          throw new Error('No active document');
+          throw new Error('No document is open in Photoshop');
         }
         // Defensive cleanup: a prior killed wrapper.vbs (annotated previews
         // timing out at 30s) leaves a stale "<orig> __mcp_preview__" doc
@@ -895,7 +895,7 @@ async function getLayerBoundsDiff(connection, rawArgs) {
         const script = `
       ${getContextInfo}
 
-      if (app.documents.length === 0) throw new Error('No active document');
+      if (app.documents.length === 0) throw new Error('No document is open in Photoshop');
       var doc = app.activeDocument;
 
       ${normNameHelper}
@@ -1037,7 +1037,7 @@ async function compareRegions(connection, rawArgs) {
         const script = `
       ${getContextInfo}
 
-      if (app.documents.length === 0) throw new Error('No active document');
+      if (app.documents.length === 0) throw new Error('No document is open in Photoshop');
       var doc = app.activeDocument;
 
       function statsForRect(left, top, right, bottom) {

package/dist/tools/retouch-tools.js

@@ -370,7 +370,7 @@ export function createRetouchTools(connection, snippetClient, detClient = new On
         {
             tool: {
                 name: 'ps_retouch',
-                description: 'Selection-driven content-aware retouch — choose the technique with `method`. Requires an active selection (throws if none, so Content-Aware Fill never silently fills the whole layer). Auto-duplicates the active layer by default so the original is preserved (auto-duplicate-first per Bundle O); pass `apply_to_active_layer: true` to bake into the original. `content_aware_fill` synthesizes a fill from surroundings (remove wires/objects/blemishes); `patch` samples replacement pixels from a chosen offset — or NAME the source region with `source_placement` (grounded + gated); `content_aware_move` relocates the selection and fills the source — offset, or NAME where with `destination_placement`.',
+                description: 'Selection-driven content-aware retouch — choose the technique with `method`. Requires an active selection (throws if none, so Content-Aware Fill never silently fills the whole layer). Auto-duplicates the active layer by default so the original is preserved (auto-duplicate-first); pass `apply_to_active_layer: true` to bake into the original. `content_aware_fill` synthesizes a fill from surroundings (remove wires/objects/blemishes); `patch` samples replacement pixels from a chosen offset — or NAME the source region with `source_placement` (grounded + gated); `content_aware_move` relocates the selection and fills the source — offset, or NAME where with `destination_placement`.',
                 inputSchema: RETOUCH_INPUT_SCHEMA,
                 outputSchema: RETOUCH_OUTPUT_SCHEMA,
                 annotations: {

package/dist/tools/scene-tools.js

@@ -83,7 +83,7 @@ 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.',
+            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.',
         },
         composition_context: {
             type: 'object',
@@ -375,7 +375,34 @@ export function createSceneTools(connection, snippetClient, opts = {}) {
                         doc: { type: 'object' },
                         subjects: { type: 'array', items: { type: 'object' } },
                         faces: { type: 'array', items: { type: 'object' } },
-                        regions: { type: 'array', items: { type: 'object' } },
+                        regions: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    kind: { type: 'string' },
+                                    coverage: { type: 'number' },
+                                    coverage_is_estimate: {
+                                        type: 'boolean',
+                                        description: 'Always true today: `coverage` is the coarse histogram split, never a measured mask. It and the real selection routinely disagree (a night shot read sky at 0.08 while the gated selection found a real sky at 0.83) — trust `selectable_confidence` and the precomputed channel over this number. Carried as a field rather than left implicit so a future measured-coverage path can report false.',
+                                    },
+                                    selectable: {
+                                        type: ['boolean', 'null'],
+                                        description: 'Tristate as null when the region was never resolved — never read this as a plain boolean; branch on `selectable_state`.',
+                                    },
+                                    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.',
+                                    },
+                                    selectable_via: {
+                                        type: 'string',
+                                        description: 'The method that resolved it (only when selectable).',
+                                    },
+                                    selectable_confidence: { type: 'number' },
+                                },
+                            },
+                        },
                         region_menu: { type: 'array', items: { type: 'object' } },
                         horizon: { type: 'object' },
                         tonal_zones: { type: 'object' },

package/dist/tools/selection-tools.js

@@ -522,7 +522,35 @@ const SELECTION_CHANNEL_INPUT_SCHEMA = {
     },
     required: ['op', 'channel_name'],
 };
-const LAYER_MASK_OPS = ['create', 'delete', 'apply'];
+const LAYER_MASK_OPS = ['create', 'delete', 'apply', 'gradient'];
+const MASK_GRADIENT_PROPS = {
+    fade_to: {
+        type: 'string',
+        enum: ['bottom', 'top', 'left', 'right'],
+        description: 'op=gradient: the side that ends fully HIDDEN (mask black). The opposite side stays fully visible. E.g. a water reflection fades with fade_to=bottom.',
+        default: 'bottom',
+    },
+    start: {
+        type: 'number',
+        minimum: 0,
+        maximum: 1,
+        description: 'op=gradient: 0-1 fraction along the fade direction where the fade begins — the layer stays fully visible up to here.',
+        default: 0,
+    },
+    end: {
+        type: 'number',
+        minimum: 0,
+        maximum: 1,
+        description: 'op=gradient: 0-1 fraction where the fade completes — fully hidden from here on. Must be greater than start.',
+        default: 1,
+    },
+    extent: {
+        type: 'string',
+        enum: ['layer', 'canvas'],
+        description: "op=gradient: measure start/end over the active layer's pixel bounds (default) or the whole canvas. A layer with no pixel bounds falls back to canvas.",
+        default: 'layer',
+    },
+};
 const LAYER_MASK_INPUT_SCHEMA = {
     type: 'object',
     properties: {
@@ -531,11 +559,17 @@ const LAYER_MASK_INPUT_SCHEMA = {
             enum: [...LAYER_MASK_OPS],
             description: 'create: add a layer mask on the active layer (if a selection is active it reveals the selection — the "mask to the frame opening" answer; adjustment layers load the selection into their built-in mask). ' +
                 'delete: remove the mask (layer pixels preserved). ' +
-                'apply: DESTRUCTIVE — bake the mask into pixels (pixels outside the mask are lost).',
+                'apply: DESTRUCTIVE — bake the mask into pixels (pixels outside the mask are lost). ' +
+                'gradient: draw a linear white→black fade INTO the mask (auto-creates a reveal-all mask if none) — the universal fade-out primitive (reflections, sky blends, edge feathering). REPLACES existing mask content.',
         },
+        ...MASK_GRADIENT_PROPS,
     },
     required: ['op'],
 };
+const MASK_GRADIENT_ARGS_SCHEMA = {
+    type: 'object',
+    properties: { ...MASK_GRADIENT_PROPS },
+};
 export function createSelectionTools(connection, snippetClient, client = new OnnxLandmarkDetectionClient()) {
     return [
         {
@@ -640,7 +674,7 @@ export function createSelectionTools(connection, snippetClient, client = new Onn
         {
             tool: {
                 name: 'ps_layer_mask',
-                description: 'Manage the active layer\'s mask — choose with `op`. `create`: add a layer mask; if a selection is active it reveals the selection and hides the rest (the one-call "mask the placed image to the frame opening" — make the selection first, then create); with no selection, a reveal-all mask; adjustment layers load the current selection into their built-in mask. `delete`: remove the mask (layer pixels preserved). `apply`: DESTRUCTIVE — permanently bake the mask into the pixels (outside-mask pixels lost). Prefer keeping masks non-destructive unless flattening for export. **Don\'t write `Mk Chnl At=Msk` AM scripts in execute_script — this tool already does that.**',
+                description: 'Manage the active layer\'s mask — choose with `op`. `create`: add a layer mask; if a selection is active it reveals the selection and hides the rest (the one-call "mask the placed image to the frame opening" — make the selection first, then create); with no selection, a reveal-all mask; adjustment layers load the current selection into their built-in mask. `delete`: remove the mask (layer pixels preserved). `apply`: DESTRUCTIVE — permanently bake the mask into the pixels (outside-mask pixels lost). `gradient`: draw a linear fade into the mask (fade_to names the side that ends hidden; start/end place the fade; auto-creates the mask; replaces existing mask content and clears any active selection first) — the standard fade for reflections, sky blends, and soft edge falloff. Verify with ps_get_preview. Prefer keeping masks non-destructive unless flattening for export. **Don\'t write `Mk Chnl At=Msk` or `Grdn` AM scripts in execute_script — this tool already does both.**',
                 inputSchema: LAYER_MASK_INPUT_SCHEMA,
                 outputSchema: {
                     type: 'object',
@@ -651,6 +685,26 @@ export function createSelectionTools(connection, snippetClient, client = new Onn
                         hadSelection: { type: 'boolean' },
                         maskDeleted: { type: 'boolean' },
                         maskApplied: { type: 'boolean' },
+                        mask_gradient: { type: 'boolean' },
+                        created_mask: {
+                            type: 'boolean',
+                            description: 'op=gradient: true when the reveal-all mask had to be created first.',
+                        },
+                        fade_to: { type: 'string' },
+                        from: {
+                            type: 'object',
+                            description: 'op=gradient: fully-visible end of the drawn fade, doc pixels.',
+                        },
+                        to: {
+                            type: 'object',
+                            description: 'op=gradient: fully-hidden end of the drawn fade, doc pixels.',
+                        },
+                        extent: {
+                            type: 'string',
+                            description: "op=gradient: 'layer' or 'canvas' — reports the extent actually used.",
+                        },
+                        bounds_used: { type: 'object' },
+                        layer_name: { type: 'string' },
                         context: { type: 'object' },
                     },
                 },
@@ -891,6 +945,7 @@ async function selectionChannel(connection, snippetClient, rawArgs) {
     }
 }
 async function layerMask(connection, snippetClient, rawArgs) {
+    const { op: _omit, ...rest } = rawArgs;
     switch (rawArgs.op) {
         case 'create':
             return createLayerMask(connection, snippetClient);
@@ -898,6 +953,8 @@ async function layerMask(connection, snippetClient, rawArgs) {
             return deleteLayerMask(connection, snippetClient);
         case 'apply':
             return applyLayerMask(connection, snippetClient);
+        case 'gradient':
+            return maskGradient(connection, snippetClient, rest);
         default:
             return unknownDiscriminator('layer_mask op', rawArgs.op, LAYER_MASK_OPS);
     }
@@ -1412,6 +1469,27 @@ async function applyLayerMask(connection, snippetClient) {
         successText: () => 'Layer mask applied (merged to layer)',
     });
 }
+async function maskGradient(connection, snippetClient, rawArgs) {
+    return runSnippetTool({
+        connection,
+        snippetClient,
+        rawArgs,
+        schema: MASK_GRADIENT_ARGS_SCHEMA,
+        snippet: 'maskGradient',
+        errorPrefix: 'Error drawing mask gradient',
+        params: (args) => ({
+            fade_to: args.fade_to ?? 'bottom',
+            start: args.start ?? 0,
+            end: args.end ?? 1,
+            extent: args.extent ?? 'layer',
+        }),
+        successText: (result, args) => {
+            const r = result;
+            const created = r.created_mask ? ' (mask created)' : '';
+            return `Mask gradient drawn: fade to ${args.fade_to ?? 'bottom'}${created}\nResult: ${JSON.stringify(result)}`;
+        },
+    });
+}
 async function saveSelectionToChannel(connection, snippetClient, rawArgs) {
     return runSnippetTool({
         connection,

package/dist/update/check.js

@@ -1,7 +1,7 @@
 import { VERSION } from '../version.js';
 import { resolveInstallChannel } from '../install-channel.js';
 const DEFAULT_DIST_TAGS_URL = 'https://registry.npmjs.org/-/package/editmamei/dist-tags';
-const RELEASES_URL = 'https://github.com/editmamei/editmamei-wiki/releases/latest';
+const RELEASES_URL = 'https://editmamei.com/download';
 export function resolveUpdateCheckUrl(env = process.env) {
     const override = env.EDITMAMEI_UPDATE_CHECK_URL;
     return override && override.length > 0 ? override : DEFAULT_DIST_TAGS_URL;