editmamei 1.1.0 → 1.2.1

package/README.md

@@ -75,7 +75,7 @@ These are the choices that shape the surface, and the reason an AI assistant can
 
 ## Tool surface
 
-**82 tools across 16 capability groups** (59 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. `tools/list` reports eight more than the table below: the names superseded by `filter`, `group`, and `text` (`apply_filter`, `create_group`, `move_layer_to_group`, `set_group_blend_mode`, `ungroup`, `delete_group`, `create_text_layer`, `set_text`) stay registered as deprecated aliases for one release, so existing calls keep working.
+**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 |
 | --- | --- | --- |
@@ -94,11 +94,11 @@ These are the choices that shape the surface, and the reason an AI assistant can
 | **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
 

package/dist/api/extendscript/_helpers.js

@@ -27,12 +27,13 @@ function __notFoundMessage(label, requested, groupsOnly) {
     var out = '';
     for (var c = 0; c < s.length; c++) {
       var code = s.charCodeAt(c);
-      if (code >= 32 && code <= 126 && code !== 92) {
-        out += s.charAt(c);
-      } else {
+      // 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;
@@ -47,6 +48,11 @@ function __notFoundMessage(label, requested, groupsOnly) {
       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);

package/dist/api/photoshop-api.js

@@ -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/help.js

@@ -48,5 +48,6 @@ Per-user data and session logs live in ~/.editmamei/; uninstall preserves them.
 
 Docs: https://editmamei.com/docs
 Issues: https://github.com/editmamei/editmamei/issues
+Release notes by email: https://editmamei.com/blog?src=cli
 `);
 }

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';
@@ -63,6 +64,8 @@ export class EditmameiServer {
     lastPingReachedPs = null;
     liveVersionResolutionAttempted = false;
     updateInfo = null;
+    updateCheck = null;
+    updateNoticeShown = false;
     snippetClient = new GoSnippetClient();
     refreshLicenseOnPing = createPingLicenseRefresher();
     constructor() {
@@ -82,7 +85,7 @@ 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;
             });
         }
@@ -102,18 +105,23 @@ export class EditmameiServer {
                     ...(entry.error ? { error: entry.error } : {}),
                 }, entry.result);
                 const telemetrySuccess = entry.tool === 'ps_ping' && this.lastPingReachedPs === false ? false : entry.success;
-                const errorClass = classifyError(entry.error);
+                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: 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'),
                     });
                 }
             },
@@ -155,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: {
@@ -209,6 +222,7 @@ export class EditmameiServer {
             toolRegistry: this.toolRegistry,
             logger: this.logger,
             assertToolsClassified: () => this.assertToolsClassified(),
+            classifyTool: (name) => this.classifyTool(name),
         });
         const proModule = this.moduleLifecycle.resolveProModule();
         this.kernel = new Kernel({
@@ -239,10 +253,13 @@ export class EditmameiServer {
     async ensureEntitledModuleFresh(delivery = {}) {
         return this.moduleLifecycle.ensureEntitledModuleFresh(delivery);
     }
+    classifyTool(name) {
+        tierOf(name);
+        groupOf(name);
+    }
     assertToolsClassified() {
         for (const tool of this.toolRegistry.list()) {
-            tierOf(tool.name);
-            groupOf(tool.name);
+            this.classifyTool(tool.name);
         }
     }
     listCapabilities() {
@@ -346,6 +363,9 @@ export class EditmameiServer {
     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;
@@ -359,6 +379,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');
@@ -373,10 +410,14 @@ export class EditmameiServer {
                     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');
@@ -390,10 +431,12 @@ export class EditmameiServer {
                 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) {
@@ -431,7 +474,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: {
@@ -442,14 +485,45 @@ 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}` +
+                ` Not urgent: they can also read and subscribe to release notes at` +
+                ` https://editmamei.com/blog?src=update_notice`,
+            notify: true,
+        };
     }
     async start() {
         await this.loadModules();

package/dist/core/tool-groups.js

@@ -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 = {
@@ -93,6 +93,7 @@ export const TOOL_GROUPS = {
     ps_compare_regions: 'verify',
     ps_get_layer_bounds_diff: 'verify',
     ps_get_selection_preview: 'verify',
+    ps_document: 'document',
     ps_create_document: 'document',
     ps_open_document: 'document',
     ps_close_document: 'document',
@@ -111,10 +112,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_filter: 'filter',
-    ps_apply_filter: 'filter',
     ps_apply_camera_raw: 'filter',
     ps_retouch: 'retouch',
     ps_apply_brush_stroke: 'retouch',
@@ -139,11 +141,6 @@ export const TOOL_GROUPS = {
     ps_warp_layer_region: 'layers',
     ps_warp_layer_to: 'layers',
     ps_group: '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_shape: 'layers',
     ps_layer_mask: 'masks',
     ps_clipping_mask: 'masks',
@@ -152,8 +149,6 @@ export const TOOL_GROUPS = {
     ps_apply_image: 'masks',
     ps_calculations: 'masks',
     ps_text: 'type',
-    ps_create_text_layer: 'type',
-    ps_set_text: 'type',
     ps_detect: 'perception',
     ps_read_scene: 'perception',
     ps_select_by_reference: 'perception',
@@ -174,6 +169,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];

package/dist/core/tool-registry.js

@@ -26,6 +26,9 @@ export class ToolRegistry {
     restore(snap) {
         this.tools = new Map(snap);
     }
+    unregister(name) {
+        this.tools.delete(name);
+    }
     get(name) {
         return this.tools.get(name);
     }

package/dist/core/tool-tiers.js

@@ -5,21 +5,17 @@ export const TOOL_TIERS = {
     ps_list_actions: 'pro',
     ps_play_action: 'pro',
     ps_execute_script: 'pro',
+    ps_batch: 'pro',
     ps_add_adjustment_layer: 'community',
     ps_apply_adjustment: 'community',
+    ps_document: 'dev',
     ps_create_document: 'community',
     ps_close_document: 'community',
     ps_open_document: 'community',
     ps_save_psd: 'community',
     ps_export: 'community',
     ps_filter: 'community',
-    ps_apply_filter: 'community',
     ps_group: 'community',
-    ps_create_group: 'community',
-    ps_move_layer_to_group: 'community',
-    ps_set_group_blend_mode: 'community',
-    ps_ungroup: 'community',
-    ps_delete_group: 'community',
     ps_clipping_mask: 'community',
     ps_undo: 'community',
     ps_redo: 'community',
@@ -38,7 +34,6 @@ export const TOOL_TIERS = {
     ps_add_layer_style: 'community',
     ps_create_layer: 'community',
     ps_delete_layer: 'community',
-    ps_create_text_layer: 'community',
     ps_fill_layer: 'community',
     ps_add_fill_layer: 'community',
     ps_select_layer: 'community',
@@ -73,6 +68,8 @@ export const TOOL_TIERS = {
     ps_select_sky: 'community',
     ps_select_subject_instance: 'pro',
     ps_select_object: 'pro',
+    ps_select_focus_area: 'dev',
+    ps_replace_sky: 'dev',
     ps_modify_selection: 'community',
     ps_get_selection_preview: 'community',
     ps_selection_channel: 'community',
@@ -91,7 +88,6 @@ export const TOOL_TIERS = {
     ps_template_recall: 'pro',
     ps_template_delete: 'pro',
     ps_text: 'community',
-    ps_set_text: 'community',
 };
 export function tierOf(toolName) {
     const tier = TOOL_TIERS[toolName];

package/dist/delivery/provision.js

@@ -5,7 +5,7 @@ import { installModule, readInstalledModule } from './store.js';
 import { Logger } from '../utils/logger.js';
 const logger = new Logger('Modules');
 const SKU_RE = /^[a-z0-9-]{2,32}$/;
-const VERSION_RE = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/;
+export const VERSION_RE = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/;
 const MAX_ARTIFACT_BYTES = 64 * 1024 * 1024;
 export async function provisionModules(key, opts = {}) {
     const result = {
@@ -137,7 +137,7 @@ export async function provisionModules(key, opts = {}) {
 function errMsg(e) {
     return e instanceof Error ? e.message : String(e);
 }
-function compareVersions(a, b) {
+export function compareVersions(a, b) {
     const [aCore, aPre] = a.split('-', 2);
     const [bCore, bPre] = b.split('-', 2);
     const ap = aCore.split('.').map(Number);

package/dist/kernel/module-lifecycle.js

@@ -5,9 +5,10 @@ import { EDITION } from '../edition.js';
 import { resolveProBinaryPath } from '../api/snippet-client.js';
 import { isProEntitled } from '../license/entitlement.js';
 import { loadVerifiedModule, readInstalledModule, installedPath, PRO_SKU, } from '../delivery/store.js';
-import { provisionModules } from '../delivery/provision.js';
+import { provisionModules, compareVersions, VERSION_RE, } from '../delivery/provision.js';
 import { readLicense } from '../license/store.js';
 import { HOST_MIN_ABI } from './host-api.js';
+import { VERSION } from '../version.js';
 export function classifyModuleOutcome(inputs) {
     if (inputs.proModuleLoaded && inputs.skipReason === null)
         return 'loaded';
@@ -38,11 +39,12 @@ export class ModuleLifecycle {
         if (isProEntitled()) {
             const verified = loadVerifiedModule(PRO_SKU);
             if (verified) {
-                const abi = readInstalledModule(PRO_SKU)?.abi ?? null;
+                const installed = readInstalledModule(PRO_SKU);
                 this._proModule = {
                     importer: () => import(pathToFileURL(verified.handlersPath).href),
                     binDir: verified.binDir,
-                    abi,
+                    abi: installed?.abi ?? null,
+                    version: installed?.version ?? null,
                 };
                 return this._proModule;
             }
@@ -61,6 +63,7 @@ export class ModuleLifecycle {
                 importer: () => import(inTreeProSpecifier),
                 binDir: dirname(resolveProBinaryPath()),
                 abi: null,
+                version: null,
             };
             return this._proModule;
         }
@@ -79,10 +82,33 @@ export class ModuleLifecycle {
         const snapshot = this.deps.toolRegistry.snapshot();
         try {
             await this.kernel.loadDownloaded(this._proModule.importer);
+            if (this._proModule.version !== null &&
+                VERSION_RE.test(this._proModule.version) &&
+                compareVersions(this._proModule.version, VERSION) > 0) {
+                const added = this.deps.toolRegistry
+                    .list()
+                    .map((tool) => tool.name)
+                    .filter((name) => !snapshot.has(name));
+                for (const name of added) {
+                    try {
+                        this.deps.classifyTool(name);
+                    }
+                    catch {
+                        this.deps.toolRegistry.unregister(name);
+                        this.deps.logger.warn(`Module tool '${name}' is not recognized by this host — skipping it; the ` +
+                            `rest of the module is loaded. Update Editmamei to use it.`);
+                    }
+                }
+            }
             this.deps.assertToolsClassified();
         }
         catch (err) {
-            const changed = this.deps.toolRegistry.count() - snapshot.size;
+            let changed = 0;
+            for (const tool of this.deps.toolRegistry.list()) {
+                const prior = snapshot.get(tool.name);
+                if (!prior || this.deps.toolRegistry.get(tool.name) !== prior)
+                    changed++;
+            }
             this.deps.toolRegistry.restore(snapshot);
             this.deps.logger.warn(`Pro module could not be loaded on this host — booting Community and rolling back ` +
                 `${changed} module tool change(s); will re-provision in the background: ` +

package/dist/modules/ce/index.js

@@ -29,6 +29,7 @@ import { createPathTools } from '../../tools/path-tools.js';
 import { createVectorMaskTools } from '../../tools/vector-mask-tools.js';
 import { createChannelComposeTools } from '../../tools/channel-compose-tools.js';
 import { createShapeTools } from '../../tools/shape-tools.js';
+import { createSkyTools } from '../../tools/sky-tools.js';
 const ceFactories = [
     createDocumentTools,
     createLayerTools,
@@ -57,6 +58,7 @@ const ceFactories = [
     createVectorMaskTools,
     createChannelComposeTools,
     createShapeTools,
+    createSkyTools,
 ];
 export const ceModule = {
     manifest: { id: 'ce', name: 'Editmamei Community Tools', abi: KERNEL_ABI },

package/dist/perception/region-precompute.js

@@ -10,11 +10,24 @@ let cachedMenu = [];
 export function __resetPrecompute() {
     lastPrecomputedKey = null;
     cachedMenu = [];
+    channelsDocState = null;
 }
 export const CHANNEL_PREFIX = 'scene:';
 export async function saveSelectionAsSceneChannel(connection, target) {
     await runScript(connection, saveSelectionToNamedChannelScript(`${CHANNEL_PREFIX}${target}`), SCENE_CHANNEL_TIMEOUT_MS);
 }
+let channelsDocState = null;
+export async function invalidateSceneChannelsIfStale(connection, cacheKey) {
+    if (channelsDocState === cacheKey)
+        return;
+    try {
+        await runScript(connection, deleteSceneChannelsScript(), SCENE_CHANNEL_TIMEOUT_MS);
+        channelsDocState = cacheKey;
+    }
+    catch {
+        channelsDocState = null;
+    }
+}
 const PRECOMPUTE_TARGETS = [
     'sky',
     'ground',
@@ -24,6 +37,31 @@ const PRECOMPUTE_TARGETS = [
     'subject',
     'face',
 ];
+export function candidateMenu(model) {
+    const advertise = (target) => ({
+        key: `${CHANNEL_PREFIX}${target}`,
+        target,
+        method: 'on_demand',
+        bounds: null,
+        on_demand: true,
+    });
+    const hasFace = model.faces.length > 0;
+    const hasSubject = model.subjects.length > 0;
+    const hasPerson = model.subjects.some((s) => s.label === 'person');
+    const menu = [
+        advertise('sky'),
+        advertise('ground'),
+        advertise('shadows'),
+        advertise('highlights'),
+    ];
+    if (hasPerson || hasFace)
+        menu.push(advertise('skin'));
+    if (hasSubject)
+        menu.push(advertise('subject'));
+    if (hasFace)
+        menu.push(advertise('face'));
+    return menu;
+}
 function deleteSceneChannelsScript() {
     return `
     if (app.documents.length === 0) { throw new Error('No document is open in Photoshop'); }
@@ -145,6 +183,7 @@ export async function precomputeRegions(connection, snippet, model, composition,
     const tally = { scripts: 0 };
     const countedConnection = countingConnection(connection, tally);
     await runScript(countedConnection, deleteSceneChannelsScript(), SCENE_CHANNEL_TIMEOUT_MS);
+    channelsDocState = model.provenance.cache_key;
     const menu = [];
     for (const target of PRECOMPUTE_TARGETS) {
         try {