editmamei 1.9.3 → 1.9.5

package/dist/backends/gimp/bridge/ops.py

@@ -817,8 +817,11 @@ def op_open(args):
             # 'indexed'", but nothing propagates to Python), so a bare call here would silently
             # report `ok: true` with the ORIGINAL precision still in effect, misleading the
             # caller into thinking their promotion applied when it didn't. Checking the return
-            # value turns that into a real, catchable failure.
-            if not img.convert_precision(_PRECISION_ENUM[precision]):
+            # value turns that into a real, catchable failure. GIMP also returns `False` when the
+            # image already has the target precision (a 16-bit TIFF opened at '16'), and that is
+            # already the outcome asked for, so it is not attempted.
+            target = _PRECISION_ENUM[precision]
+            if img.get_precision() != target and not img.convert_precision(target):
                 raise lib.OpError(
                     'gimp_op_failed',
                     "precision promotion to %r failed for this image (base_type=%s); GIMP "
@@ -2254,22 +2257,40 @@ def _proxy_render(img, max_px):
     return dup, unmirrored
 
 
+# Filters whose geometry is a fraction of their layer's own extent (`lib.build_vignette_params`):
+# a crop before they render would re-centre them on the cropped area.
+_EXTENT_RELATIVE_OPERATIONS = frozenset({'gegl:vignette'})
+
+
 def _region_full_res(img, region):
-    """Full-res duplicate, cropped to `region`, flattened. Caller deletes it. A plain
+    """Full-res duplicate, cropped to `region` and flattened. Caller deletes it. A plain
     `Image.duplicate()` copies each layer's real live DrawableFilters (not just pixels), so
-    rendering this way is exact -- the filter runs at native resolution over the cropped area
-    BEFORE any later downscale, unlike the preview proxy (which shrinks the base first and then
-    has to approximate a spatial filter's radius, see `_mirror_filters`).
+    rendering this way is exact -- the filter runs at native resolution BEFORE any later
+    downscale, unlike the preview proxy (which shrinks the base first and then has to approximate
+    a spatial filter's radius, see `_mirror_filters`).
+
+    The crop comes first, because a full-size flatten per region is far slower with heavy filters.
+    An image carrying a filter in `_EXTENT_RELATIVE_OPERATIONS` is the exception: it is flattened
+    at full size and cropped after, so the filter lands where the whole image shows it.
 
     `region` is validated against `img`'s FULL-RES bounds before anything is duplicated (partly
     or fully outside raises `invalid_argument` rather than silently clamping to whatever sliver
     overlaps); the duplicate itself is torn down on ANY failure after that, not just the size
     check, so a crop/flatten error can never leak an orphaned image."""
     x, y, w, h = lib.validate_region(region, img.get_width(), img.get_height())
+    extent_relative = any(
+        f.get_operation_name() in _EXTENT_RELATIVE_OPERATIONS
+        for l in _all_layers(img)
+        for f in l.get_filters()
+    )
     dup = img.duplicate()
     try:
-        dup.crop(w, h, x, y)
-        layer = dup.flatten()
+        if extent_relative:
+            layer = dup.flatten()
+            dup.crop(w, h, x, y)
+        else:
+            dup.crop(w, h, x, y)
+            layer = dup.flatten()
     except Exception:
         dup.delete()
         raise

package/dist/backends/gimp/session.js

@@ -5,6 +5,7 @@ import { basename, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Logger } from '../../utils/logger.js';
 import { userOwnedTempRoot } from '../../utils/temp.js';
+import { windowsSystemTool } from '../../platform/windows-system-tool.js';
 import { GimpError, GIMP_ERROR_CODES } from './errors.js';
 export const READY_TIMEOUT_MS = 180_000;
 export const CALL_READY_WAIT_MS = 30_000;
@@ -45,7 +46,9 @@ export function defaultTreeKill(proc) {
     if (hasExited(proc) || proc.pid === undefined)
         return;
     if (process.platform === 'win32') {
-        spawnSync('taskkill', ['/PID', String(proc.pid), '/T', '/F'], { windowsHide: true });
+        spawnSync(windowsSystemTool('taskkill.exe'), ['/PID', String(proc.pid), '/T', '/F'], {
+            windowsHide: true,
+        });
         return;
     }
     try {

package/dist/cli/clients/shell.js

@@ -1,7 +1,8 @@
 import { spawn } from 'node:child_process';
+import { windowsSystemTool } from '../../platform/windows-system-tool.js';
 export async function isOnPath(cmd) {
     const probe = process.platform === 'win32'
-        ? spawn('where', [cmd], { stdio: 'ignore', windowsHide: true })
+        ? spawn(windowsSystemTool('where.exe'), [cmd], { stdio: 'ignore', windowsHide: true })
         : spawn('command', ['-v', cmd], { stdio: 'ignore', shell: '/bin/sh' });
     return new Promise((resolve) => {
         const finish = (ok) => {

package/dist/cli/report.js

@@ -6,6 +6,6 @@ export async function runReport(opts = {}) {
     const bundle = await collect({ note: opts.note });
     const { path } = await write(bundle);
     out(`\n  Wrote an anonymized diagnostic bundle to:\n    ${path}\n\n`);
-    out(`  It contains recent logs + system info — no images, no full file paths, no tool arguments.\n`);
+    out(`  It contains recent logs + system info — no images, no full file paths, and no tool arguments outside error messages.\n`);
     out(`  Attach this file to a new issue at ${ISSUES_URL} so the maintainers can debug.\n\n`);
 }

package/dist/core/preview-privacy.js

@@ -40,15 +40,13 @@ export function withholdImages(result) {
     if (counter.n === 0)
         return result;
     const what = counter.n === 1 ? 'An image was' : `${counter.n} images were`;
+    const text = `${what} withheld because the user's privacy.send_previews_to_llm setting is off. ` +
+        'Work from the text and numbers; ask the user if you need to see the image.';
     return {
         ...stripped,
-        content: [
-            ...(stripped.content ?? []),
-            {
-                type: 'text',
-                text: `${what} withheld because the user's privacy.send_previews_to_llm setting is off. ` +
-                    'Work from the text and numbers; ask the user if you need to see the image.',
-            },
-        ],
+        content: [...(stripped.content ?? []), { type: 'text', text }],
+        ...(stripped.structuredContent
+            ? { structuredContent: { ...stripped.structuredContent, images_withheld: text } }
+            : {}),
     };
 }

package/dist/core/server.js

@@ -61,10 +61,12 @@ function hashRetryKey(tool, args) {
 export const FIRST_RUN_DISCLOSURE = 'First run: Editmamei collects content-free usage telemetry (tool name, ' +
     'success, duration, bytes returned, version/edition/OS/PS-version, install channel, ' +
     'which AI client connected, Node/OS/architecture versions, and per-session counts like ' +
-    'edits made and retries) to find what breaks. It never sends image content, file paths, ' +
-    'or tool arguments. The only identifier is a random install ID. Opt out anytime: ' +
-    '`editmamei config set telemetry.usage false` (or edit ~/.editmamei/settings.json). ' +
-    'Opt in to sanitized diagnostics: `editmamei config set telemetry.diagnostics true`.';
+    'edits made and retries) to find what breaks. Usage telemetry never sends image content, ' +
+    'file paths, or tool arguments. The only identifier is a random install ID. Opt out ' +
+    'anytime: `editmamei config set telemetry.usage false` (or edit ' +
+    '~/.editmamei/settings.json). Opt in to sanitized diagnostics (error messages, which can ' +
+    'name a layer or repeat a value you passed): ' +
+    '`editmamei config set telemetry.diagnostics true`.';
 export const BACKGROUND_VERSION_PROBE_TIMEOUT_MS = 3_000;
 const PING_ROUND_TRIP_CLASSES = new Set([
     'timeout',
@@ -265,7 +267,7 @@ export class EditmameiServer {
             this.toolRegistry.register('ps_ping', {
                 tool: {
                     name: 'ps_ping',
-                    description: 'Test connection to Photoshop and report session-start discovery signals. Read-only and idempotent. Call this once at the start of a session to confirm liveness before invoking any other tool. **If the user has given you an open-ended editing task, ALSO call `ps_overview` after this** — it returns the workflow contract + capabilities map + verification primitives so you can plan well. Returns `version` (folds the removed get-version tool), `custom_action_sets` (count of Action Sets loaded in the Photoshop Actions palette — non-zero means recorded workflows exist; if action tools are available in this build they will appear in `tools/list`), `user_templates` (count of saved Editmamei templates), and `open_documents` (names of documents already open in Photoshop, so the LLM does not have to ask which doc to edit).',
+                    description: 'Test connection to Photoshop and report session-start discovery signals. Read-only and idempotent. Call this once at the start of a session to confirm liveness before invoking any other tool. **If the user has given you an open-ended editing task, ALSO call `ps_overview` after this** — it returns the workflow contract + capabilities map + verification primitives so you can plan well. Returns `version` (folds the removed get-version tool), `custom_action_sets` (count of Action Sets loaded in the Photoshop Actions palette — non-zero means recorded workflows exist; if action tools are available in this build they will appear in `tools/list`), `user_templates` (count of saved Editmamei templates), and `open_documents` (names of documents already open in Photoshop, so the LLM can see which document to target).',
                     inputSchema: {
                         type: 'object',
                         properties: {},

package/dist/core/tool-registry.js

@@ -1,6 +1,7 @@
 import { Logger } from '../utils/logger.js';
 import { getToolTimeoutMs } from '../utils/operation-timeouts.js';
 import { budgetContextFor, runWithToolBudget } from '../utils/tool-budget-context.js';
+import { missingRequiredArg } from '../utils/validate.js';
 export class ToolRegistry {
     logger;
     tools;
@@ -48,7 +49,13 @@ export class ToolRegistry {
         let error;
         let result;
         try {
-            result = await runWithToolBudget(budgetContextFor(name, getToolTimeoutMs(name)), () => definition.handler(args));
+            const missing = missingRequiredArg(definition.tool.inputSchema, args);
+            result = missing
+                ? {
+                    content: [{ type: 'text', text: `Missing required argument: ${missing}` }],
+                    isError: true,
+                }
+                : await runWithToolBudget(budgetContextFor(name, getToolTimeoutMs(name)), () => definition.handler(args));
             if (result?.isError) {
                 success = false;
                 const firstText = result.content?.find((c) => c.type === 'text');

package/dist/delivery/client.js

@@ -14,6 +14,7 @@ export class DeliveryError extends Error {
 const MAX_ARTIFACT_BYTES = 64 * 1024 * 1024;
 const USER_AGENT = 'editmamei-delivery-client/1';
 const HEADER_KEY = 'x-editmamei-license-key';
+const HEADER_ACTIVATION = 'x-editmamei-activation-id';
 const defaultFetch = (url, init) => fetch(url, init);
 const DEFAULT_RETRY = { attempts: 4, baseDelayMs: 1000, maxDelayMs: 65_000 };
 const DEFAULT_MIN_INTERVAL_MS = 500;
@@ -25,6 +26,7 @@ export class DeliveryClient {
     sleep;
     minIntervalMs;
     maxArtifactBytes;
+    activationId;
     lastRequestAt = 0;
     constructor(opts = {}) {
         this.cfg = opts.config ?? resolveDeliveryConfig();
@@ -33,6 +35,7 @@ export class DeliveryClient {
         this.sleep = opts.sleep ?? defaultSleep;
         this.minIntervalMs = opts.minRequestIntervalMs ?? DEFAULT_MIN_INTERVAL_MS;
         this.maxArtifactBytes = opts.maxArtifactBytes ?? MAX_ARTIFACT_BYTES;
+        this.activationId = opts.activationId || undefined;
         if (!this.cfg.baseUrl) {
             throw new DeliveryError('Delivery endpoint is not configured. Set EDITMAMEI_DELIVERY_URL ' +
                 '(e.g. http://localhost:8787 for a local wrangler dev Worker).', 0, 'not_configured');
@@ -130,7 +133,11 @@ export class DeliveryClient {
         try {
             return await this.fetchImpl(`${this.cfg.baseUrl}${path}`, {
                 method: 'GET',
-                headers: { 'user-agent': USER_AGENT, [HEADER_KEY]: key },
+                headers: {
+                    'user-agent': USER_AGENT,
+                    [HEADER_KEY]: key,
+                    ...(this.activationId ? { [HEADER_ACTIVATION]: this.activationId } : {}),
+                },
             });
         }
         catch (err) {

package/dist/delivery/provision.js

@@ -3,6 +3,7 @@ import { sha256Hex } from './crypto.js';
 import { verifyModuleSignature, verifyModuleSignatureV2, digestsRootSha256Hex, isModuleFileDigestArray, } from './signing.js';
 import { installModule, readInstalledModule } from './store.js';
 import { KERNEL_ABI } from '../kernel/host-api.js';
+import { readLicense } from '../license/store.js';
 import { Logger } from '../utils/logger.js';
 const logger = new Logger('Modules');
 const SKU_RE = /^[a-z0-9-]{2,32}$/;
@@ -15,12 +16,15 @@ export async function provisionModules(key, opts = {}) {
         errors: [],
         notConfigured: false,
     };
+    const license = readLicense(opts);
+    const activationId = license?.key === key ? license.activation_id : undefined;
     let client;
     try {
         client = new DeliveryClient({
             config: opts.config,
             fetchImpl: opts.fetchImpl,
             sleep: opts.sleep,
+            activationId,
         });
     }
     catch (e) {

package/dist/detection/sam-segmenter.js

@@ -63,9 +63,43 @@ function sameImageKey(a, b) {
         a.byteLength === b.byteLength &&
         a.hash === b.hash);
 }
+export function toSamFrame(img) {
+    const long = Math.max(img.width, img.height);
+    if (long === SAM_INPUT)
+        return img;
+    const scale = SAM_INPUT / long;
+    const width = Math.max(1, Math.round(img.width * scale));
+    const height = Math.max(1, Math.round(img.height * scale));
+    const data = new Uint8Array(width * height * 4);
+    for (let y = 0; y < height; y++) {
+        const sy = Math.min(Math.max(((y + 0.5) * img.height) / height - 0.5, 0), img.height - 1);
+        const y0 = Math.floor(sy);
+        const y1 = Math.min(y0 + 1, img.height - 1);
+        const fy = sy - y0;
+        for (let x = 0; x < width; x++) {
+            const sx = Math.min(Math.max(((x + 0.5) * img.width) / width - 0.5, 0), img.width - 1);
+            const x0 = Math.floor(sx);
+            const x1 = Math.min(x0 + 1, img.width - 1);
+            const fx = sx - x0;
+            for (let c = 0; c < 4; c++) {
+                const top = img.data[(y0 * img.width + x0) * 4 + c] * (1 - fx) +
+                    img.data[(y0 * img.width + x1) * 4 + c] * fx;
+                const bottom = img.data[(y1 * img.width + x0) * 4 + c] * (1 - fx) +
+                    img.data[(y1 * img.width + x1) * 4 + c] * fx;
+                data[(y * width + x) * 4 + c] = Math.round(top * (1 - fy) + bottom * fy);
+            }
+        }
+    }
+    return { width, height, data };
+}
+export function encoderInputOf(img) {
+    const framed = toSamFrame(img);
+    return { data: toEncoderInput(framed), dims: [framed.height, framed.width, 3] };
+}
 async function realRunEncoder(img) {
     const session = await loadModel(resolveModelPath(MODEL_ENCODER));
-    const input = new ort.Tensor('float32', toEncoderInput(img), [img.height, img.width, 3]);
+    const { data, dims } = encoderInputOf(img);
+    const input = new ort.Tensor('float32', data, dims);
     const out = await session.run({ input_image: input });
     return out.image_embeddings;
 }

package/dist/platform/windows-detector.js

@@ -2,6 +2,7 @@ import { exec } from 'child_process';
 import { promisify } from 'util';
 import { access, constants } from 'fs/promises';
 import { Logger } from '../utils/logger.js';
+import { windowsSystemTool } from './windows-system-tool.js';
 const execAsync = promisify(exec);
 export class WindowsDetector {
     logger = new Logger('WindowsDetector');
@@ -35,7 +36,7 @@ export class WindowsDetector {
             ];
             for (const key of productKeys) {
                 try {
-                    const { stdout } = await execAsync(`reg query "${key}" /s`);
+                    const { stdout } = await execAsync(`"${windowsSystemTool('reg.exe')}" query "${key}" /s`);
                     const entries = this.readRegistryEntries(stdout);
                     if (entries.length > 0) {
                         const newest = entries.sort((a, b) => b.version.localeCompare(a.version))[0];
@@ -54,7 +55,7 @@ export class WindowsDetector {
             ];
             for (const key of comRegistrations) {
                 try {
-                    const { stdout } = await execAsync(`reg query "${key}" /ve`);
+                    const { stdout } = await execAsync(`"${windowsSystemTool('reg.exe')}" query "${key}" /ve`);
                     const exePath = this.readComServerPath(stdout);
                     if (exePath) {
                         const info = await this.inspectPath(exePath);

package/dist/platform/windows-runner.js

@@ -7,6 +7,7 @@ import { ScriptQueue } from './script-queue.js';
 import { runChildWithTimeout } from './run-child.js';
 import { decodeScriptResult } from './script-result.js';
 import { waitForLaunchReady } from './launch-readiness.js';
+import { windowsSystemTool } from './windows-system-tool.js';
 const execAsync = promisify(exec);
 const LAUNCH_PROBE_TIMEOUT_MS = 2_000;
 const IS_RUNNING_EXEC_TIMEOUT_MS = 3_000;
@@ -21,7 +22,7 @@ export class WindowsScriptRunner {
         try {
             const scriptPath = await dir.write('script.jsx', script);
             const shimPath = await dir.write('run.vbs', this.buildComShim(scriptPath));
-            const { stdout, stderr } = await runChildWithTimeout('cscript', ['//nologo', shimPath], {
+            const { stdout, stderr } = await runChildWithTimeout(windowsSystemTool('cscript.exe'), ['//nologo', shimPath], {
                 timeout: timeoutMs,
                 diagLabel: 'cscript run.vbs',
             });
@@ -61,7 +62,7 @@ End If
     }
     async isRunning() {
         try {
-            const { stdout } = await execAsync('tasklist /FI "IMAGENAME eq Photoshop.exe"', {
+            const { stdout } = await execAsync(`"${windowsSystemTool('tasklist.exe')}" /FI "IMAGENAME eq Photoshop.exe"`, {
                 timeout: IS_RUNNING_EXEC_TIMEOUT_MS,
             });
             return stdout.toLowerCase().includes('photoshop.exe');

package/dist/platform/windows-system-tool.js

@@ -0,0 +1,5 @@
+import { win32 as pathWin32 } from 'node:path';
+export function windowsSystemTool(name, env = process.env) {
+    const root = env.SystemRoot || env.windir || 'C:\\Windows';
+    return pathWin32.join(root, 'System32', name);
+}

package/dist/tools/adjustment-tools.js

@@ -149,9 +149,9 @@ const addAdjustmentLayerSchema = {
         },
         bw_tint_hue: {
             type: 'number',
-            description: 'For type=black_and_white when bw_tint=true. Tint hue in degrees (-180 to 180). Default 220 (cool blue).',
+            description: 'For type=black_and_white when bw_tint=true. Tint hue in degrees (0 to 360; negative values wrap). Default 220 (cool blue).',
             minimum: -180,
-            maximum: 180,
+            maximum: 360,
             default: 220,
         },
         bw_tint_saturation: {
@@ -475,7 +475,7 @@ const addAdjustmentLayerSchema = {
         },
         exp_gamma: {
             type: 'number',
-            description: 'For type=exposure. Gamma correction (0.01 to 9.99). PS default 1.0 (identity). Values <1 brighten midtones; >1 darken them.',
+            description: 'For type=exposure. Gamma correction (0.01 to 9.99). PS default 1.0 (identity). Values >1 brighten midtones; <1 darken them.',
             minimum: 0.01,
             maximum: 9.99,
             default: 1.0,
@@ -622,7 +622,7 @@ const APPLY_ADJUSTMENT_INPUT_SCHEMA = {
         type: {
             type: 'string',
             enum: [...APPLY_ADJUSTMENT_TYPES],
-            description: 'Which destructive adjustment to bake (none exist as adjustment layers in PS). ' +
+            description: 'Which destructive adjustment to bake. shadows_highlights and equalize have no adjustment layer in PS; color_lookup does, and this bakes it instead. ' +
                 'shadows_highlights: one-pass shadow/highlight recovery (shadow_amount, highlight_amount, …). ' +
                 'equalize: parameter-free histogram equalization. ' +
                 'color_lookup: bake a 3DLUT grade — cl_lut_name REQUIRED. ' +
@@ -639,7 +639,7 @@ export function createAdjustmentTools(connection, snippetClient) {
         {
             tool: {
                 name: 'ps_apply_adjustment',
-                description: "Apply a DESTRUCTIVE tonal adjustment that Photoshop does NOT offer as an adjustment layer — chosen via `type`. Runs on a DUPLICATE of the active layer by default (auto-duplicate-first — the original is preserved; revert by deleting the copy); pass `apply_to_active_layer: true` to bake in place. Auto-rasterizes text/smart-object layers. `shadows_highlights` recovers blown highlights + crushed shadows in one pass (defaults match Adobe's dialog: 35 shadow amount, +20 color correction); `equalize` stretches/flattens the histogram (parameter-free); `color_lookup` bakes a 3DLUT grade (cl_lut_name required — leaf name of a file in Presets/3DLUTs/ or an absolute .cube/.3dl/.look path). For EDITABLE tonal/color work, prefer ps_add_adjustment_layer.",
+                description: "Apply a DESTRUCTIVE tonal adjustment, baked into pixels — chosen via `type`. Runs on a DUPLICATE of the active layer by default (auto-duplicate-first — the original is preserved; revert by deleting the copy); pass `apply_to_active_layer: true` to bake in place. Auto-rasterizes text/smart-object layers. `shadows_highlights` recovers blown highlights + crushed shadows in one pass (defaults match Adobe's dialog: 35 shadow amount, +20 color correction); `equalize` stretches/flattens the histogram (parameter-free); `color_lookup` bakes a 3DLUT grade (cl_lut_name required — leaf name of a file in Presets/3DLUTs/ or an absolute .cube/.3dl/.look path). For EDITABLE tonal/color work, prefer ps_add_adjustment_layer.",
                 inputSchema: APPLY_ADJUSTMENT_INPUT_SCHEMA,
                 outputSchema: {
                     type: 'object',

package/dist/tools/brush-tools.js

@@ -16,7 +16,7 @@ const applyBrushStrokeSchema = {
         placement: {
             ...PLACEMENT_SCHEMA,
             description: 'ANCHOR-RELATIONAL stroke path (preferred over supplying pixels): a PATH relation — `along` a traced edge ' +
-                'or a Pro face-mesh landmark curve, `offset-curve`, or `segment` between two anchors — so the stroke traces ' +
+                'or a face-mesh landmark curve, where available, `offset-curve`, or `segment` between two anchors — so the stroke traces ' +
                 'the resolved, gate-verified curve (the FULL polyline, not just endpoints: paint along the jaw / horizon / ' +
                 'under-eye). Strokes ONLY if the gate PASSES. When set, `path` is ignored; tool/brush_size/source_point/' +
                 'colors/dynamics/jitter still apply. See ps_resolve_placement for the anchors + relation vocabulary.',

package/dist/tools/detection-tools.js

@@ -174,7 +174,7 @@ export function createDetectionTools(connection, _snippetClient, client = new On
         {
             tool: {
                 name: 'ps_detect',
-                description: 'The cheap, narrow read: labeled bounding boxes only — faces and/or COCO-80 objects (person, dog, car, chair, sofa, …) in DOCUMENT-pixel space. LOCAL on-device computer vision; the image is never sent anywhere. Use this for real coordinates before a spatially-targeted edit when boxes are all you need — far more reliable than estimating positions from a preview. For the full scene model (regions, horizon, tonal zones, composition, and a menu of selectable named regions), use ps_read_scene instead. `target` selects faces / objects / both. Read-only: renders a throwaway duplicate, never modifies the working document. Boxes are [x1, y1, x2, y2]. Pass `annotate:true` for an annotated preview JPEG (faces cyan, objects magenta) when you need to visually confirm a surprising result.',
+                description: 'The cheap, narrow read: labeled bounding boxes only — faces and/or COCO-80 objects (person, dog, car, chair, sofa, …) in DOCUMENT-pixel space. Detection runs locally on this device; annotate:true returns a JPEG to your AI client. Use this for real coordinates before a spatially-targeted edit when boxes are all you need — far more reliable than estimating positions from a preview. For the full scene model (regions, horizon, tonal zones, composition, and a menu of selectable named regions), use ps_read_scene instead. `target` selects faces / objects / both. Read-only: renders a throwaway duplicate, never modifies the working document. Boxes are [x1, y1, x2, y2]. Pass `annotate:true` for an annotated preview JPEG (faces cyan, objects magenta) when you need to visually confirm a surprising result.',
                 inputSchema: detectSchema,
                 outputSchema: {
                     type: 'object',

package/dist/tools/diagnostics-tools.js

@@ -15,7 +15,7 @@ export function createDiagnosticsTools(_connection, _snippetClient, deps = {}) {
         {
             tool: {
                 name: 'ps_report_problem',
-                description: "Collect an ANONYMIZED diagnostic bundle and write it to the user's Downloads folder so they can attach it to a bug report — use when Editmamei misbehaves (won't connect, a tool keeps failing, unexpected results). The bundle holds recent server logs, system info (Editmamei/OS/Photoshop versions), and a content-free summary of recent tool calls (name, success, duration, error class). It contains NO image content, NO tool arguments, and file paths reduced to basenames. Does not touch Photoshop; writes one JSON file. After calling, tell the user the file path and that they can attach it to a new issue at " +
+                description: "Collect an ANONYMIZED diagnostic bundle and write it to the user's Downloads folder so they can attach it to a bug report — use when Editmamei misbehaves (won't connect, a tool keeps failing, unexpected results). The bundle holds recent server logs, system info (Editmamei/OS/Photoshop versions), and a content-free summary of recent tool calls (name, success, duration, error class). It contains NO image content, the tool-call summary carries NO tool arguments, and file paths are reduced to basenames; log lines can still quote a layer name or a value from an error message. Does not touch Photoshop; writes one JSON file. After calling, tell the user the file path and that they can attach it to a new issue at " +
                     ISSUES_URL +
                     '.',
                 inputSchema: reportSchema,
@@ -47,7 +47,7 @@ export function createDiagnosticsTools(_connection, _snippetClient, deps = {}) {
                         {
                             type: 'text',
                             text: `Wrote an anonymized diagnostic bundle to:\n  ${path}\n\n` +
-                                `It contains recent logs + system info — no images, no full file paths, no tool arguments. ` +
+                                `It contains recent logs + system info — no images, no full file paths, and no tool arguments outside error messages. ` +
                                 `Attach this file to a new issue at ${ISSUES_URL} so the maintainers can debug.`,
                         },
                     ],

package/dist/tools/document-tools.js

@@ -3,7 +3,7 @@ import { runScript } from '../utils/run-script.js';
 import { validateArgs } from '../utils/validate.js';
 import { OPEN_DOCUMENT_TIMEOUT_MS, OPEN_DOCUMENT_REPROBE_TIMEOUT_MS, SAVE_PSD_REPROBE_TIMEOUT_MS, getToolTimeoutMs, } from '../utils/operation-timeouts.js';
 import { toolErrorResult, runSnippetTool } from '../utils/tool-helpers.js';
-import { checkOutputPath, recordOutputPath, requireLocalPath } from '../utils/local-path.js';
+import { checkOutputPath, recordOutputPath, requireLocalImagePath } from '../utils/local-path.js';
 import { purgeSceneChannels } from '../perception/region-precompute.js';
 import { Logger } from '../utils/logger.js';
 const logger = new Logger('document-tools');
@@ -136,7 +136,7 @@ const exportJpegSchema = {
         },
         quality: {
             type: 'integer',
-            description: "JPEG quality 0-100 (the Photoshop 'Save As' / JPEG-dialog scale humans and the UI use). 100 = maximum. Mapped internally to Photoshop's 0-12 JPEGSaveOptions scripting scale (e.g. 90→11, 100→12).",
+            description: "JPEG quality 0-100 (the Photoshop 'Export As' scale). 100 = maximum. Mapped internally to Photoshop's 0-12 JPEGSaveOptions scripting scale (e.g. 90→11, 100→12).",
             default: 90,
             minimum: 0,
             maximum: 100,
@@ -375,7 +375,7 @@ export function createDocumentTools(connection, snippetClient) {
         {
             tool: {
                 name: 'ps_export',
-                description: 'Export the active document to a flattened image file — JPEG or PNG, chosen via `format`. Operates on a duplicate, so the working document is unchanged. Optionally downscales so the long edge equals long_edge_px. JPEG: quality 0-100 (Save-As scale), optional sRGB convert + profile embed. PNG: transparent background (alpha preserved) or flattened onto white, compression 0-9.',
+                description: 'Export the active document to a flattened image file — JPEG or PNG, chosen via `format`. Operates on a duplicate, so the working document is unchanged. Optionally downscales so the long edge equals long_edge_px. JPEG: quality 0-100 (Export As scale), optional sRGB convert + profile embed. PNG: transparent background (alpha preserved) or flattened onto white, compression 0-9.',
                 inputSchema: exportInputSchema,
                 outputSchema: {
                     type: 'object',
@@ -563,7 +563,7 @@ async function openDocumentPipeline(connection, snippetClient, rawArgs) {
     let filePath;
     try {
         const args = validateArgs(openDocumentSchema, rawArgs);
-        filePath = requireLocalPath('file_path', args.file_path);
+        filePath = requireLocalImagePath('file_path', args.file_path);
         const suppressDialogs = args.suppress_dialogs;
         const bitDepth = args.bit_depth;
         const script = await snippetClient.build('openDocumentPipeline', {

package/dist/tools/filter-tools.js

@@ -3,7 +3,7 @@ import { validateArgs } from '../utils/validate.js';
 import { OnnxLandmarkDetectionClient } from '../detection/landmark-detection-client.js';
 import { resolveGatedPlacement, PLACEMENT_SCHEMA } from '../perception/grounding-locate.js';
 import { toolErrorResult, runSnippetTool, applyToActiveLayerProp, asSmartFilterProp, unknownDiscriminator, } from '../utils/tool-helpers.js';
-import { requireLocalPath } from '../utils/local-path.js';
+import { requireLocalImagePath } from '../utils/local-path.js';
 import { LAYER_BLEND_MODES } from '../utils/blend-modes.js';
 import { runSmartFilterOp } from './smart-object-tools.js';
 const gaussianBlurSchema = {
@@ -1653,7 +1653,7 @@ async function applyDisplace(connection, snippetClient, rawArgs) {
         snippet: 'applyDisplace',
         errorPrefix: 'Error applying Displace',
         params: (args) => ({
-            mapPath: requireLocalPath('map_path', args.map_path),
+            mapPath: requireLocalImagePath('map_path', args.map_path),
             horizontalScale: args.horizontal_scale ?? 10,
             verticalScale: args.vertical_scale ?? 10,
             displacementMap: args.displacement_map ?? 'stretch_to_fit',

package/dist/tools/gimp-compose-tools.js

@@ -195,7 +195,7 @@ const canvasSchema = {
                 'pre-existing transparency in those layers. On a GRAYSCALE image a hex color renders as ' +
                 'its LUMINANCE (a weighted gray, not one channel picked out). transparent: genuinely ' +
                 'transparent only in a live, layered document (e.g. saved via gimp_save_xcf) — ' +
-                'gimp_export and gimp_layer op=flatten both flatten first, which fills any transparent ' +
+                'gimp_export (unless keep_alpha or a layered psd) and gimp_layer op=flatten flatten first, which fills any transparent ' +
                 "area with GIMP's ambient background color (white, unchanged by this tool) and drops " +
                 'alpha, not with transparency. A non-transparent fill on an INDEXED image is REFUSED ' +
                 'outright, before the canvas resizes at all — indexed has no backdrop layer type to add.',

package/dist/tools/gimp-geometry-tools.js

@@ -1,6 +1,6 @@
 import { validateArgs } from '../utils/validate.js';
 import { toolGimpErrorResult, unknownDiscriminator } from '../utils/tool-helpers.js';
-import { GIMP_IMAGE_PROP, runGimpTool, pickSchemaDeclaredKeys } from './gimp-shared.js';
+import { GIMP_IMAGE_PROP, effectUpdateFailuresNote, runGimpTool, pickSchemaDeclaredKeys, withWarning, } from './gimp-shared.js';
 const cropSchema = {
     type: 'object',
     properties: {
@@ -75,17 +75,6 @@ const transformCanvasSchema = {
     },
     required: ['image', 'op'],
 };
-export function effectUpdateFailuresNote(failures) {
-    if (!failures || failures.length === 0)
-        return '';
-    const plural = failures.length > 1;
-    const it = plural ? 'them' : 'it';
-    return (` WARNING: ${failures.join(', ')} could not be updated for this transform and ` +
-        `${plural ? 'were' : 'was'} left at ${plural ? 'their' : 'its'} old position/angle/offset/size ` +
-        `instead -- delete ${it} (gimp_filter op=delete) and re-create ${it} if ${plural ? 'they need' : 'it needs'} ` +
-        `to track the content (re-applying THIS SAME transform again would move ${it} a second time, ` +
-        `misaligning ${it} the other way).`);
-}
 async function gimpTransformCanvas(gimp, rawArgs) {
     try {
         const args = validateArgs(transformCanvasSchema, rawArgs);
@@ -100,7 +89,7 @@ async function gimpTransformCanvas(gimp, rawArgs) {
             effectUpdateFailuresNote(result.effect_update_failures);
         return {
             content: [{ type: 'text', text }],
-            structuredContent: result,
+            structuredContent: withWarning(result, effectUpdateFailuresNote(result.effect_update_failures)),
         };
     }
     catch (error) {

package/dist/tools/gimp-selection-tools.js

@@ -2,7 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { rm } from 'node:fs/promises';
 import { validateArgs } from '../utils/validate.js';
 import { toolGimpErrorResult } from '../utils/tool-helpers.js';
-import { GIMP_IMAGE_PROP, GIMP_LAYER_ID_PROP, GIMP_LAYER_PROP, GIMP_MAX_PX_PROP, readRender, defaultPreviewsAllowed, pickSchemaDeclaredKeys, runGimpTool, } from './gimp-shared.js';
+import { GIMP_IMAGE_PROP, GIMP_LAYER_ID_PROP, GIMP_LAYER_PROP, GIMP_MAX_PX_PROP, readRender, defaultPreviewsAllowed, pickSchemaDeclaredKeys, runGimpTool, withWarning, } from './gimp-shared.js';
 const maskResultSchema = {
     type: 'object',
     properties: {
@@ -274,7 +274,14 @@ async function selectionPreview(gimp, rawArgs, previewsAllowedFn) {
                         : ' privacy.send_previews_to_llm is false — image not returned to the model.') +
                     unmirroredNote,
             });
-            return { content, structuredContent: { width: r.width, height: r.height } };
+            return {
+                content,
+                structuredContent: withWarning({
+                    width: r.width,
+                    height: r.height,
+                    ...(r.unmirrored_filters?.length ? { unmirrored_filters: r.unmirrored_filters } : {}),
+                }, unmirroredNote),
+            };
         }
         finally {
             await rm(out, { force: true }).catch(() => undefined);

package/dist/tools/gimp-shared.js

@@ -54,6 +54,21 @@ export async function readRender(path) {
     }
 }
 export const defaultPreviewsAllowed = () => loadSettings().settings.privacy.send_previews_to_llm;
+export function effectUpdateFailuresNote(failures) {
+    if (!failures || failures.length === 0)
+        return '';
+    const plural = failures.length > 1;
+    const it = plural ? 'them' : 'it';
+    return (` WARNING: ${failures.join(', ')} could not be updated for this transform and ` +
+        `${plural ? 'were' : 'was'} left at ${plural ? 'their' : 'its'} old position/angle/offset/size ` +
+        `instead -- delete ${it} (gimp_filter op=delete) and re-create ${it} if ${plural ? 'they need' : 'it needs'} ` +
+        `to track the content (re-applying THIS SAME transform again would move ${it} a second time, ` +
+        `misaligning ${it} the other way).`);
+}
+export function withWarning(structured, note) {
+    const warning = note.trim();
+    return warning ? { ...structured, warning } : structured;
+}
 export async function runGimpTool(spec) {
     try {
         const args = validateArgs(spec.schema, spec.rawArgs);
@@ -61,7 +76,7 @@ export async function runGimpTool(spec) {
         const result = await spec.gimp.call(spec.op, bridgeArgs);
         return {
             content: [{ type: 'text', text: spec.successText(result, args) }],
-            structuredContent: result,
+            structuredContent: withWarning(result, effectUpdateFailuresNote(result.effect_update_failures)),
         };
     }
     catch (error) {

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

@@ -1,7 +1,8 @@
 import { validateArgs } from '../utils/validate.js';
 import { toolGimpErrorResult, unknownDiscriminator } from '../utils/tool-helpers.js';
 import { GIMP_IMAGE_PROP, GIMP_LAYER_PROP, GIMP_LAYER_ID_PROP, pickSchemaDeclaredKeys, } from './gimp-shared.js';
-import { EFFECT_UPDATE_FAILURES_PROP, effectUpdateFailuresNote } from './gimp-geometry-tools.js';
+import { EFFECT_UPDATE_FAILURES_PROP } from './gimp-geometry-tools.js';
+import { effectUpdateFailuresNote } from './gimp-shared.js';
 const TRANSFORM_LAYER_OPS = ['fit', 'scale', 'move', 'rotate', 'flip', 'skew', 'free'];
 const xyProp = (what) => ({
     type: 'object',
@@ -41,8 +42,8 @@ const transformLayerSchema = {
         mode: {
             type: 'string',
             enum: ['fit', 'fill'],
-            description: "fit only. 'fit' letterboxes inside the canvas (shorter edge touches); 'fill' covers it " +
-                '(longer edge touches, overflow is left outside the canvas, not cropped). Defaults to ' +
+            description: "fit only. 'fit' letterboxes the whole layer inside the canvas; 'fill' covers the canvas " +
+                '(overflow is left outside the canvas, not cropped). Defaults to ' +
                 "'fit'.",
         },
         scale_percent: {

package/dist/tools/gimp-verify-tools.js

@@ -4,7 +4,7 @@ import { basename } from 'node:path';
 import { validateArgs } from '../utils/validate.js';
 import { toolGimpErrorResult, unknownDiscriminator } from '../utils/tool-helpers.js';
 import { Logger } from '../utils/logger.js';
-import { GIMP_IMAGE_PROP, GIMP_REGION_PROP, GIMP_MAX_PX_PROP, pickSchemaDeclaredKeys, readRender, defaultPreviewsAllowed, } from './gimp-shared.js';
+import { GIMP_IMAGE_PROP, GIMP_REGION_PROP, GIMP_MAX_PX_PROP, pickSchemaDeclaredKeys, readRender, defaultPreviewsAllowed, withWarning, } from './gimp-shared.js';
 import { regionStatsLines } from './gimp-result-text.js';
 const logger = new Logger('GimpVerifyTools');
 const CHANNELS = ['luminance', 'red', 'green', 'blue'];
@@ -71,7 +71,10 @@ async function gimpGetPreview(gimp, rawArgs, previewsAllowedFn) {
                         : `privacy.send_previews_to_llm is false — image not returned to the model; ${fileNote}.`) +
                     unmirroredNote,
             });
-            return { content, structuredContent: { ...result, path: published ? latestName : null } };
+            return {
+                content,
+                structuredContent: withWarning({ ...result, path: published ? latestName : null }, unmirroredNote),
+            };
         }
         finally {
             await rm(renderPath, { force: true }).catch(() => undefined);
@@ -132,7 +135,7 @@ async function gimpGetHistogram(gimp, rawArgs) {
                     text: `Histogram (${result.exact ? 'exact' : 'proxy'}${result.mask ? `, mask ${result.mask}` : ''}, ${result.pixels.toLocaleString()} px): ${summary}${unmirroredNote}`,
                 },
             ],
-            structuredContent: result,
+            structuredContent: withWarning(result, unmirroredNote),
         };
     }
     catch (error) {
@@ -252,7 +255,10 @@ async function gimpCompare(gimp, rawArgs, previewsAllowedFn) {
                         : '') +
                     unmirroredNote,
             });
-            return { content, structuredContent: reported };
+            return {
+                content,
+                structuredContent: withWarning(reported, unmirroredNote),
+            };
         }
         finally {
             if (beforePath)

package/dist/tools/guide-tools.js

@@ -1,3 +1,4 @@
+import { validateArgs } from '../utils/validate.js';
 import { runSnippetTool } from '../utils/tool-helpers.js';
 const addGuideSchema = {
     type: 'object',
@@ -79,6 +80,7 @@ export function createGuideTools(connection, snippetClient) {
     ];
 }
 async function guides(connection, snippetClient, rawArgs) {
+    validateArgs({ type: 'object', properties: { op: { type: 'string' } }, required: ['op'] }, rawArgs);
     const op = rawArgs.op;
     const { op: _omit, ...rest } = rawArgs;
     switch (op) {

package/dist/tools/history-tools.js

@@ -39,7 +39,7 @@ export function createHistoryTools(connection, snippetClient) {
         {
             tool: {
                 name: 'ps_undo',
-                description: 'Step backward in the document history (equivalent to Ctrl/Cmd+Z). WHEN TO REACH FOR THIS: after an experimental destructive bake (ps_merge mode=visible/flatten, ps_filter op=apply type=*_blur/sharpen/noise) produced a wrong result; after a play_action whose scope you mispredicted; or to revert an entire branch of exploration. Non-destructive workflows (adjustment layers + masks) rarely need this — just tweak/delete the offending layer instead. Reversible via ps_redo as long as no new edit has been made since. Returns current history state, remaining steps, and document context.',
+                description: 'Step backward in the document history (equivalent to Ctrl/Cmd+Z). WHEN TO REACH FOR THIS: after an experimental destructive bake (ps_merge mode=visible/flatten, ps_filter op=apply type=*_blur/sharpen/noise) produced a wrong result; or to revert an entire branch of exploration. Non-destructive workflows (adjustment layers + masks) rarely need this — just tweak/delete the offending layer instead. Reversible via ps_redo as long as no new edit has been made since. Returns current history state, remaining steps, and document context.',
                 inputSchema: undoSchema,
                 outputSchema: HISTORY_STEP_RESULT_SCHEMA,
                 annotations: {

package/dist/tools/image-placement-tools.js

@@ -1,5 +1,5 @@
 import { runSnippetTool } from '../utils/tool-helpers.js';
-import { requireLocalPath } from '../utils/local-path.js';
+import { requireLocalImagePath } from '../utils/local-path.js';
 const PS_COORD_MAX_PX = 300_000;
 const placeImageSchema = {
     type: 'object',
@@ -74,7 +74,7 @@ async function placeImage(connection, snippetClient, rawArgs) {
         errorPrefix: 'Error placing image',
         params: (args) => {
             const params = {
-                filePath: requireLocalPath('file_path', args.file_path),
+                filePath: requireLocalImagePath('file_path', args.file_path),
                 x: args.x,
                 y: args.y,
             };

package/dist/tools/inspect-tools.js

@@ -1,3 +1,4 @@
+import { validateArgs } from '../utils/validate.js';
 import { getMetadata, getMetadataSchema } from './metadata-tools.js';
 import { getHistory } from './history-tools.js';
 import { getLayerTree } from './layer-tools.js';
@@ -78,6 +79,7 @@ export function createInspectTools(connection, snippetClient) {
     ];
 }
 async function inspect(connection, snippetClient, rawArgs) {
+    validateArgs({ type: 'object', properties: { what: { type: 'string' } }, required: ['what'] }, rawArgs);
     const what = rawArgs.what;
     const { what: _omit, ...rest } = rawArgs;
     switch (what) {
@@ -96,7 +98,7 @@ async function inspect(connection, snippetClient, rawArgs) {
                 content: [
                     {
                         type: 'text',
-                        text: `Error: unknown inspect target "${String(what)}". Allowed: ${INSPECT_WHATS.join(', ')}.`,
+                        text: `Error: unknown \`what\` value "${String(what)}". Allowed: ${INSPECT_WHATS.join(', ')}.`,
                     },
                 ],
                 isError: true,

package/dist/tools/path-tools.js

@@ -39,7 +39,7 @@ const pathInputSchema = {
         },
         placement: {
             ...PLACEMENT_SCHEMA,
-            description: 'create_from_placement only: NAME the curve the path follows, as an anchor-relational placement that resolves to a PATH (relation `along` a traced edge / a Pro landmark curve, or a `segment` between two anchors). The spatial-grounding resolver + objective gate produce AND verify the curve; the path is created ONLY if the gate PASSES. Name the curve — do NOT hand-type anchor points.',
+            description: 'create_from_placement only: NAME the curve the path follows, as an anchor-relational placement that resolves to a PATH (relation `along` a traced edge / a landmark curve, where available, or a `segment` between two anchors). The spatial-grounding resolver + objective gate produce AND verify the curve; the path is created ONLY if the gate PASSES. Name the curve — do NOT hand-type anchor points.',
         },
         closed: {
             type: 'boolean',

package/dist/tools/portrait-tools.js

@@ -119,7 +119,7 @@ export function createPortraitTools(connection, snippetClient, client = new Onnx
         {
             tool: {
                 name: 'ps_portrait_touchup',
-                description: 'Detection-driven face touch-ups using LOCAL on-device face detection. op=dodge_face brightens the detected face(s) with a non-destructive masked adjustment layer. op=soften_skin applies a soft blur over the face(s) on a duplicate layer (light, bounding-box-level smoothing). Works from the face bounding box — precise landmark ops (eyes/teeth/lips) are a Pro feature. Multiple faces are handled together. Pair with ps_detect (target=faces) to preview detection first.',
+                description: 'Detection-driven face touch-ups using LOCAL on-device face detection. op=dodge_face brightens the detected face(s) with a non-destructive masked adjustment layer. op=soften_skin applies a soft blur over the face(s) on a duplicate layer (light, bounding-box-level smoothing). Works from the face bounding box — precise landmark ops (eyes/teeth/lips) are not part of this tool. Multiple faces are handled together. Pair with ps_detect (target=faces) to preview detection first.',
                 inputSchema: portraitSchema,
                 outputSchema: {
                     type: 'object',

package/dist/tools/preview-tools.js

@@ -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.',
+                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 ps_place_image / ps_transform_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',

package/dist/tools/scene-tools.js

@@ -332,6 +332,7 @@ async function selectByReference(connection, snippet, client, rawArgs, proRefine
                         method: 'precomputed_channel',
                         passed: true,
                         confidence: 1,
+                        note: 'Loaded from a saved channel. If the image changed since, re-run with refresh:true, and verify with ps_get_selection_preview.',
                         reasons: ['loaded the saved scene:* channel by name'],
                         selection_info: loaded.selection_info,
                         detail: { from: 'precompute' },
@@ -393,7 +394,7 @@ export function createSceneTools(connection, snippetClient, opts = {}) {
         {
             tool: {
                 name: 'ps_read_scene',
-                description: 'The full scene model — run this before a spatially-targeted edit, not the cheaper ps_detect: detected subjects (with the main one flagged) and faces in document pixels, a coarse sky/ground region map, the horizon line (y + placement + confidence), tonal zones (shadow/midtone/highlight bands + coverage), composition geometry (which thirds cell the subject sits in, balance, headroom), and the menu of selectable named regions. The structured model is complete on its own — pass `annotate:true` for an annotated preview JPEG when you actually need to see it drawn. Built using LOCAL on-device vision + classical CV; the image never leaves the machine. Select regions by name with ps_select_by_reference instead of guessing a rectangle. Read-only: renders a throwaway duplicate. Perception is cached per document state, so repeated reads are cheap.',
+                description: 'The full scene model — run this before a spatially-targeted edit, not the cheaper ps_detect: detected subjects (with the main one flagged) and faces in document pixels, a coarse sky/ground region map, the horizon line (y + placement + confidence), tonal zones (shadow/midtone/highlight bands + coverage), composition geometry (which thirds cell the subject sits in, balance, headroom), and the menu of selectable named regions. The structured model is complete on its own — pass `annotate:true` for an annotated preview JPEG when you actually need to see it drawn. Built using LOCAL on-device vision + classical CV; annotate:true returns a JPEG to your AI client. Select regions by name with ps_select_by_reference instead of guessing a rectangle. Read-only: renders a throwaway duplicate. Perception is cached per document state, so repeated reads are cheap.',
                 inputSchema: sceneSchema,
                 outputSchema: {
                     type: 'object',
@@ -447,7 +448,7 @@ export function createSceneTools(connection, snippetClient, opts = {}) {
         {
             tool: {
                 name: 'ps_select_by_reference',
-                description: 'Select a region by NAME instead of coordinates — the natural-mask alternative to a rectangle — with a CONFIDENCE GATE. target=sky/ground/foliage/subject/face/shadows/highlights/skin/above_horizon resolves through the right Photoshop-native method (threshold for sky, invert-sky−subjects for ground, luminance for shadows/highlights, skin-tone colour ∩ the subject box, the detected face/subject box) and is SCORED before it is offered: a clean region is left selected; an unconfident one is NOT selected and reported as honest absence (the city with no real sky gets no sky). Pro adds precise FACE-FEATURE targets backed by the face mesh — face_skin (the retouch mask: face minus eyes/brows/lips), face_eyes, face_brows, face_lips, face_teeth (mouth opening), face_nose, face_under_eye, face_cheeks — each a real geometry-following selection, derived on first request and then saved as a scene:face_* channel so repeats load instantly. `passed`/`confidence` are returned. A region derived here is cached as a `scene:*` channel keyed by TARGET ONLY, so a later call for the same target loads it by name; pass `refresh:true` to force a fresh derive after an edit that changes what the region means, and note that narrowing a call with `label`/`instance`/`composition_context` always derives (it neither reads nor writes that shared channel). The structural floor (coherence, horizon alignment) is never tuned; for an artistic/non-standard shot pass `composition_context` (e.g. profile:big_sky) to relax the compositional priors so a legitimately large sky is not rejected. For target=subject with several present, pass `label` and/or `instance`. Build/inspect with ps_read_scene first; verify with ps_get_selection_preview (the red-overlay is the human/agent oversight view). Prefer this over a rectangle for any real-world region.',
+                description: 'Select a region by NAME instead of coordinates — the natural-mask alternative to a rectangle — with a CONFIDENCE GATE. target=sky/ground/foliage/subject/face/shadows/highlights/skin/above_horizon resolves through the right Photoshop-native method (threshold for sky, invert-sky−subjects for ground, luminance for shadows/highlights, skin-tone colour ∩ the subject box, the detected face/subject box) and is SCORED before it is offered: a clean region is left selected; an unconfident one is NOT selected and reported as honest absence (the city with no real sky gets no sky). Some builds add precise FACE-FEATURE targets backed by the face mesh — face_skin (the retouch mask: face minus eyes/brows/lips), face_eyes, face_brows, face_lips, face_teeth (mouth opening), face_nose, face_under_eye, face_cheeks — each a real geometry-following selection, derived on first request and then saved as a scene:face_* channel so repeats load instantly. `passed`/`confidence` are returned. A region derived here is cached as a `scene:*` channel keyed by TARGET ONLY, so a later call for the same target loads it by name; pass `refresh:true` to force a fresh derive after an edit that changes what the region means, and note that narrowing a call with `label`/`instance`/`composition_context` always derives (it neither reads nor writes that shared channel). The structural floor (coherence, horizon alignment) is never tuned; for an artistic/non-standard shot pass `composition_context` (e.g. profile:big_sky) to relax the compositional priors so a legitimately large sky is not rejected. For target=subject with several present, pass `label` and/or `instance`. Build/inspect with ps_read_scene first; verify with ps_get_selection_preview (the red-overlay is the human/agent oversight view). Prefer this over a rectangle for any real-world region.',
                 inputSchema: selectByReferenceSchema,
                 outputSchema: {
                     type: 'object',

package/dist/tools/selection-tools.js

@@ -398,7 +398,7 @@ const selectionPreviewSchema = {
             type: 'string',
             enum: ['overlay', 'mask', 'both'],
             default: 'overlay',
-            description: "Which rendered image(s) to return inline. 'overlay' (default): a 50% red wash over the selected area (Quick Mask-style — most intuitive). 'mask': a B/W mask (black=selected, white=not) instead. 'both': the overlay followed by the mask, for when you need to compare them side by side. selection_info is returned regardless of this choice.",
+            description: "Which rendered image(s) to return inline. 'overlay' (default): a 50% red wash over the selected area (most intuitive). 'mask': a B/W mask (black=selected, white=not) instead. 'both': the overlay followed by the mask, for when you need to compare them side by side. selection_info is returned regardless of this choice.",
         },
     },
 };
@@ -705,7 +705,7 @@ export function createSelectionTools(connection, snippetClient, client = new Onn
         {
             tool: {
                 name: 'ps_get_selection_preview',
-                description: "Render an inline JPEG so the agent can visually verify what is currently selected: by default a red-wash OVERLAY (50% red over the selected area, Quick Mask-style — most intuitive); pass `image:'mask'` for a B/W MASK (black = selected, white = not) instead, or `image:'both'` for both. selection_info is always returned regardless of `image`. Heavier than the selection_info bundle alone (~2-4s) — call this when the stats look off or before committing a mask. Does NOT modify the source document.",
+                description: "Render an inline JPEG so the agent can visually verify what is currently selected: by default a red-wash OVERLAY (50% red over the selected area, most intuitive); pass `image:'mask'` for a B/W MASK (black = selected, white = not) instead, or `image:'both'` for both. selection_info is always returned regardless of `image`. Heavier than the selection_info bundle alone (~2-4s) — call this when the stats look off or before committing a mask. Does NOT modify the source document.",
                 inputSchema: selectionPreviewSchema,
                 outputSchema: {
                     type: 'object',
@@ -728,7 +728,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). `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.**',
+                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. **Prefer this tool over a hand-written mask script; it already handles masks and gradients.**',
                 inputSchema: LAYER_MASK_INPUT_SCHEMA,
                 outputSchema: {
                     type: 'object',

package/dist/tools/shape-tools.js

@@ -28,7 +28,7 @@ const shapeInputSchema = {
             ...PLACEMENT_SCHEMA,
             description: 'ANCHOR-RELATIONAL placement (preferred over guessing pixels): rectangle/ellipse ← a region relation ' +
                 '(inside/gap) → the resolved region bounding box; line ← a path relation (along/offset-curve over a traced ' +
-                'edge or a Pro face-mesh landmark curve) → a straight line between the resolved curve endpoints. The shape ' +
+                'edge or a face-mesh landmark curve, where available) → a straight line between the resolved curve endpoints. The shape ' +
                 'is created ONLY if the gate PASSES (otherwise an error and no layer). When set, left/top/right/bottom and ' +
                 'start_x/start_y/end_x/end_y are ignored, but styling (fill_color/stroke/weight/corner_radius) still ' +
                 'applies. See the placement-resolver tool, when this build has one, for the anchors + relation vocabulary.',

package/dist/tools/sky-tools.js

@@ -1,5 +1,5 @@
 import { runSnippetTool } from '../utils/tool-helpers.js';
-import { requireLocalPath } from '../utils/local-path.js';
+import { requireLocalImagePath } from '../utils/local-path.js';
 import { SKY_REPLACEMENT_TIMEOUT_MS } from '../utils/operation-timeouts.js';
 import { defaultSkyPreset, loadSkyPresets, matchSkyPreset, } from '../utils/sky-presets.js';
 const PLACEHOLDER_SKY_ID = '00000000-0000-0000-0000-000000000000';
@@ -73,7 +73,7 @@ function resolveSky(args, presets) {
     if (args.sky_file !== undefined) {
         return {
             kind: 'file',
-            path: requireLocalPath('sky_file', args.sky_file),
+            path: requireLocalImagePath('sky_file', args.sky_file),
             label: 'Custom Sky',
         };
     }

package/dist/tools/smart-object-tools.js

@@ -1,6 +1,7 @@
 import { validateArgs } from '../utils/validate.js';
 import { runSnippetTool, toolErrorResult } from '../utils/tool-helpers.js';
 import { LAYER_BLEND_MODES } from '../utils/blend-modes.js';
+const INDICES_RENUMBERED = 'Indices renumbered — re-run op=list before the next index-taking call.';
 const SMART_FILTER_OPS = ['list', 'set_visibility', 'set_blend', 'remove'];
 const smartFilterInputSchema = {
     type: 'object',
@@ -116,9 +117,14 @@ export async function runSmartFilterOp(connection, snippetClient, rawArgs) {
                 params: (a) => ({ index: a.index }),
                 successText: (result) => {
                     const r = result;
-                    return `Removed Smart Filter ${String(r.index)} (${String(r.removed_filter_name)}) from "${String(r.layer_name)}". ${String(r.remaining_count)} remaining. Indices renumbered — re-run op=list before the next index-taking call.`;
+                    return `Removed Smart Filter ${String(r.index)} (${String(r.removed_filter_name)}) from "${String(r.layer_name)}". ${String(r.remaining_count)} remaining. ${INDICES_RENUMBERED}`;
                 },
-            });
+            }).then((result) => result.isError
+                ? result
+                : {
+                    ...result,
+                    structuredContent: { ...result.structuredContent, note: INDICES_RENUMBERED },
+                });
         default:
             return toolErrorResult('Error in ps_filter', new Error(`Unknown smart-filter op: ${String(op)}. Allowed: ${SMART_FILTER_OPS.join(', ')}.`));
     }

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

@@ -1,3 +1,4 @@
+import { validateArgs } from '../utils/validate.js';
 import { runSnippetTool } from '../utils/tool-helpers.js';
 const rotateCanvasSchema = {
     type: 'object',
@@ -60,6 +61,7 @@ export function createTransformCanvasTools(connection, snippetClient) {
     ];
 }
 async function transformCanvas(connection, snippetClient, rawArgs) {
+    validateArgs({ type: 'object', properties: { op: { type: 'string' } }, required: ['op'] }, rawArgs);
     const op = rawArgs.op;
     const { op: _omit, ...rest } = rawArgs;
     switch (op) {

package/dist/utils/local-path.js

@@ -53,6 +53,21 @@ export function requireLocalPath(field, value, opts = {}) {
             throw new PathArgumentError(`"${field}" does not resolve to a stable absolute path ("${String(value)}"). Pass a plain, full path.`);
     }
 }
+function withoutTrailingDotsAndSpaces(path) {
+    let end = path.length;
+    while (end > 0 && (path[end - 1] === '.' || path[end - 1] === ' '))
+        end--;
+    return path.slice(0, end);
+}
+const NOT_AN_IMAGE_EXT_RE = /\.(jsx|jsxbin|jsxinc|js|psjs|atn|abr|pat|asl|grd|tpl)$/i;
+export function requireLocalImagePath(field, value, opts = {}) {
+    const path = requireLocalPath(field, value, opts);
+    if (NOT_AN_IMAGE_EXT_RE.test(withoutTrailingDotsAndSpaces(path))) {
+        throw new PathArgumentError(`"${field}" is a script, Action or preset file, not an image: "${String(value)}". ` +
+            'Open or place an image or document instead.');
+    }
+    return path;
+}
 const PERCENT_ESCAPE_RE = /%[0-9A-Fa-f]{2}/;
 const WIN32_DEVICE_NAME_RE = /^(con|prn|aux|nul|conin\$|conout\$|com[0-9¹²³]|lpt[0-9¹²³])\s*(\..*)?$/i;
 function refuseExtendScriptAmbiguity(field, path, platform) {

package/dist/utils/validate.js

@@ -4,6 +4,10 @@ export class ValidationError extends Error {
         this.name = 'ValidationError';
     }
 }
+export function missingRequiredArg(schema, args) {
+    const props = (schema.properties ?? {});
+    return schema.required?.find((key) => (args[key] === undefined || args[key] === null) && props[key]?.default === undefined);
+}
 export function validateArgs(schema, args) {
     const input = args ?? {};
     const out = {};

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '1.9.3';
+export const VERSION = '1.9.5';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "editmamei",
-  "version": "1.9.3",
+  "version": "1.9.5",
   "description": "Photoshop MCP server: natural-language AI photo editing in desktop Photoshop (Community Edition)",
   "mcpName": "io.github.editmamei/editmamei-photoshop-mcp",
   "editmamei": {