editmamei 1.0.3 → 1.2.0

package/README.md

@@ -47,7 +47,7 @@ Then restart your AI client and ask it: _"Is Photoshop connected?"_
 
 Prefer not to use a terminal? Claude Desktop users can install the one-click [`.mcpb` extension](https://github.com/editmamei/editmamei/releases/latest/download/editmamei.mcpb) directly (no system Node required, Claude Desktop ships its own runtime). Full walkthrough in the [install guide](docs/installation.md).
 
-**Requirements:** Adobe Photoshop 2026 (v27.x), Windows 10/11 or macOS 12+, Node.js 20+ (for the npm path), and an MCP-compatible AI client (Claude Desktop, Cursor, Claude Code).
+**Requirements:** Adobe Photoshop 2026 (v27.x), Windows 10/11 or macOS 12+, Node.js 22+ (for the npm path), and an MCP-compatible AI client (Claude Desktop, Cursor, Claude Code).
 
 ## A session, end to end
 
@@ -75,7 +75,7 @@ These are the choices that shape the surface, and the reason an AI assistant can
 
 ## Tool surface
 
-**87 tools across 16 capability groups** (64 Community, 23 Pro). Every tool is namespaced `ps_*` and discoverable at runtime via `tools/list`. Community tools ship in both editions; Pro tools unlock with a license.
+**79 tools across 16 capability groups** (59 Community, 20 Pro). Every tool is namespaced `ps_*` and discoverable at runtime via `tools/list`. Community tools ship in both editions; Pro tools unlock with a license.
 
 | Group | Edition | Tools |
 | --- | --- | --- |
@@ -85,20 +85,20 @@ These are the choices that shape the surface, and the reason an AI assistant can
 | **Document & canvas** | Community | `create_document` · `open_document` · `close_document` · `save_psd` · `export` · `place_image` · `resize_image` · `crop_document` · `convert_image_mode` · `transform_canvas` · `guides` |
 | **Selection** | Community | `select` · `modify_selection` · `selection_channel` |
 | **Adjustments** | Community | `add_adjustment_layer` · `apply_adjustment` |
-| **Filters** | Community | `apply_filter` |
+| **Filters** | Community | `filter` |
 | **Retouch** | Community | `retouch` |
-| **Layers** | Community | `create_layer` · `delete_layer` · `fill_layer` · `add_fill_layer` · `select_layer` · `move_layer_to_position` · `duplicate_layer` · `copy_to_new_layer` · `convert_to_smart_object` · `rasterize_layer` · `set_layer` · `merge` · `bake_layer` · `add_layer_style` · `transform_layer` · `shape` · `create_group` · `move_layer_to_group` · `set_group_blend_mode` · `ungroup` · `delete_group` |
-| **Masks & paths** | Community | `layer_mask` · `create_clipping_mask` · `path` · `vector_mask` · `apply_image` · `calculations` |
-| **Type** | Community | `create_text_layer` · `set_text` |
+| **Layers** | Community | `create_layer` · `delete_layer` · `fill_layer` · `add_fill_layer` · `select_layer` · `move_layer_to_position` · `duplicate_layer` · `copy_to_new_layer` · `convert_to_smart_object` · `rasterize_layer` · `set_layer` · `merge` · `bake_layer` · `add_layer_style` · `transform_layer` · `shape` · `group` |
+| **Masks & paths** | Community | `layer_mask` · `clipping_mask` · `path` · `vector_mask` · `apply_image` · `calculations` |
+| **Type** | Community | `text` |
 | **Perception** | Community | `detect` · `read_scene` · `select_by_reference` |
 | **AI selection** | Community | `select_subject` · `select_sky` |
 | **AI selection** | Pro | `select_subject_instance` · `select_object` |
 | **Filters** | Pro | `apply_camera_raw` |
-| **Layers (warp)** | Pro | `warp_layer` · `warp_layer_mesh` · `warp_layer_along` · `warp_layer_region` · `warp_layer_to` |
+| **Layers (warp)** | Pro | `warp_layer` |
 | **Perception** | Pro | `edit_object` · `add_text_to_object` · `resolve_placement` |
 | **Face mesh** | Pro | `detect_landmarks` · `select_face_feature` |
 | **Templates** | Pro | `template_create_evidence` · `template_save` · `template_list` · `template_apply` · `template_verify` · `template_recall` · `template_delete` |
-| **Automation** | Pro | `list_actions` · `play_action` · `execute_script` |
+| **Automation** | Pro | `list_actions` · `play_action` · `execute_script` · `batch` |
 
 ## Editions
 
@@ -119,7 +119,7 @@ npm run build
 npm test
 ```
 
-You need Node.js 20+ and a Go toolchain (the build compiles the `editmamei-core` binary that generates Photoshop scripts). The build warns instead of failing when Go is missing, so you can still run the test suite; set `EDITMAMEI_CORE_BIN` to a prebuilt binary if you would rather not install Go.
+You need Node.js 22+ and a Go toolchain (the build compiles the `editmamei-core` binary that generates Photoshop scripts). The build warns instead of failing when Go is missing, so you can still run the test suite; set `EDITMAMEI_CORE_BIN` to a prebuilt binary if you would rather not install Go.
 
 The test suite runs without Photoshop. It verifies the ExtendScript Editmamei generates, never that Photoshop accepted it, so live verification against a real Photoshop is a separate step.
 

package/dist/api/extendscript/_helpers.js

@@ -18,6 +18,75 @@ function normName(s) {
   return result.replace(/\\s+/g, ' ').replace(/^\\s+|\\s+$/g, '').toLowerCase();
 }
 `;
+export const notFoundMessageHelper = `
+function __notFoundMessage(label, requested, groupsOnly) {
+  var kept = [];
+  var total = 0;
+  var walkBroke = false;
+  function __nfEsc(s) {
+    var out = '';
+    for (var c = 0; c < s.length; c++) {
+      var code = s.charCodeAt(c);
+      // Control characters and backslash only — see the doc comment above.
+      if (code < 32 || code === 127 || code === 92) {
+        var hex = code.toString(16);
+        while (hex.length < 4) hex = '0' + hex;
+        out += '\\\\u' + hex;
+      } else {
+        out += s.charAt(c);
+      }
+    }
+    return out;
+  }
+  function consider(layer) {
+    var nm = '';
+    try { nm = String(layer.name); } catch (eN) { walkBroke = true; return; }
+    total++;
+    if (kept.length >= 8) return;
+    nm = __nfEsc(nm);
+    if (nm.length > 40) {
+      nm = nm.substring(0, 40);
+      var cut = nm.lastIndexOf('\\\\u');
+      if (cut > 34) nm = nm.substring(0, cut);
+      // Non-ASCII is no longer escaped, so the cut counts raw UTF-16 units and
+      // can land between the halves of a surrogate pair. Drop a trailing high
+      // surrogate rather than emit a lone one.
+      var lastCode = nm.length > 0 ? nm.charCodeAt(nm.length - 1) : 0;
+      if (lastCode >= 0xD800 && lastCode <= 0xDBFF) nm = nm.substring(0, nm.length - 1);
+      nm = nm + '...';
+    }
+    kept.push(nm);
+  }
+  function walk(layers, depth) {
+    var n = 0;
+    try { n = layers.length; } catch (eL) { walkBroke = true; return; }
+    for (var i = 0; i < n; i++) {
+      var l = null;
+      try { l = layers[i]; } catch (eI) { walkBroke = true; continue; }
+      if (!l) continue;
+      var isGroup = false;
+      try { isGroup = (l instanceof LayerSet); } catch (eG) {}
+      if (isGroup || !groupsOnly) consider(l);
+      if (isGroup && depth < 32) {
+        try { walk(l.layers, depth + 1); } catch (eD) { walkBroke = true; }
+      }
+    }
+  }
+  try { walk(app.activeDocument.layers, 0); } catch (eW) { walkBroke = true; }
+  if (walkBroke && total === 0) {
+    return label + ' not found: ' + __nfEsc(String(requested));
+  }
+  var have;
+  if (total === 0) {
+    have = groupsOnly ? '(no groups)' : '(none)';
+  } else {
+    have = kept.join(', ');
+    if (total > kept.length) have += ' (+' + (total - kept.length) + ' more)';
+    if (walkBroke) have += ' (list may be incomplete)';
+  }
+  return label + ' not found: ' + __nfEsc(String(requested)) + '. Have: ' + have;
+}
+`;
 export const selectionTypeHelpers = `
 function mapSelType(s) {
   if (s === 'add' || s === 'extend') return SelectionType.EXTEND;
@@ -222,8 +291,7 @@ function getContextInfo() {
   // during the context probe should NOT make the op look failed to the
   // caller. On any unexpected throw we return a degraded context with
   // an error_reading field so the caller can see something happened
-  // but the structured result still arrives. T05 P1-4 in the
-  // launch-readiness review.
+  // but the structured result still arrives.
   try {
     var context = {
       hasDocument: app.documents.length > 0

package/dist/api/photoshop-api.js

@@ -33,7 +33,7 @@ class ExtendScriptPhotoshopAPI {
                     'This usually means PS is in a stuck/modal state (a leaked preview duplicate ' +
                     'or a pending dialog from a prior timeout), or there is no active document. ' +
                     'Check that a document is open and try once more; if it persists, dismiss any ' +
-                    'open Photoshop dialog.');
+                    'open Photoshop dialog.', { cause: err });
             }
             throw err instanceof Error ? err : new Error(msg);
         }
@@ -55,6 +55,21 @@ class ExtendScriptPhotoshopAPI {
   // numbers, booleans, null/undefined, arrays, and plain objects. Cycles
   // and very deep nesting are capped via __depth to avoid stack overflow
   // on pathological inputs.
+  //
+  // Everything outside printable ASCII is escaped as a JSON u-escape, not
+  // just the control range. The Windows cscript stdout transport is
+  // codepage-bound and flattens raw non-ASCII to '?' (measured live,
+  // PS 27.2.0), so a layer Photoshop named itself in a non-English UI —
+  // 'Farbfuellung 1' spelled with the u-umlaut — used to reach the caller as
+  // 'Farbf?llung 1'. Naming that layer back at us then missed, because '?'
+  // is not what the layer is called. The escape is valid JSON, survives the
+  // transport, and JSON.parse restores the exact character, so the round trip
+  // is lossless rather than merely legible. Every outcome the script itself
+  // produces routes through here, errors included, so this covers messages as
+  // well as values. It does NOT cover the Windows shim's own COM failures
+  // (windows-runner.ts echoes Err.Description straight to stdout), nor raw
+  // non-ASCII sitting in a snippet's own source text — that arrives by a
+  // different path and is not addressed here.
   function __mcpJsonEncode(v, __depth) {
     if (__depth === undefined) __depth = 0;
     if (__depth > 32) return '"<<truncated:max-depth>>"';
@@ -72,7 +87,7 @@ class ExtendScriptPhotoshopAPI {
         else if (c === '\\t') s += '\\\\t';
         else if (c === '\\b') s += '\\\\b';
         else if (c === '\\f') s += '\\\\f';
-        else if (cc < 32) {
+        else if (cc < 32 || cc > 126) {
           var hex = cc.toString(16);
           while (hex.length < 4) hex = '0' + hex;
           s += '\\\\u' + hex;

package/dist/cli/activate.js

@@ -33,7 +33,7 @@ export async function runActivate(opts = {}) {
     catch (e) {
         if (e instanceof PolarLicenseError) {
             err(`Activation failed: ${e.message}\n`);
-            throw new Error(e.code);
+            throw new Error(e.code, { cause: e });
         }
         throw e;
     }

package/dist/cli/config.js

@@ -98,7 +98,7 @@ export function runConfig(args, io = {}) {
         }
         catch (e) {
             err(`Invalid value for ${key}: ${e instanceof Error ? e.message : String(e)}\n`);
-            throw new Error('config set: bad value');
+            throw new Error('config set: bad value', { cause: e });
         }
         const { settings } = loadSettings(io);
         spec.set(settings, coerced);

package/dist/cli/deactivate.js

@@ -12,7 +12,7 @@ export async function runDeactivate(opts = {}) {
     catch (e) {
         if (e instanceof PolarLicenseError) {
             err(`Deactivate failed: ${e.message}\n`);
-            throw new Error(e.code);
+            throw new Error(e.code, { cause: e });
         }
         throw e;
     }

package/dist/core/raw-develop-state.js

@@ -0,0 +1,13 @@
+let pending = null;
+export function markRawOpened(documentName, filePath) {
+    pending = { documentName, filePath };
+}
+export function clearPendingRawDevelop() {
+    pending = null;
+}
+export function getPendingRawDevelop() {
+    return pending;
+}
+export function __clearRawDevelopState() {
+    pending = null;
+}

package/dist/core/server.js

@@ -13,6 +13,7 @@ import { loadSettings, applyTelemetryEnvOverrides, applyUpdateCheckEnvOverride,
 import { TelemetryClient } from '../telemetry/client.js';
 import { resolveInstallChannel } from '../install-channel.js';
 import { checkForUpdate, shouldCheckForUpdate } from '../update/check.js';
+import { previousSessionFailureCounts, relevantFixes } from '../update/session-fixes.js';
 import { join } from 'node:path';
 import { GoSnippetClient, coreBinaryName } from '../api/snippet-client.js';
 import { isProEntitled } from '../license/entitlement.js';
@@ -21,6 +22,7 @@ import { runScript } from '../utils/run-script.js';
 import { listTemplates } from '../utils/template-storage.js';
 import { toolErrorResult } from '../utils/tool-helpers.js';
 import { Kernel } from '../kernel/kernel.js';
+import { markRawOpened, clearPendingRawDevelop } from './raw-develop-state.js';
 import { ceModule } from '../modules/ce/index.js';
 import { hostDetectionRuntime } from '../detection/runtime.js';
 import { ModuleLifecycle, classifyModuleOutcome } from '../kernel/module-lifecycle.js';
@@ -45,6 +47,7 @@ const FIRST_RUN_DISCLOSURE = 'First run: Editmamei collects anonymous, content-f
     'It never sends image content, file paths, or personal data. 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`.';
+export const BACKGROUND_VERSION_PROBE_TIMEOUT_MS = 3_000;
 export class EditmameiServer {
     server;
     logger;
@@ -58,7 +61,11 @@ export class EditmameiServer {
         return this.moduleLifecycle.moduleSkipReason;
     }
     psVersion = null;
+    lastPingReachedPs = null;
+    liveVersionResolutionAttempted = false;
     updateInfo = null;
+    updateCheck = null;
+    updateNoticeShown = false;
     snippetClient = new GoSnippetClient();
     refreshLicenseOnPing = createPingLicenseRefresher();
     constructor() {
@@ -78,13 +85,18 @@ export class EditmameiServer {
         if (created)
             this.logger.info(FIRST_RUN_DISCLOSURE);
         if (shouldCheckForUpdate(effectiveSettings.update_check)) {
-            void checkForUpdate().then((info) => {
+            this.updateCheck = checkForUpdate().then((info) => {
                 this.updateInfo = info;
             });
         }
         warnLogScriptOnErrorOnce(this.logger);
         this.toolRegistry = new ToolRegistry({
             onCall: (entry) => {
+                if (entry.success && entry.tool !== 'ps_ping' && this.psVersion === null) {
+                    if (this.session.getConnection().hasReachedPhotoshop()) {
+                        this.resolveLiveVersionInBackground();
+                    }
+                }
                 void this.sessionLog.append({
                     tool: entry.tool,
                     args: entry.args,
@@ -92,18 +104,24 @@ export class EditmameiServer {
                     duration_ms: entry.duration_ms,
                     ...(entry.error ? { error: entry.error } : {}),
                 }, entry.result);
-                const errorClass = classifyError(entry.error);
+                const telemetrySuccess = entry.tool === 'ps_ping' && this.lastPingReachedPs === false ? false : entry.success;
+                const isPingDowngrade = entry.tool === 'ps_ping' && !telemetrySuccess && entry.error === undefined;
+                const errorClass = classifyError(entry.error) ??
+                    (telemetrySuccess ? null : isPingDowngrade ? 'ps_not_running' : 'other');
                 this.telemetry.recordCall({
                     tool: entry.tool,
-                    success: entry.success,
+                    success: telemetrySuccess,
                     duration_ms: entry.duration_ms,
                     error_class: errorClass,
                 });
-                if (!entry.success && entry.error) {
+                if (!telemetrySuccess) {
                     this.telemetry.recordDiagnostic({
                         tool: entry.tool,
                         error_class: errorClass ?? 'other',
-                        error_message: entry.error,
+                        error_message: entry.error ||
+                            (isPingDowngrade
+                                ? 'ps_ping did not reach Photoshop'
+                                : 'tool reported failure with no message'),
                     });
                 }
             },
@@ -145,14 +163,19 @@ export class EditmameiServer {
                         },
                         update_available: {
                             type: ['object', 'null'],
-                            description: 'Set when a newer Editmamei version is published, else null. When present, TELL THE USER: relay current → latest and how_to_update verbatim. { current, latest, channel (npm/mcpb/dev), how_to_update }. Anonymous npm-registry check at boot; opt out with `editmamei config set update_check false`.',
+                            description: 'Set when a newer Editmamei version is published, else null: { current, latest, channel (npm/mcpb/dev), how_to_update, fixed_tools (tools whose recorded failures the newer version fixes) }. The relay instruction rides the ping TEXT on the first ping — see notify_user. Anonymous npm-registry check at boot; opt out with `editmamei config set update_check false`.',
                             properties: {
                                 current: { type: 'string' },
                                 latest: { type: 'string' },
                                 channel: { type: 'string' },
                                 how_to_update: { type: 'string' },
+                                fixed_tools: { type: 'array', items: { type: 'string' } },
                             },
                         },
+                        notify_user: {
+                            type: 'boolean',
+                            description: 'True on the one ping whose text carries the update notice — relay that notice to the user before continuing. False on later pings and when no update is available.',
+                        },
                     },
                 },
                 annotations: {
@@ -284,6 +307,7 @@ export class EditmameiServer {
         try {
             const result = await this.toolRegistry.execute(name, args);
             this.session.updateActivity();
+            this.trackRawDevelopState(name, result);
             return result;
         }
         catch (error) {
@@ -291,13 +315,59 @@ export class EditmameiServer {
             return toolErrorResult('Error', error);
         }
     }
+    trackRawDevelopState(name, result) {
+        if (result.isError)
+            return;
+        if (name === 'ps_open_document') {
+            const sc = result.structuredContent;
+            if (sc?.is_raw_source === true && this.toolRegistry.get('ps_apply_camera_raw')) {
+                const opened = sc;
+                markRawOpened(String(opened.document_name ?? ''), String(opened.file_path ?? ''));
+            }
+            else {
+                clearPendingRawDevelop();
+            }
+        }
+        else if (name === 'ps_apply_camera_raw' || name === 'ps_close_document') {
+            clearPendingRawDevelop();
+        }
+    }
+    resolveLiveVersionInBackground() {
+        if (this.liveVersionResolutionAttempted || this.psVersion !== null)
+            return;
+        void (async () => {
+            try {
+                const connection = this.session.getConnection();
+                const snippet = await this.snippetClient.build('pingState');
+                if (!(await connection.isCurrentlyRunning()))
+                    return;
+                if (this.liveVersionResolutionAttempted || this.psVersion !== null)
+                    return;
+                this.liveVersionResolutionAttempted = true;
+                const state = (await runScript(connection, snippet, BACKGROUND_VERSION_PROBE_TIMEOUT_MS));
+                if (state.version && state.version !== 'Unknown' && this.psVersion === null) {
+                    this.psVersion = state.version;
+                    void this.sessionLog.setPsVersion(state.version);
+                    this.telemetry.onPsVersionResolved();
+                }
+            }
+            catch (err) {
+                this.logger.debug(`background ps_version resolution failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        })();
+    }
     async pingPhotoshop() {
+        this.lastPingReachedPs = null;
         this.refreshLicenseOnPing();
+        if (this.updateCheck)
+            await this.updateCheck;
+        const update = await this.buildUpdateNotice();
         const connection = this.session.getConnection();
         let version = 'Unknown';
         let actionSetsCount = 0;
         let openDocuments = [];
         const degraded = [];
+        let versionIsLive = false;
         try {
             const detected = await connection.getVersion();
             if (detected)
@@ -305,6 +375,23 @@ export class EditmameiServer {
         }
         catch {
         }
+        if (connection.getPhotoshopInfo() !== null && !(await connection.isCurrentlyRunning())) {
+            this.lastPingReachedPs = false;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Photoshop does not appear to be running. Start Photoshop, then call ps_ping again.' +
+                            update.note,
+                    },
+                ],
+                structuredContent: {
+                    connected: false,
+                    update_available: this.updateInfo,
+                    notify_user: update.notify,
+                },
+            };
+        }
         let pingStateSnippet = null;
         try {
             pingStateSnippet = await this.snippetClient.build('pingState');
@@ -314,14 +401,19 @@ export class EditmameiServer {
             const alive = await connection.ping().catch(() => false);
             if (!alive) {
                 const reason = unsupportedHostReason();
+                this.lastPingReachedPs = false;
                 return {
                     content: [
                         {
                             type: 'text',
-                            text: (reason ?? 'Photoshop did not respond') + this.updateNote(),
+                            text: (reason ?? 'Photoshop did not respond') + update.note,
                         },
                     ],
-                    structuredContent: { connected: false, update_available: this.updateInfo },
+                    structuredContent: {
+                        connected: false,
+                        update_available: this.updateInfo,
+                        notify_user: update.notify,
+                    },
                 };
             }
             degraded.push('pingState');
@@ -333,15 +425,20 @@ export class EditmameiServer {
             }
             catch (err) {
                 this.logger.warn(`pingState snippet failed: ${err instanceof Error ? err.message : String(err)}`);
+                this.lastPingReachedPs = false;
                 return {
-                    content: [
-                        { type: 'text', text: 'Photoshop did not respond' + this.updateNote() },
-                    ],
-                    structuredContent: { connected: false, update_available: this.updateInfo },
+                    content: [{ type: 'text', text: 'Photoshop did not respond' + update.note }],
+                    structuredContent: {
+                        connected: false,
+                        update_available: this.updateInfo,
+                        notify_user: update.notify,
+                    },
                 };
             }
-            if (state.version)
+            if (state.version) {
                 version = state.version;
+                versionIsLive = true;
+            }
             if (typeof state.action_sets_count === 'number')
                 actionSetsCount = state.action_sets_count;
             if (Array.isArray(state.open_documents))
@@ -357,10 +454,13 @@ export class EditmameiServer {
             degraded.push('templates');
         }
         if (version !== 'Unknown') {
-            this.psVersion = version;
             void this.sessionLog.setPsVersion(version);
+        }
+        if (versionIsLive && version !== 'Unknown') {
+            this.psVersion = version;
             this.telemetry.onPsVersionResolved();
         }
+        this.lastPingReachedPs = true;
         const degradedNote = degraded.length ? ` (degraded: ${degraded.join(', ')})` : '';
         return {
             content: [
@@ -370,7 +470,7 @@ export class EditmameiServer {
                         `${actionSetsCount} custom action set(s), ${userTemplates} saved template(s), ` +
                         `${openDocuments.length} open document(s)${openDocuments.length ? ': ' + openDocuments.join(', ') : ''}` +
                         `${degradedNote}.` +
-                        this.updateNote(),
+                        update.note,
                 },
             ],
             structuredContent: {
@@ -381,14 +481,43 @@ export class EditmameiServer {
                 open_documents: openDocuments,
                 degraded,
                 update_available: this.updateInfo,
+                notify_user: update.notify,
             },
         };
     }
-    updateNote() {
+    async buildUpdateNotice() {
         const u = this.updateInfo;
         if (!u)
-            return '';
-        return ` Update available: v${u.current} → v${u.latest}. ${u.how_to_update}`;
+            return { note: '', notify: false };
+        if (this.updateNoticeShown) {
+            return {
+                note: ` Update available: v${u.current} → v${u.latest}. ${u.how_to_update}`,
+                notify: false,
+            };
+        }
+        this.updateNoticeShown = true;
+        let fixNote = '';
+        if (u.fixed_tools.length > 0) {
+            try {
+                const counts = await previousSessionFailureCounts(this.session.getSessionId(), {
+                    dir: this.sessionLog.directory,
+                });
+                const hits = relevantFixes(counts, u.fixed_tools);
+                if (hits.length > 0) {
+                    const named = hits
+                        .map((h) => `${h.tool} (failed ${h.failures} time${h.failures === 1 ? '' : 's'} last session)`)
+                        .join(', ');
+                    fixNote = ` v${u.latest} fixes known failures in ${named}.`;
+                }
+            }
+            catch {
+            }
+        }
+        return {
+            note: ` IMPORTANT — tell the user before continuing: Editmamei v${u.latest} is available` +
+                ` (this install runs v${u.current}).${fixNote} To update: ${u.how_to_update}`,
+            notify: true,
+        };
     }
     async start() {
         await this.loadModules();

package/dist/core/tool-groups.js

@@ -7,12 +7,12 @@ export const GROUPS = {
     inspect: {
         id: 'inspect',
         label: 'Inspect',
-        purpose: 'Read document/layer/selection/history state and render previews.',
+        purpose: 'Read document/layer/selection/history/smart-object state and render previews.',
     },
     verify: {
         id: 'verify',
         label: 'Verify',
-        purpose: 'Measurement primitives — histogram, region compare, bounds diff — to check work instead of eyeballing.',
+        purpose: 'Measurement primitives — histogram, region compare, bounds diff, selection preview — to check work instead of eyeballing.',
     },
     document: {
         id: 'document',
@@ -22,12 +22,12 @@ export const GROUPS = {
     select: {
         id: 'select',
         label: 'Selection',
-        purpose: 'Manual selections, selection edits, and alpha-channel save/load.',
+        purpose: 'Manual selections, selection edits, and alpha-channel save/load/duplicate/delete.',
     },
     select_ai: {
         id: 'select_ai',
         label: 'AI selection',
-        purpose: 'Sensei/CV-backed subject & sky selection (Pro).',
+        purpose: 'Sensei/CV-backed selection: select_subject and select_sky (community), plus subject-instance selection and named-object selection (Pro).',
     },
     adjust: {
         id: 'adjust',
@@ -37,12 +37,12 @@ export const GROUPS = {
     filter: {
         id: 'filter',
         label: 'Filters',
-        purpose: 'Blur/sharpen/noise/stylize filters (auto-duplicate-first by default).',
+        purpose: 'Blur/sharpen/noise/stylize filters (auto-duplicate-first by default) and the Camera Raw develop surface, plus managing the re-editable Smart Filter stack on a Smart Object.',
     },
     retouch: {
         id: 'retouch',
         label: 'Retouch',
-        purpose: 'Content-aware fill/patch/move and brush strokes.',
+        purpose: 'Content-aware fill, patch, and move.',
     },
     layers: {
         id: 'layers',
@@ -52,7 +52,7 @@ export const GROUPS = {
     masks: {
         id: 'masks',
         label: 'Masks & paths',
-        purpose: 'Layer masks, clipping masks, vector masks, and work paths.',
+        purpose: 'Layer masks, clipping masks, vector masks, work paths, and channel compositing (apply image / calculations).',
     },
     type: {
         id: 'type',
@@ -66,8 +66,8 @@ export const GROUPS = {
     },
     face: {
         id: 'face',
-        label: 'Face mesh (Pro)',
-        purpose: 'Face-landmark perception and mesh-aimed feature selection / contour strokes (Pro).',
+        label: 'Face mesh',
+        purpose: 'Face-landmark perception and mesh-aimed feature selection / contour strokes. Pro in shipped builds.',
     },
     templates: {
         id: 'templates',
@@ -77,7 +77,7 @@ export const GROUPS = {
     automation: {
         id: 'automation',
         label: 'Automation (Pro)',
-        purpose: 'Play recorded Actions and the ExtendScript escape hatch (Pro).',
+        purpose: 'Batch files, play recorded Actions, and the ExtendScript escape hatch (Pro).',
     },
 };
 export const TOOL_GROUPS = {
@@ -111,9 +111,11 @@ export const TOOL_GROUPS = {
     ps_select_sky: 'select_ai',
     ps_select_subject_instance: 'select_ai',
     ps_select_object: 'select_ai',
+    ps_select_focus_area: 'select_ai',
+    ps_replace_sky: 'select_ai',
     ps_add_adjustment_layer: 'adjust',
     ps_apply_adjustment: 'adjust',
-    ps_apply_filter: 'filter',
+    ps_filter: 'filter',
     ps_apply_camera_raw: 'filter',
     ps_retouch: 'retouch',
     ps_apply_brush_stroke: 'retouch',
@@ -137,21 +139,15 @@ export const TOOL_GROUPS = {
     ps_warp_layer_along: 'layers',
     ps_warp_layer_region: 'layers',
     ps_warp_layer_to: 'layers',
-    ps_create_group: 'layers',
-    ps_move_layer_to_group: 'layers',
-    ps_set_group_blend_mode: 'layers',
-    ps_ungroup: 'layers',
-    ps_delete_group: 'layers',
+    ps_group: 'layers',
+    ps_shape: 'layers',
     ps_layer_mask: 'masks',
-    ps_create_clipping_mask: 'masks',
-    ps_release_clipping_mask: 'masks',
+    ps_clipping_mask: 'masks',
     ps_path: 'masks',
     ps_vector_mask: 'masks',
     ps_apply_image: 'masks',
     ps_calculations: 'masks',
-    ps_shape: 'layers',
-    ps_create_text_layer: 'type',
-    ps_set_text: 'type',
+    ps_text: 'type',
     ps_detect: 'perception',
     ps_read_scene: 'perception',
     ps_select_by_reference: 'perception',
@@ -172,6 +168,7 @@ export const TOOL_GROUPS = {
     ps_list_actions: 'automation',
     ps_play_action: 'automation',
     ps_execute_script: 'automation',
+    ps_batch: 'automation',
 };
 export function groupOf(toolName) {
     const group = TOOL_GROUPS[toolName];