Verify that the Photoshop scripting engine can run a script.

Use when: once at session start, and after extendscript_timeout until this call succeeds. Do NOT use when: on every tool call — after a successful ping, use photoshop_get_state. Do not call get_state or get_layers while this ping is still failing.

Returns: "Successfully connected to Photoshop" only after a short script runs inside Photoshop. While a previous script is still running, returns extendscript_timeout — retry photoshop_ping. If that timeout happens while the OS drive has under 10 GB free, returns scratch_disk_full instead: free space on the scratch disk and restart Photoshop. If Photoshop is not installed or not running, returns a failure string and does not launch the app. May append a FEEDBACK_NUDGE block 15 minutes after the first successful ping, then at most once per 7 days (disabled with PSMCP_FEEDBACK=0). May append an UPDATE_AVAILABLE block when a newer photoshop-mcp release is on npm, at most once per 7 days (disabled with PSMCP_UPDATE_CHECK=0). A single ping carries at most one of these blocks. Preconditions: none. Side effects: may trigger Photoshop detection. Does not launch Photoshop.

Record the user's answer to a Photoshop MCP product-feedback nudge.

Use when: photoshop_ping returned a FEEDBACK_NUDGE block and you already asked the user via the host question UI (Cursor AskQuestion / Claude AskUserQuestion) or chat. Do NOT use when: ping had no FEEDBACK_NUDGE — never invent this question. Do not start implementing the suggestion.

Returns: { ok, recorded, next }. After this call, immediately continue the user's original Photoshop request. Preconditions: none. Side effects: persists a local cooldown flag and may send an anonymous analytics event.

Return the detected Photoshop version string.

Use when: user asks about compatibility or before version-gated features. Do NOT use when: you need feature flags — prefer photoshop_get_capabilities.

Returns: version string. Preconditions: none. Side effects: none.

Create a new empty Photoshop document with specified dimensions and color mode.

Use when: starting a design from scratch or no document is open. Do NOT use when: opening an existing file — use photoshop_open_image.

Returns: created document id and name. Preconditions: none. Side effects: creates a new document and makes it active.

Read the active document id, name, size, resolution, and color mode. Does not change pixels or which tab is active.

Use when: you need dimensions or color mode of the front document only. Do NOT use when: several documents are open and you need every tab — use photoshop_list_documents. Do NOT use when: you also need the active layer and selection — use photoshop_get_state.

Returns: document context JSON. Preconditions: an open document. Side effects: none.

List every open Photoshop document with id, dimensions, saved flag, artboard_count, and which tab is active.

Use when: multiple documents are open and you need document_id before switching tabs, previewing, or closing a specific file. Do NOT use when: you only need the active document — use photoshop_get_document_info or photoshop_get_state.

Returns: JSON { ok, summary, details: { count, documents[] (id, name, width, height, saved, artboard_count, is_active), active_document_id, context } }. Preconditions: none (safe when zero documents open). Side effects: briefly activates each tab to read artboard_count, then restores the original active document.

Switch the active document tab by document_id (preferred), zero-based index, or name.

Use when: working across multiple open files and mutations must target a specific document. Do NOT use when: only one document is open — it is already active. Do NOT use document_name when duplicate names exist — use document_id from photoshop_list_documents.

Returns: JSON { ok, summary, details: { activated: { id, name }, context } }. Preconditions: target document must be open. Provide exactly one of document_id, index, or document_name. Side effects: changes active tab.

Save the active document to disk in PSD, JPEG, or PNG format.

Use when: user requests export/save with a specific path and format. Do NOT use when: web-optimized resize+sharpen pipeline is needed — use photoshop_recipe_prepare_for_web.

Returns: confirmation with saved path and format. Preconditions: active document; path required. Side effects: writes file to disk.

Close a Photoshop document tab. Defaults to the active document; pass document_id to close a specific open file.

Use when: the user is done with a file, or when cleaning up extra open tabs after photoshop_list_documents. Do NOT use when: you only need to switch tabs — use photoshop_set_active_document.

Returns: confirmation that the document closed. Preconditions: target document is open. Side effects: closes that tab; save=true writes unsaved changes first.

Create a new empty layer above the active layer.

Use when: user needs a blank layer for painting, fills, or stacking content. Do NOT use when: adding text — use photoshop_create_text_layer.

Returns: created layer name and context. Preconditions: active document. Side effects: adds layer to history.

Delete the active layer, including its pixels, mask, and effects.

Use when: the user wants that layer removed from the stack. Do NOT use when: it should only be hidden — use photoshop_set_layer_visibility. Do NOT use when: only the mask should go — use photoshop_delete_layer_mask. Do NOT use when: the whole stack should collapse — use photoshop_flatten_image.

Returns: confirmation that the layer was deleted. Preconditions: active document and a deletable active layer. Side effects: destroys the layer. Reversible with photoshop_undo while history holds it.

Create a text layer with content, position, font, and optional typography (tracking, leading, paragraph box, alignment, color).

Users often say: add title, letter spacing, line height, text box, 字间距, 行高, 排版.

Use when: adding labels, titles, or typography to the design. Do NOT use when: editing existing text — use photoshop_update_text_content / photoshop_set_text_style. Do NOT use execute_script for tracking/leading/box — pass those fields here.

Returns: JSON { ok, summary, details: { layerName, text, style, context } }. Use photoshop_list_fonts to discover font names; photoshop_set_text_font / photoshop_set_text_style to change later. Preconditions: active document. Side effects: adds text layer.

Fill the active layer with a solid RGB color. If a selection exists, only that region is filled and the selection stays; otherwise the whole layer is filled and the selection is cleared.

Use when: a flat color fill on the active layer or on the current selection. Do NOT use when: a new empty layer is needed first — use photoshop_create_layer, then this. Do NOT use when: the fill should be a two-color gradient — use photoshop_fill_gradient. Do NOT use when: the selection should be filled with surrounding content — use photoshop_content_aware_fill. Do NOT use when: the active layer is text — rasterize with photoshop_rasterize_layer first, or recolor type with photoshop_set_text_color. A smart object is rasterized in place and then filled. No extra layer is created.

Returns: the RGB color applied. Preconditions: active document and an unlocked non-text layer. Side effects: overwrites those pixels. The same color on the same pixels is idempotent. Reversible with photoshop_undo.

Paint a two-color linear gradient on the active layer pixels.

Use when: the user asks for a color gradient, blend, or "mavi yeşil" style ramp on a layer. Do NOT use when: a flat color is enough — use photoshop_fill_layer. Do NOT use when: the gradient should fade the layer into the background — use photoshop_recipe_gradient_fade. Do NOT use when: you would write ExtendScript. Document.gradients does not exist.

Returns: the two colors and direction applied. Preconditions: active document and an unlocked non-text layer. Side effects: overwrites those pixels, one history step. The same colors on the same pixels are idempotent. Reversible with photoshop_undo.

List all layers in the active document with kind, visibility, and opacity.

Use when: choosing a layer to edit, debugging structure, or after organize_layers. Do NOT use when: only session summary is needed — use photoshop_get_state (lighter).

Returns: layerCount, layers array (LayerSets include is_artboard), context. Preconditions: active document. Side effects: none.

Select the active layer by exact name, including layers inside groups.

Use when: a transform or property tool must target a named layer (photoshop_scale_layer, etc.). Do NOT use when: the layer is already active — check photoshop_get_state first.

Returns: selected, layerName, kind, bounds (best-effort), context. First depth-first name match wins when duplicate names exist in different groups. Preconditions: active document. Side effects: changes active layer.

Resample the active document to a new pixel width and height (bicubic). Every layer scales and the canvas size changes.

Use when: the user gives exact output pixel dimensions for the whole document. Do NOT use when: only one layer should scale — use photoshop_scale_layer or photoshop_fit_layer_to_document. Do NOT use when: AI upscale is requested and photoshop_get_capabilities reports generative_upscale — use photoshop_generative_upscale. Do NOT use when: cropping to a region — use photoshop_crop_document.

Returns: the resulting width and height in pixels. Preconditions: active document. Side effects: resamples all layers, one history step. Reversible with photoshop_undo.

Crop the active document to a pixel rectangle (left, top, right, bottom). Pixels outside that rectangle are deleted and the canvas shrinks.

Use when: the user gives explicit crop bounds in pixels. Do NOT use when: only one layer should scale inside the existing canvas — use photoshop_fit_layer_to_document or photoshop_scale_layer. Do NOT use when: the whole image should be resampled to a new width and height — use photoshop_resize_image.

Returns: the new document width and height. Preconditions: active document; right > left and bottom > top. Side effects: destructive crop of every layer, one history step. Reversible with photoshop_undo.

Place an external image file as a new layer in the active document.

x/y are absolute canvas coordinates for the placed layer's top-left bound in pixels (0,0 = document top-left). They are NOT an offset from Photoshop's default centered Place.

Use when: compositing assets into an open document at a known position. Do NOT use when: opening a file as a new document — use photoshop_open_image.

Returns: placed layer name, bounds, and position.semantics = absolute_top_left. Preconditions: active document; file must exist. Side effects: adds a new layer.

Open an image file as a new Photoshop document.

Use when: user provides a file path to edit or no document is open yet. Do NOT use when: adding to an existing composite — use photoshop_place_image.

Returns: document id, name, width, height. Preconditions: file must exist on disk. Side effects: opens document as active.

Convert the active layer (or a named layer) to an embedded Smart Object.

Users often say: convert to smart object, make smart layer, embed layer.

Use when: non-destructive transforms/filters are needed on a raster or shape layer. Do NOT use when: the layer is already a Smart Object — returns success with already_smart_object. Do NOT use on background layers — unlock or duplicate first.

Returns: JSON { ok, summary, details: { layer_name, kind, already_smart_object? } }. Preconditions: active document; target layer must be selected or named. Side effects: one history step.

Replace the embedded contents of a Smart Object layer from an image file. Preserves transforms, warps, and Smart Filters on the layer.

Users often say: replace smart object, swap mockup screen, relink embedded file.

Use when: updating a mockup or template Smart Object with a new asset file. Do NOT use when: the target is not a Smart Object — convert first or use photoshop_place_image. Do NOT use for linked Smart Objects that need Relink to File — this replaces embedded contents.

Returns: JSON { ok, summary, details: { layer_name, file_path } }. Preconditions: Smart Object layer active or named; file_path must exist (absolute). Side effects: replaces embedded pixels.

Open a Smart Object for editing (double-click / Edit Contents). The embedded .psb becomes the active document until you save and close it.

Users often say: edit smart object, open embedded file, double-click smart layer.

Use when: modifying pixels inside an embedded Smart Object non-destructively. Do NOT use when: replacing the whole asset — use photoshop_replace_smart_object_contents.

Returns: JSON { ok, summary, details: { parent_document, embedded_document, layer_name } }. Preconditions: Smart Object layer active or named. Side effects: active document switches to the embedded .psb — save/close it to return to the parent document.

Create an independent Smart Object via Copy — unlinked duplicate with its own embedded contents.

Users often say: new smart object via copy, independent smart copy, duplicate smart object separately.

Use when: you need a second Smart Object that does not share embedded data with the original. Do NOT use when: you want linked instances — use photoshop_duplicate_layer (Layer via Copy).

Returns: JSON { ok, summary, details: { source_layer_name, new_layer_name, kind } }. Preconditions: Smart Object layer active or named. Side effects: adds a new Smart Object layer.

Scale the active layer to the document canvas, keeping aspect ratio. fillDocument: false (default) fits inside and may letterbox; true covers the canvas and may crop the layer.

Use when: a placed layer should match the canvas size. Do NOT use when: you want a specific percent — use photoshop_scale_layer. Do NOT use when: the document canvas itself should change size — use photoshop_resize_image or photoshop_crop_document.

Returns: confirmation of the fit. Preconditions: active document and active layer. Side effects: transforms that layer. Does not change document dimensions. Reversible with photoshop_undo.

Scale the active layer by a percentage (100 leaves the size unchanged). centerAnchor true (default) scales from the center; false scales from the top-left.

Use when: a numeric percent scale on one layer. Do NOT use when: the layer should fit the canvas automatically — use photoshop_fit_layer_to_document. Do NOT use when: the document dimensions should change — use photoshop_resize_image. Do NOT use when: the layer has no pixels yet — fill it first. An empty layer fails with an empty bounding rectangle.

Returns: the scale percent applied. Preconditions: active document and active layer. Side effects: transforms that layer, one history step. 100% does not change size; any other percent is not idempotent. Reversible with photoshop_undo.

Move the active layer by specified offset

Rotate the active layer by degrees (positive is clockwise) around its center. The document canvas does not rotate.

Use when: one layer needs a rotation. Do NOT use when: the layer should scale or move in pixels — use photoshop_scale_layer or photoshop_move_layer. Do NOT use when: the whole canvas orientation should change — this tool does not rotate the document.

Returns: the degrees applied. Preconditions: active document and active layer. Side effects: transforms that layer, one history step. A second call adds another rotation. Reversible with photoshop_undo.

Rasterize the active layer (convert text/smart object to normal layer)

Set the active layer opacity to an absolute 0–100 value. The number replaces the current opacity; it is not added to it.

Use when: the active layer should be more or less transparent. Do NOT use when: the layer should be fully hidden from the stack — use photoshop_set_layer_visibility. Do NOT use when: fading into the background with a mask gradient — use photoshop_recipe_gradient_fade.

Returns: the opacity that was set. Preconditions: active document and active layer. Side effects: opacity only. The same value is idempotent. Reversible with photoshop_undo.

Set the blend mode of the active layer.

COLOR is the Photoshop UI name (Colorize); it is mapped to ExtendScript BlendMode.COLORBLEND.

Show or hide the active layer

Set the all-lock flag on the active layer. locked: true blocks further edits to that layer; false clears the lock.

Use when: the user asks to lock or unlock the current layer. Do NOT use when: the layer should only be hidden — use photoshop_set_layer_visibility. Do NOT use when: a different layer is the target — use photoshop_select_layer_by_name first.

Returns: confirmation of the lock state. Preconditions: active document and active layer. Side effects: sets layer.allLocked. The same boolean is idempotent. Reversible with photoshop_undo or by calling again with the opposite value.

Rename the active layer. Does not change pixels, order, or visibility.

Use when: the active layer needs a stable name for a later photoshop_select_layer_by_name. Do NOT use when: many layers should be renamed by kind — use photoshop_recipe_organize_layers. Do NOT use when: a different layer is the target — use photoshop_select_layer_by_name first.

Returns: the new layer name. Preconditions: active document and active layer. Side effects: the name only. Setting the same name is idempotent. Reversible with photoshop_undo.

Duplicate the active layer. The duplicate becomes the active layer; returns its name and, when available, its layer id.

Merge every visible layer into one layer. Hidden layers stay in the stack.

Use when: the user wants visible layers combined and hidden layers kept. Do NOT use when: every layer, including hidden ones, should become a single Background — use photoshop_flatten_image. Do NOT use when: only two named layers should combine — this always merges all visible layers.

Returns: confirmation that visible layers were merged. Preconditions: active document with at least one visible layer. Side effects: destroys the separate visible layers in one history step. Reversible with photoshop_undo.

Flatten the active document into a single Background layer. Hidden layers are discarded.

Use when: the user explicitly wants one background layer and no remaining layer stack. Do NOT use when: hidden layers should survive — use photoshop_merge_visible_layers. Do NOT use when: layers must stay editable.

Returns: confirmation that the document was flattened. Preconditions: active document. Side effects: destroys every layer, mask, and hidden pixel. photoshop_undo can restore the stack while history still holds it.

Apply Gaussian Blur filter to the active layer

Apply Unsharp Mask to the active raster layer (amount, radius, threshold). This is a pixel filter on one layer, not a web-export sharpen pass.

Use when: sharpening one layer in the open document. Do NOT use when: preparing a file for the web — use photoshop_recipe_prepare_for_web. Do NOT use when: you want edge extraction for an overlay sharpen — use photoshop_apply_high_pass.

Returns: the amount, radius, and threshold applied. Preconditions: active document and a normal raster layer. Text and Smart Objects are rasterized first, which drops live type and smart-object edits. Side effects: changes pixels in one history step. Reversible with photoshop_undo.

Apply Add Noise to the active raster layer (amount percent, UNIFORM or GAUSSIAN, optional monochromatic).

Use when: grain or noise on one raster layer. Do NOT use when: the goal is blur or sharpen — use photoshop_apply_gaussian_blur or photoshop_apply_sharpen.

Returns: the amount, distribution, and monochromatic flag applied. Preconditions: active document and a normal raster layer. Text and Smart Objects are rasterized first. Side effects: destructive pixels, one history step. A second call adds more noise. Reversible with photoshop_undo.

Apply Motion Blur to the active raster layer (angle in degrees, distance in pixels).

Use when: directional streak blur on one layer. Do NOT use when: a round blur is enough — use photoshop_apply_gaussian_blur. Do NOT use when: blur should keep edges — use photoshop_apply_smart_blur.

Returns: the angle and radius applied. Preconditions: active document and a normal raster layer. Text and Smart Objects are rasterized first. Side effects: destructive pixels, one history step. Reversible with photoshop_undo.

Apply the High Pass filter to the active raster layer — edge/detail extraction for sharpening workflows or frequency separation prep.

Users often say: high pass filter, sharpen edges, extract details, frequency separation high layer.

Use when: sharpening via overlay blend, detail extraction, or prepping a high-frequency layer. Do NOT use on text, Smart Objects, or the Background layer — rasterize or convert first (photoshop_rasterize_layer).

Returns: JSON { ok, summary, details: { filter, radius, context } }. Preconditions: active document; normal (raster) layer selected. Side effects: one history step.

Apply the Smart Blur filter to the active raster layer — edge-preserving blur for smoothing skin or simplifying backgrounds.

Users often say: smart blur, edge-preserving blur, smooth skin blur, blur but keep edges.

Use when: subtle smoothing that respects edges (portraits, product cleanup). Do NOT use on text, Smart Objects, or the Background layer — rasterize first (photoshop_rasterize_layer). Do NOT use when: uniform blur is enough — use photoshop_apply_gaussian_blur.

Returns: JSON { ok, summary, details: { filter, radius, threshold, mode, quality, context } }. Preconditions: active document; normal (raster) layer selected. Side effects: one history step.

Apply Image > Adjustments > Brightness/Contrast once to the active layer. Values are deltas on pixels, not an adjustment layer.

Users often say: fix exposure, add contrast, brighten, darken.

Use when: a quick brightness/contrast pass on the current raster layer. Do NOT use when: exposure in stops on an editable layer — use photoshop_adjust_exposure. Do NOT use when: a non-destructive tonal curve — use photoshop_adjust_curves. Do NOT use when: automatic black and white points — use photoshop_auto_levels.

Returns: the brightness and contrast values applied. Preconditions: active document and active layer. Text and Smart Objects are rasterized first. Side effects: destructive pixels, one history step. Calling again applies another delta. Reversible with photoshop_undo.

Shift hue, saturation, and lightness on the active layer via Image > Adjustments > Hue/Saturation. Values are applied once to pixels, not stored as an adjustment layer.

Use when: a direct color shift on the current layer is enough. Do NOT use when: the change must stay editable — use photoshop_adjust_vibrance or photoshop_adjust_curves. Do NOT use when: the user wants a cinematic grade — use photoshop_recipe_apply_color_grade.

Returns: the hue, saturation, and lightness that were applied. Preconditions: active document and active layer. Text and Smart Objects are rasterized first, and a non-Normal blend mode is reset to Normal. Side effects: destructive pixel edit, one history step. Reversible with photoshop_undo.

Run Auto Levels on the active layer. Photoshop sets the black, white, and gray points; there is no amount parameter.

Users often say: fix flat image, auto tone, make it pop (mild).

Use when: a one-shot automatic level fix on the current layer. Do NOT use when: only contrast should move — use photoshop_auto_contrast. Do NOT use when: you want a specific brightness and contrast delta — use photoshop_adjust_brightness_contrast. Do NOT use when: the correction must stay an editable adjustment layer — use photoshop_adjust_curves.

Returns: confirmation that Auto Levels ran. Preconditions: active document and active layer. Text and Smart Objects are rasterized first. Side effects: destructive pixels, one history step. Reversible with photoshop_undo.

Run Auto Contrast on the active layer. Photoshop picks the contrast; there is no amount parameter.

Use when: a one-shot automatic contrast fix on the current layer. Do NOT use when: you need numeric brightness and contrast — use photoshop_adjust_brightness_contrast. Do NOT use when: black, white, and gray points should move — use photoshop_auto_levels. Do NOT use when: a non-destructive curve — use photoshop_adjust_curves.

Returns: confirmation that Auto Contrast ran. Preconditions: active document and active layer. Text and Smart Objects are rasterized first. Side effects: destructive pixels, one history step. Reversible with photoshop_undo.

Create a Curves adjustment layer on the active document.

Users often say: make it pop, S-curve, fix flat image, auto tone, improve contrast.

Use when: global tonal correction via a non-destructive Curves adjustment layer. Do NOT use when: stylistic cinematic grade — use photoshop_recipe_apply_color_grade.

Returns: JSON { ok, summary, details: { layer_name, preset } }. Preconditions: active document. Side effects: adds Curves adjustment layer.

Desaturate the active layer (convert to grayscale)

Invert colors of the active layer

List installed fonts available to Photoshop.

Use when: choosing a font for photoshop_create_text_layer or photoshop_set_text_font. TextItem.font requires the PostScript name — use postScriptName from results, or pass display name to set/create tools (they resolve automatically).

Returns: fonts array ({ name, postScriptName, family, style }), total count, truncated flag. First call may be slow (app.fonts.length can exceed 1000). Side effects: none.

Install a font file for the current user and reload Photoshop's font list without quitting.

Use when: photoshop_list_fonts does not include a font the user wants, and they already have the font file. Does not download fonts. file_path is an absolute path to a .ttf, .otf, .ttc, or .otc. macOS copies it to ~/Library/Fonts (Font Book, Current User). Windows installs it for the current user only, not for all users. If Photoshop is open, this calls app.refreshFonts() so the new PostScript names are listed immediately. Do not quit Photoshop.

Fredoka Bold is the Bold named instance inside the variable font Fredoka[wdth,wght].ttf (SIL Open Font License, Google Fonts). Its PostScript name is Fredoka-Bold. There is no separate Fredoka Bold file in that release.

Returns: installed_path, post_script_names, fonts_refreshed. Side effects: writes the current-user font folder and reloads the open app's font list.

Set font family and size for active text layer.

Accepts display name (e.g. "Arial") or PostScript name (e.g. "ArialMT") — resolved via app.fonts. Use photoshop_list_fonts to discover available fonts. If the font is not listed, install its file with photoshop_install_font. That reloads the open app's font list; do not quit Photoshop.

Set one RGB color on the whole active text layer.

Use when: the entire text layer should share one color. Do NOT use when: creating the layer — pass red, green, and blue on photoshop_create_text_layer. Do NOT use when: only a character range should change color — use photoshop_set_text_ranges. Do NOT use when: font, size, tracking, or alignment should change too — use photoshop_set_text_style.

Returns: the RGB color applied. Preconditions: active document and an active text layer. Side effects: updates the text color. The same RGB is idempotent. Reversible with photoshop_undo.

Set justification on the whole active text layer (LEFT through FULLYJUSTIFIED).

Use when: the entire text layer should share one alignment. Do NOT use when: creating the layer — pass alignment on photoshop_create_text_layer. Do NOT use when: only a character range should change, or font, color, and tracking should change too — use photoshop_set_text_ranges or photoshop_set_text_style.

Returns: confirmation of the alignment. Preconditions: active document and an active text layer. Side effects: updates TextItem.justification. The same alignment is idempotent. Reversible with photoshop_undo.

Replace the string contents of the active text layer. Font, color, and alignment stay as they are.

Use when: the wording of an existing text layer should change. Do NOT use when: no text layer exists yet — use photoshop_create_text_layer. Do NOT use when: only style should change — use photoshop_set_text_style, photoshop_set_text_font, photoshop_set_text_color, or photoshop_set_text_alignment.

Returns: confirmation with the new text. Preconditions: active document and an active text layer. Side effects: replaces the characters. The same string is idempotent. Reversible with photoshop_undo.

Set layer-wide typography on the active text layer: tracking, leading, point vs paragraph box, alignment, font, size, color.

Users often say: letter spacing, tracking, line height, leading, text box width, paragraph text, 字间距, 行高, 文本框.

Use when: tightening/loosening type, setting line height, converting to a wrapped paragraph box, or batching several text attributes in one undo-friendly call. Do NOT use when: creating a new layer — pass the same fields on photoshop_create_text_layer. Do NOT use when: mixed fonts/colors inside one layer — use photoshop_set_text_ranges. Do NOT use execute_script for tracking/leading/box.

Returns: JSON { ok, summary, details: { style } }. Preconditions: active text layer. Side effects: mutates TextItem attributes.

Apply mixed fonts, sizes, and colors inside a single text layer (Action Manager textStyleRange).

Users often say: mixed type, two fonts in one line, multicolor text, 混排, 同一文字层.

Use when: one layer must contain more than one font or color. from is inclusive, to is exclusive (JavaScript slice / ExtendScript string indexes). Do NOT use when: the whole layer shares one style — use photoshop_set_text_style. Do NOT split into extra layers for mixed type unless this tool errors.

Returns: JSON { ok, summary, details: { style, ranges } }. Preconditions: active text layer. Unspecified gaps keep the layer default style. Side effects: rewrites character styles; restores tracking/leading/box afterward.

Read the active pixel selection bounds in document pixels (read-only).

Use when: verifying selection exists and its size/position before mask, fill, or recipe steps. Do NOT use when: creating or modifying a selection — use photoshop_select_rectangle or photoshop_select_subject.

Returns: JSON { ok, summary, details: { has_selection, bounds?, context } }. Preconditions: active document. Side effects: none.

Create an elliptical pixel selection from a bounding box (anti-aliased).

Use when: circular or oval masks, vignettes, or radial edits inside a region. Do NOT use when: a rectangular region is enough — use photoshop_select_rectangle.

Returns: JSON { ok, summary, details: { shape, bounds?, context } }. Preconditions: active document; right > left and bottom > top. Side effects: replaces current selection.

Expand the active pixel selection outward by a pixel amount.

Use when: growing a tight subject selection or adding padding before feather/fill. Do NOT use when: no selection exists — create one first.

Returns: JSON { ok, summary, details: { pixels, bounds?, context } }. Preconditions: active document and active pixel selection. Side effects: modifies selection.

Contract (shrink) the active pixel selection inward by a pixel amount.

Use when: tightening a loose selection or trimming halo after expand. Do NOT use when: no selection exists — create one first.

Returns: JSON { ok, summary, details: { pixels, bounds?, context } }. Preconditions: active document and active pixel selection. Side effects: modifies selection.

Feather (soften) the edges of the active pixel selection.

Use when: soft transitions before fill, mask, or delete operations. Do NOT use when: a hard edge is required or no selection exists.

Returns: JSON { ok, summary, details: { pixels, bounds?, context } }. Preconditions: active document and active pixel selection. Side effects: modifies selection edges.

Save the active pixel selection to a new alpha channel.

Use when: preserving a selection for later reload or batch workflows. Do NOT use when: no selection exists — create one first.

Returns: JSON { ok, summary, details: { channel_name, context } }. Preconditions: active document and active pixel selection. Side effects: adds alpha channel.

Create a rectangular pixel selection from corner coordinates.

Use when: masking, cropping a region, or preparing for layer mask. Do NOT use when: subject isolation is needed — use photoshop_recipe_remove_background.

Returns: selection bounds [left, top, right, bottom]. Preconditions: active document. Side effects: replaces, adds, subtracts, or intersects the current selection. mode intersect/add/subtract uses Action Manager and does not depend on the SelectionType enum.

Select every pixel of the active document. Does not change layer pixels.

Use when: the next fill, mask, or filter should cover the whole canvas. Do NOT use when: only a region is needed — use photoshop_select_rectangle or photoshop_select_subject. Do NOT use when: the selection should be cleared — use photoshop_deselect.

Returns: confirmation that the document is selected. Preconditions: active document. Side effects: replaces the current selection. Idempotent. Reversible with photoshop_undo.

Clear the current pixel selection. Pixels are unchanged.

Use when: a selection should be cleared before the next edit. Do NOT use when: you want the inverse region selected — use photoshop_invert_selection. Do NOT use when: you want every pixel selected — use photoshop_select_all.

Returns: confirmation that the selection was cleared. Preconditions: active document. Safe when nothing is selected. Side effects: selection only. Idempotent. Reversible with photoshop_undo if a selection existed.

Invert the current pixel selection: selected pixels become unselected and the rest become selected. Layer pixels are unchanged.

Use when: a selection exists and the user wants the opposite region. Do NOT use when: no selection exists — create one with photoshop_select_rectangle or photoshop_select_all. Do NOT use when: the layer colors should invert — use photoshop_invert.

Returns: confirmation that the selection was inverted. Preconditions: active document and an existing selection. Side effects: selection only. Calling twice restores the original selection. Reversible with photoshop_undo.

Create a layer mask on the active layer from the current selection (reveal selection).

Users often say: mask this, hide the background, non-destructive cutout (after selection).

Use when: non-destructive hide/show after a selection exists. Do NOT use when: no selection exists — create selection first or use remove_background recipe.

Returns: maskCreated confirmation. Preconditions: active document and active selection. Side effects: adds mask to active layer.

Delete the layer mask from active layer

Bake the active layer mask into its pixels and remove the mask. Pixels the mask hid are deleted.

Use when: the user wants the mask permanently applied. Do NOT use when: the mask should stay editable — leave it, or create one with photoshop_create_layer_mask. Do NOT use when: the mask should be discarded without changing pixels — use photoshop_delete_layer_mask.

Returns: confirmation that the mask was applied. Preconditions: active document and an active layer that has a mask. Side effects: destroys masked-out pixels and the mask. Reversible with photoshop_undo while history holds it.

Run Select Subject on the active layer (creates a pixel selection only, no mask).

Users often say: cut out, isolate subject, select person, select object.

Use when: you need a subject selection for masking, fill, or further edits. Do NOT use when: full background removal with mask — use photoshop_recipe_remove_background.

Returns: JSON { ok, summary, details: { selected, method } }. Preconditions: PS ≥ 23, active document, non-Background active layer with a recognizable subject. Side effects: replaces current selection.

Fill the current pixel selection using Content-Aware Fill.

Users often say: remove distraction, erase object, content aware fill, inpaint selection.

Use when: a rectangular or other selection covers the area to remove/replace. Do NOT use when: no selection exists — use photoshop_select_rectangle first. Do NOT use when: generative remove is requested — not scriptable; use this fill or manual touch-up.

Returns: JSON { ok, summary, details: { filled } }. Preconditions: active document and active pixel selection. Side effects: modifies pixels inside selection; deselects afterward.

Apply a linear black-to-white gradient on the active layer mask channel (fade/blend).

Users often say: fade into background, gradient mask, blend subject, soft edge fade.

This paints on an existing layer mask — not a Gradient Fill layer. Use when: softening edges or fading a layer into the background through its mask. Do NOT use when: subject is not isolated — use photoshop_recipe_remove_background or photoshop_create_layer_mask first.

Returns: JSON { ok, summary, details: { applied, direction, angle, mask_auto_created? } }. Preconditions: active document and active layer. Creates a reveal-all mask if none exists. Side effects: modifies layer mask pixels; two history steps when mask is auto-created.

Create a clipping mask on the active layer (or a named layer).

Users often say: clip to layer below, clipping mask, clip this layer, mask to shape below.

Use when: the active layer should be visible only where the layer directly below it has opaque pixels. Do NOT use when: the layer is already clipped — returns success with already_clipping. Do NOT use when: the layer is the bottom-most layer — there is no base layer to clip into.

Returns: JSON { ok, summary, details: { layer_name, is_clipping, already_clipping? } }. Preconditions: active document; target layer must sit directly above the base layer below it in the same group/stack. Side effects: one history step (groupEvent).

Release (remove) the clipping mask from the active layer (or a named layer).

Users often say: unclip, release clipping mask, remove clipping mask.

Use when: a clipped layer should become independent again. Do NOT use when: the layer is not clipped — returns not_clipping error.

Returns: JSON { ok, summary, details: { layer_name, is_clipping: false } }. Preconditions: active document; target layer must currently be a clipping mask (grouped). Side effects: sets layer.grouped = false; one history step.

Play a named action from a named action set in the Actions panel. The action runs whatever steps were recorded; this tool does not limit them.

Use when: the user names an existing action and action set to replay. Do NOT use when: no recorded action exists — use a photoshop_recipe_* tool or an atomic photoshop_* tool. Do NOT use when: you need to run arbitrary JSX — use photoshop_execute_script.

Returns: the action result text. Preconditions: actionName and actionSetName must match the Actions panel; an open document if the action expects one. Side effects: whatever the action recorded (it may delete layers, change pixels, or save). photoshop_undo reverts only the history steps the action left behind.

Execute custom ExtendScript (JSX) code inside Photoshop (advanced escape hatch).

Use when: no existing tool covers the operation and you can write safe JSX. Do NOT use when: a recipe or atomic tool exists — prefer photoshop_recipe_* or photoshop_* tools. Do NOT use when: painting a two-color gradient — use photoshop_fill_gradient. Document.gradients does not exist and throws "undefined is not an object".

Returns: script return value serialized as text/JSON. IMPORTANT: Your code runs inside a wrapping IIFE. Use an explicit return to pass data back — a bare trailing expression returns undefined. Example: return { ok: true }; Objects are serialized with toSource() and parsed automatically on macOS and Windows. Long scripts: pass timeout_ms (up to 600000) so the default 30s budget does not kill the job. Preconditions: valid ExtendScript; active document if script expects one. Side effects: depends on code.

Step the active document back through history (Ctrl/Cmd+Z). Each call moves the active history state earlier by steps (default 1).

Users often say: undo, geri al, ctrl z, cmd z, son değişikliği geri al. Use when: reverting the last edit or a short run of edits. Do NOT use when: you need to reapply an undone edit — use photoshop_redo. Do NOT use when: you only need to inspect the stack — use photoshop_get_history.

Returns: text confirmation with the step count. Preconditions: active document with history. Side effects: restores an earlier state and drops the current one onto the redo stack. Not idempotent — a second call undoes further. Reversible with photoshop_redo while those states remain.

Redo the previously undone operation(s), equivalent to Ctrl/Cmd+Shift+Z.

Users often say: redo, yinele, geri alınanı uygula. Use when: reapplying the change that was just undone. Do NOT use when: stepping back through history — use photoshop_undo.

Returns: text confirmation with the step count. Preconditions: active document with something on the redo stack. Side effects: moves the history state forward.

Read the history stack of the active document, including which state is current. Does not change pixels.

Use when: deciding how many steps photoshop_undo or photoshop_redo should take. Do NOT use when: you want to change the document — use photoshop_undo or photoshop_redo.

Returns: the history state list as text. Preconditions: active document. Side effects: none.

Reorder the active layer relative to a named layer. position is ABOVE, BELOW, TOP, or BOTTOM of targetLayerName. This changes stacking order, not canvas pixels.

Use when: the active layer must sit above or below a specific other layer. Do NOT use when: it should go to the top or bottom of the whole stack — use photoshop_move_layer_to_top or photoshop_move_layer_to_bottom. Do NOT use when: it should move one step — use photoshop_move_layer_up or photoshop_move_layer_down. Do NOT use when: you mean a pixel offset on the canvas — use photoshop_move_layer.

Returns: text confirmation of the new stack position. Preconditions: active document, an active layer, and an existing targetLayerName. Side effects: stacking order only. Reversible with photoshop_undo.

Move the active layer to the top of the layer stack

Move the active layer to the bottom of the layer stack

Move the active layer up one position in the layer stack

Move the active layer down one position in the layer stack

Return a cheap read-only snapshot of Photoshop session state (active document, layer, selection).

Use when: before any tool that needs an active document/layer, or after an error to recover context. Do NOT use when: you only need a visual preview — use photoshop_get_preview instead.

Returns: JSON with hasDocument, openDocumentCount, documents[] (id, name, width, height, saved, is_active for every open file), document (id, name, path, saved, width, height, resolution, colorMode, bitsPerChannel, layerCount, layers[] up to 40 top-level layers, artboards), activeLayer, activeArtboard, hasSelection. path is omitted until the file has been saved. Capture document.id and pass it as document_id on later mutating calls. Artboard ids come from document.artboards[].id. Preconditions: none (safe on empty session). Side effects: none.

Export the active document as a base64 JPEG preview for visual verification.

Use when: after visual edits to confirm result before reporting success to the user. Do NOT use when: you only need numeric state — use photoshop_get_state (much cheaper).

Returns: MCP image content block (JPEG) plus metadata text (document size, color mode, up to 40 top-level layer names). Hosts that support MCP Apps also render ui://photoshop/preview. Preconditions: active document required. Side effects: creates and deletes a temp file; does not modify the document.

Return version-aware feature flags for the installed Photoshop (Select Subject v2, Generative Fill, etc.).

Use when: once per session before suggesting AI-powered features or gated recipes. Do NOT use when: Photoshop version is already known from photoshop_get_version.

Returns: JSON { version, features: { select_subject_v2, generative_fill, ... } }. Preconditions: none. Side effects: none.

Fill the current selection using Adobe Generative Fill (Firefly) with a text prompt.

Use when: adding or replacing content inside a selection with generative AI. Do NOT use when: no selection exists — create one first or use photoshop_select_subject. Do NOT use when: Photoshop version lacks generative_fill — check photoshop_get_capabilities.

Returns: { ok, summary, details: { action_id, prompt, wait } }. Preconditions: PS 24+ with generative credits; active pixel selection. Side effects: modifies pixels in selection; may consume Adobe generative credits.

Remove content using the AI Remove tool (or generative fill fallback) on the current selection.

Use when: erasing distractions, people, or objects with generative AI. Do NOT use when: generative unavailable — fallback to photoshop_recipe_remove_distraction.

Returns: { ok, summary, details }. Preconditions: selection or auto_select_subject; generative_fill capability. Side effects: inpaints selected region; consumes generative credits when cloud-backed.

Extend the canvas beyond its edges using Generative Expand (Firefly).

Use when: outpainting, extending background, or expanding composition.

Returns: { ok, summary, details: { direction, prompt, wait } }. Preconditions: active document; generative_fill capability. Side effects: enlarges canvas with generated content.

Upscale the active document using Generative Upscale (PS 27+).

Use when: increasing resolution with AI detail recovery. Do NOT use when: generative_upscale flag is false — use photoshop_resize_image.

Returns: { ok, summary, details }. Preconditions: generative_upscale capability; signed-in Adobe account.

Replace the sky using Photoshop native Sky Replacement when available.

Use when: a sky image path is provided and native AI sky replacement is supported. Fallback: photoshop_recipe_sky_blend for manual composite.

Returns: { ok, summary, details }. Preconditions: active document; optional sky_image_path for custom sky.

Photoshop Generate Image (Firefly ImageGen): create an image from a text prompt.

Use when: the user asks for ImageGen, text-to-image, or a new picture from a description.

Returns: { ok, summary, details }. Preconditions: generative_fill capability; Adobe generative credits.

Apply a Photoshop Neural Filter via the companion UXP bridge plugin.

Use when: skin smoothing, harmonize composite layers, depth blur, super zoom, or colorizing B&W photos. Do NOT use when: uxp_bridge_reachable is false — install uxp-plugin per docs/development.md.

Returns: { ok, summary, details }. Preconditions: UXP bridge plugin running in Photoshop; PS 22+.

Apply a layer style (drop shadow, outer glow, stroke, bevel & emboss) to the active layer via Action Manager layer effects.

Users often say: add shadow, glow effect, outline this layer, stroke, bevel, 3D button look, katmana gölge ver.

Use when: quick presentational effects on the active layer (cards, buttons, mockups, text pop). Do NOT use when: you need full custom layer-effects control — use photoshop_execute_script with a custom layerEffects descriptor.

Returns: JSON { ok, summary, details: { style, layer_name } }. Preconditions: active document with an active pixel/text layer. Side effects: sets the chosen effect on the active layer. Drop shadow uses the given angle (Use Global Light is off).

Apply a Color Lookup (3D LUT) adjustment layer for cinematic color grading. Accepts a built-in LUT name (e.g. "Crisp_Warm.3dl", "Kodak 5218 Fuji 3510.3dl", "Moonlight.3dl") or an absolute path to a .cube/.3dl/.look file.

Users often say: cinematic grade, film look, teal and orange, apply LUT, sinematik renk.

Use when: stylistic non-destructive color grade in one step. Do NOT use when: basic tonal fixes — use photoshop_adjust_curves or photoshop_auto_levels.

Returns: JSON { ok, summary, details: { layer_name, lut, lut_source } }. Preconditions: active document. Side effects: adds a Color Lookup adjustment layer.

Create a Vibrance adjustment layer. Vibrance boosts muted colors while protecting skin tones.

Users often say: make colors pop (safely), boost saturation without clown look.

Returns: JSON { ok, summary, details: { layer_name, vibrance, saturation } }. Preconditions: active document. Side effects: adds a Vibrance adjustment layer.

Create an Exposure adjustment layer (stops, offset, gamma correction).

Users often say: fix underexposed photo, brighten by a stop, gamma fix.

Returns: JSON { ok, summary, details: { layer_name, exposure, offset, gamma } }. Preconditions: active document. Side effects: adds an Exposure adjustment layer.

Create a Photo Filter adjustment layer (warming/cooling/custom tint with density control).

Users often say: warm it up, cool it down, add a tint, golden hour look.

Returns: JSON { ok, summary, details: { layer_name, color, density } }. Preconditions: active document. Side effects: adds a Photo Filter adjustment layer.

Create a Gradient Map adjustment layer (black→white by default) for duotone/B&W tonal remapping.

Users often say: duotone look, gradient map B&W, remap tones.

Returns: JSON { ok, summary, details: { layer_name, reverse } }. Preconditions: active document. Side effects: adds a Gradient Map adjustment layer.

List the data sets defined on the active document (Image > Variables > Data Sets).

Use when: before applying data sets or debugging a data-driven template.

Returns: JSON { ok, summary, details: { datasets, active, count } }. Preconditions: active document with variables/data sets defined.

Import a Photoshop variables/data-sets XML file into the active document (the same file Image > Variables > Data Sets > Import accepts).

Users often say: load data sets, import variables XML, data-driven graphics.

Use when: the template PSD already has variable-bound layers and you want to load rows from an XML file. Do NOT use when: generating a batch from a CSV directly — use photoshop_recipe_csv_to_cards.

Returns: JSON { ok, summary, details: { count, datasets } }. Preconditions: active document with variables defined (Image > Variables > Define).

Batch-export the active document once per data set: applies each data set, saves a copy, moves on. "Mail merge for images".

Users often say: generate all variants, batch personalize, render every row.

Use when: data sets are already imported (photoshop_import_datasets) and you want one file per row.

Returns: JSON { ok, summary, details: { exported, skipped, output_paths } }. Preconditions: active document with data sets. Side effects: writes files to output_dir.

Load 2+ image files into one document, convert to a smart object and apply a stack mode (mean/median/max/min/...). Classic "remove tourists from N shots" or noise reduction — no generative AI involved.

Users often say: remove tourists, median stack, average these photos, noise stack, turistleri sil.

Use when: the user has multiple aligned shots of the same scene and wants a statistical blend. Do NOT use when: removing a single object from one photo — use photoshop_generative_remove or photoshop_content_aware_fill.

Returns: JSON { ok, summary, details: { file_count, mode, layer_name } }. Preconditions: 2+ existing image files. Side effects: opens the files; the stacked result becomes the active document.

Export a copy of the active document as PNG, JPEG, WebP or AVIF without changing the open document. WebP/AVIF require Photoshop 23.2+/recent builds and return a clear error when unsupported.

Users often say: export for web, save as webp, quick export png.

Use when: web-ready delivery formats are needed (WebP/AVIF/modern pipelines), or one artboard from a multi-screen file. Do NOT use when: saving the working document itself — use photoshop_save_document. For every artboard at once use photoshop_export_artboards.

Returns: JSON { ok, summary, details: { path, format, method, artboard_id? } }. Preconditions: active document. Side effects: writes one file to path. Optional artboard_id exports only that board (duplicate + crop).

List artboards in the active document with id, name, pixel bounds, and which one contains the active layer.

Users often say: artboards, 画板, multi-screen, iPhone and iPad frames, device layouts.

Use when: the document is an artboard file (UI/multi-screen) and you need artboard_id before export or edits. Do NOT use when: listing open document tabs — use photoshop_list_documents.

Returns: JSON { ok, summary, details: { count, artboards[] } }. Empty list if the document has no artboards. Preconditions: active document. Side effects: none.

Create a Photoshop artboard (AM artboardSection) at an explicit origin or placed to the right of existing artboards.

Users often say: add iPhone frame, new artboard, multi-screen layout, 画板 ekle.

Use when: building a multi-device / multi-screen document. First artboard converts a regular canvas into an artboard document. Do NOT use when: you only need a new document tab — use photoshop_create_document.

Returns: JSON { ok, summary, details: { artboard, count } }. Preconditions: active document. Side effects: adds an artboard layer group.

Select an artboard layer group by artboard_id (preferred) or unique name so subsequent edits and Select All target that board.

Use when: switching between device frames in an artboard document. Do NOT use when: switching document tabs — use photoshop_set_active_document.

Returns: JSON { ok, summary, details: { artboard } }. Preconditions: target artboard exists (photoshop_list_artboards). Side effects: changes the active layer.

Export every artboard in the active document to a folder (duplicate + crop to artboardRect, then PNG/JPEG/WebP/AVIF).

Users often say: export all artboards, multi-screen PNG, 画板 çıktısı.

Use when: delivering one file per artboard. Long jobs use a 600s script timeout. Do NOT use when: exporting the whole canvas once — use photoshop_export_as.

Returns: JSON { ok, summary, details: { exported[], failed[], folder } }. Preconditions: document with at least one artboard. Side effects: writes files; does not modify the original.

THE tool for "remove background" / "arka planı sil" / cut out / isolate subject. Call this once and stop. Unlocks a locked Background layer, then runs Photoshop native Remove Background (Select Subject / Color Range only if native is unavailable). One undo reverts everything.

Use when: the user wants the background gone. Hair, busy interiors, product shots — still this tool. Do NOT rasterize, duplicate, hide layers, select_subject, create_layer_mask, or execute_script instead of this recipe.

Returns: { ok, summary, undo_history_states_consumed, details.method = remove_background | remove_layer_background | select_subject | color_range_fallback }.

Preconditions: an active document. Native Remove Background needs a current Photoshop; Select Subject fallback needs PS ≥ 23. Side effects: may unlock/rename the Background layer; attaches a pixel mask; no pixels destroyed; one undo reverts everything.

Set up a non-destructive portrait enhancement: duplicates the active layer, builds a frequency separation pair (low/high) for skin smoothing, and adds an auto-tone curves adjustment on top. Grouped as "Enhance Portrait" and reversible with one undo.

Users often say: smooth skin, retouch portrait, fix blemishes, clean up face.

Use when: the user asks to "enhance", "retouch", "clean up" or "smooth" a portrait photo and is happy with a baseline that they can further tweak interactively. Do NOT use when: the user wants destructive, final edits — recommend manual frequency separation work via photoshop_recipe_frequency_separation instead so they can paint by hand.

Returns: { ok, summary, details: { intensity, radius_px, group_name } }.

Preconditions: active document with a NORMAL or background-converted raster layer. Side effects: appends one layer group of 2-3 layers above the active layer; original layer untouched.

Export a web-optimized version of the active document: duplicate, convert to sRGB, downscale longest edge, sharpen for screen, save to disk. The source PSD stays untouched.

Use when: the user wants a shareable JPEG/PNG sized for the web from the current artwork. Do NOT use when: the user wants multiple platform-specific exports — use photoshop_recipe_export_social_variants. Do NOT call photoshop_save_document afterwards; this recipe already wrote the file.

Returns: { ok, summary, output_paths, undo_history_states_consumed }.

Preconditions: active document. Format is jpeg (default) or png. Side effects: writes one file to disk; the source document is unchanged.

Render one JPEG per requested social-media platform from the active document. Each variant is center-cropped/resized to the platform spec and saved to disk.

Use when: the user wants multi-platform deliverables in one shot. Do NOT use when: only one export is needed (use photoshop_recipe_prepare_for_web instead) or when platforms differ by content rather than crop (recipe does not change content, only frame).

Returns: { ok, summary, output_paths, details: { variants } }.

Preconditions: active document. Aspect ratios that differ from the source result in a center-crop (no padding). Side effects: writes one file per platform; source unchanged.

Apply a named color grading preset as a non-destructive layer group (Hue/Saturation adjustment + brightness/contrast tweak).

Users often say: cinematic look, teal and orange, moody grade, color grade.

Use when: the user wants a quick stylistic look applied to the active document. Do NOT use when: the user wants subject-specific color edits (e.g. only the skin) — current recipe applies globally.

Returns: { ok, summary, details: { preset, group_name } }.

Preconditions: active document in RGB mode. CMYK/Grayscale return unsupported_color_mode. Side effects: adds one layer group with adjustment layers; one undo reverts.

Build a frequency separation stack (Low + High) on top of the active layer for hands-on retouching. Does not apply any smoothing itself — the user paints into the layers afterwards.

Users often say: frequency separation, split texture and color, manual retouch setup.

Use when: the user explicitly wants frequency separation setup, typically for portrait or product retouching. Do NOT use when: the user wants a one-shot result without painting — use photoshop_recipe_enhance_portrait instead.

Returns: { ok, summary, details: { radius_px, group_name } }.

Preconditions: active document with a NORMAL raster active layer. Side effects: appends a "Frequency Separation" layer group with 2 prepared layers; one undo reverts everything.

Iterate a directory of asset images, replace the contents of the named Smart Object in the active mockup PSD for each asset, and export a flattened JPEG per variant. The mockup's perspective/warp on the Smart Object is preserved.

Use when: the user has a mockup PSD and wants to render it once per design asset (logos, screens, product photos). Do NOT use when: the asset is not a single layer (use photoshop_place_image manually) or when the active document has no Smart Object with the requested name.

Returns: { ok, summary, output_paths, details: { variants: [{ source_asset, output_path }] } }.

Preconditions: active document containing a Smart Object layer named exactly as requested; assets_dir must exist and be readable. Side effects: writes one JPEG per asset; the active mockup PSD ends up with the LAST asset placed.

Tidy the active document's layer stack: rename layers using a consistent scheme and optionally auto-group them by kind. Never deletes, merges or rasterizes — visual output stays identical.

Use when: the user complains about layer mess ("layer 1 copy 2", "untitled 7") or asks for organization. Do NOT use when: the user wants smart, semantic naming based on layer content beyond text — recipe only summarizes text layers, not image content.

Returns: { ok, summary, details: { renamed_count, group_count } }.

Preconditions: active document. Side effects: renames top-level layers and (optionally) moves them into kind-grouped folders; one undo reverts everything.

One-shot gradient fade on the active layer mask: creates a reveal-all mask if needed, then paints a linear black-to-white gradient for soft edge blending. Wrapped in a single undoable history step.

Users often say: fade into background, gradient mask, blend subject, soft edge fade, arka planı yumuşat.

This applies a linear gradient on the layer mask channel — not a Gradient Fill layer. Use when: the user wants the active layer to fade into the background or layers below through its mask. Do NOT use when: the subject is not isolated — use photoshop_recipe_remove_background first. Do NOT use when: replacing the sky with an external image — use photoshop_recipe_sky_blend.

Returns: { ok, summary, undo_history_states_consumed, details: { direction, start_pct, end_pct, mask_created, layer_name } }.

Preconditions: active document with an active layer. Side effects: creates or modifies the active layer mask; one undo reverts everything.

One-shot sky composite: places an external sky image, adds a layer mask, and applies a horizon gradient fade. Wrapped in a single undoable history step.

Users often say: replace sky, fix blown sky, better clouds, swap sky background.

Use when: the user provides a sky image path and native sky replacement is unavailable or manual blend is preferred. Do NOT use when: no sky_image_path is available — ask the user for an absolute file path first. Do NOT use when: fading the active subject layer only — use photoshop_recipe_gradient_fade.

Returns: { ok, summary, undo_history_states_consumed, details: { sky_image_path, layer_name, horizon_pct, feather_pct, direction } }.

Preconditions: active document; sky image file must exist on disk. Side effects: adds a placed sky layer with gradient mask; one undo reverts everything.

One-shot dodge & burn setup: creates a 50% gray layer in Overlay or Soft Light mode for non-destructive light sculpting. Wrapped in a single undoable history step.

Users often say: dodge and burn, sculpt light, lighten face, darken shadows.

Use when: the user wants a ready-to-paint dodge & burn layer above the subject. Do NOT use when: the user wants automated retouch — this only sets up the paint layer; paint white (dodge) and black (burn) manually at low opacity. Do NOT use when: automated portrait smoothing is enough — use photoshop_recipe_enhance_portrait instead.

Returns: { ok, summary, undo_history_states_consumed, details: { layer_name, blend_mode } }.

Preconditions: active document with a raster-compatible active layer. Side effects: adds one "Dodge & Burn" layer above the active layer; one undo reverts.

One-shot distraction removal: generative AI remove when available, else content-aware fill. Wrapped in a single undoable history step.

Users often say: remove that person, erase distraction, content aware remove, clone out object.

Use when: the user has selected the object or region to remove. Do NOT use when: no selection exists — use photoshop_select_rectangle or photoshop_select_subject first.

Returns: { ok, summary, undo_history_states_consumed, details }. Preconditions: active document with an active pixel selection. Side effects: fills/removes selected pixels; clears selection.

Split the active wide document into N equal vertical slices and export them as sequentially numbered files for a seamless Instagram/TikTok carousel (panorama swipe effect).

Use when: the user wants a seamless/swipeable carousel, split panorama, or multi-slide export of one wide design. Typical request: "split this into a 5-slide carousel". Do NOT use when: the user wants the same content reframed per platform (use photoshop_recipe_export_social_variants) or a single crop (use photoshop_crop_document).

Returns: { ok, summary, output_paths (in slide order), details: { slides, slice_width } }.

Preconditions: active document whose width is at least slides pixels. Side effects: writes one file per slide; source document is unchanged.

Apply a text or logo watermark to every image in a folder and export watermarked JPEGs. Replaces the clunky record-an-action + File > Automate > Batch workflow.

Use when: the user wants to watermark many photos at once (copyright text, studio logo). Do NOT use when: watermarking a single open document (use photoshop_create_text_layer / photoshop_place_image directly) or removing watermarks (not supported).

Returns: { ok, summary, output_paths, details: { processed, failed: [{ file, error }] } }. Files that fail are skipped, not fatal.

Preconditions: assets_dir exists; either text or logo_path given. No active document required. Side effects: writes one JPEG per source image; source files are never modified.

Turn the active portrait into a passport/ID photo: removes the background via Select Subject, replaces it with white, crops around the subject with ICAO-style headroom, resizes to the exact official pixel size at 300 DPI, and exports a JPEG. Optionally also builds a 10×15 cm print sheet with multiple copies.

Use when: passport photo, visa photo, ID photo, vesikalık, biyometrik fotoğraf. Do NOT use when: the document has no clear single subject, or official compliance must be guaranteed — head-size rules are approximated from subject bounds (no face detection); official acceptance is NOT guaranteed.

Returns: { ok, summary, output_paths, details: { spec, width, height, sheet } }.

Preconditions: PS ≥ 23 (Select Subject v2); active document with a single-person portrait. Side effects: writes one JPEG (+ one sheet JPEG when make_sheet); source document is unchanged.

Data-driven graphics batch: convert a CSV file into Photoshop data sets, apply each row to the active template document and export one image per row. "Mail merge for images" — name cards, badges, certificates, personalized banners.

Users often say: csv to images, batch name cards, personalized banners, generate badges from spreadsheet, sertifika bastır.

CSV rules: first row = variable names matching the variables defined in the template PSD (Image > Variables > Define). A cell holding an absolute path to an image file (.png/.jpg/.webp/.tif/.psd) is treated as a pixel-replacement variable.

Use when: the user has a template PSD with variable-bound layers and a CSV of rows. Do NOT use when: the document has no variables defined — define them in Photoshop first (Image > Variables > Define).

Returns: { ok, summary, details: { rows, exported, output_paths, xml_path } }.

Preconditions: active document with variable-bound layers; readable CSV file. Side effects: writes a temp variables XML and one output file per row into output_dir.