editmamei 1.2.0 → 1.3.0

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/cli/repair.js

@@ -26,11 +26,19 @@ export async function runRepair(opts = {}) {
         out(`  Installed ${m.sku} module v${m.version}.\n`);
     for (const s of prov.skipped)
         out(`  Skipped ${s.sku} v${s.version}: ${s.reason}.\n`);
-    for (const e of prov.errors) {
+    const tooNew = prov.errors.filter((e) => e.code === 'abi_too_new');
+    const failures = prov.errors.filter((e) => e.code !== 'abi_too_new');
+    for (const e of tooNew) {
+        out(`  The published ${e.sku} module needs a newer Editmamei than this one — ` +
+            `update Editmamei to load it. Your installed module is unchanged.\n`);
+    }
+    for (const e of failures) {
         err(`  Error: could not provision the ${e.sku} module: ${e.message}\n`);
     }
-    if (prov.errors.length > 0) {
+    if (failures.length > 0) {
         throw new Error('module re-provisioning failed');
     }
-    out('\nRestart your MCP client (Claude Desktop / Claude Code) to load Pro tools.\n');
+    if (prov.installed.length > 0 || tooNew.length === 0) {
+        out('\nRestart your MCP client (Claude Desktop / Claude Code) to load Pro tools.\n');
+    }
 }

package/dist/core/server.js

@@ -222,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({
@@ -252,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() {
@@ -515,7 +519,9 @@ export class EditmameiServer {
         }
         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}`,
+                ` (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,
         };
     }

package/dist/core/tool-groups.js

@@ -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',

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

@@ -8,6 +8,7 @@ export const TOOL_TIERS = {
     ps_batch: 'pro',
     ps_add_adjustment_layer: 'community',
     ps_apply_adjustment: 'community',
+    ps_document: 'community',
     ps_create_document: 'community',
     ps_close_document: 'community',
     ps_open_document: 'community',
@@ -68,7 +69,7 @@ export const TOOL_TIERS = {
     ps_select_subject_instance: 'pro',
     ps_select_object: 'pro',
     ps_select_focus_area: 'dev',
-    ps_replace_sky: 'dev',
+    ps_replace_sky: 'community',
     ps_modify_selection: 'community',
     ps_get_selection_preview: 'community',
     ps_selection_channel: 'community',

package/dist/delivery/provision.js

@@ -2,10 +2,11 @@ import { DeliveryClient, DeliveryError } from './client.js';
 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 { 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 = {
@@ -52,6 +53,23 @@ export async function provisionModules(key, opts = {}) {
                 });
                 continue;
             }
+            const abi = entry.abi;
+            if (!Number.isInteger(abi) || abi < 1) {
+                result.errors.push({
+                    sku,
+                    code: 'abi_invalid',
+                    message: `the manifest entry for ${sku} declares an invalid abi '${String(abi)}' (expected a whole number of at least 1) — refusing to install it`,
+                });
+                continue;
+            }
+            if (abi > KERNEL_ABI) {
+                result.errors.push({
+                    sku,
+                    code: 'abi_too_new',
+                    message: `the published ${sku} module needs a newer Editmamei than this one (module abi ${abi}, this host runs up to abi ${KERNEL_ABI}) — update Editmamei; the installed module is left as it is`,
+                });
+                continue;
+            }
             const installed = readInstalledModule(sku, opts);
             if (installed && installed.version === latest && !opts.force) {
                 result.skipped.push({ sku, version: latest, reason: 'up-to-date' });
@@ -119,7 +137,7 @@ export async function provisionModules(key, opts = {}) {
             installModule({
                 sku,
                 version: latest,
-                abi: entry.abi,
+                abi,
                 sha256: digest,
                 alg: contentKey.alg,
                 content_key: contentKey.key,
@@ -137,7 +155,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/kernel.js

@@ -73,9 +73,10 @@ export class Kernel {
             throw new Error('downloaded module export is not an EditmameiModule (expected a default export with a manifest + register())');
         }
         if (this.abiTooNew(mod.manifest))
-            return;
+            return 'abi-too-new';
         const before = this.registry.count();
         await mod.register(this.hostApiFor(mod.manifest));
         this.logger.info(`Loaded downloaded module '${mod.manifest.id}' (${mod.manifest.name}) — ${this.registry.count() - before} tools.`);
+        return 'loaded';
     }
 }

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 { HOST_MIN_ABI, KERNEL_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;
         }
@@ -76,13 +79,48 @@ export class ModuleLifecycle {
             this._moduleSkipReason = 'incompatible';
             return;
         }
+        if (this._proModule.abi !== null && this._proModule.abi > KERNEL_ABI) {
+            this.deps.logger.warn(`Pro module (abi ${this._proModule.abi}) needs a newer host than this build ` +
+                `(kernel abi ${KERNEL_ABI}) — booting Community; update Editmamei to load it.`);
+            this._moduleSkipReason = 'incompatible';
+            return;
+        }
         const snapshot = this.deps.toolRegistry.snapshot();
         try {
-            await this.kernel.loadDownloaded(this._proModule.importer);
+            const outcome = await this.kernel.loadDownloaded(this._proModule.importer);
+            if (outcome === 'abi-too-new') {
+                this.deps.logger.warn(`The installed Pro module needs a newer host than this build (kernel abi ` +
+                    `${KERNEL_ABI}) — booting Community; update Editmamei to load it.`);
+                this._moduleSkipReason = 'incompatible';
+                return;
+            }
+            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: ` +
@@ -133,11 +171,14 @@ export class ModuleLifecycle {
                 this.deps.logger.warn('Module delivery is not configured — staying Community.');
                 return;
             }
+            const abiTooNew = prov.errors.some((e) => e.code === 'abi_too_new');
             for (const e of prov.errors) {
+                if (e.code === 'abi_too_new')
+                    continue;
                 this.deps.logger.warn(`Could not re-provision the ${e.sku} module (staying Community): ${e.message}`);
             }
-            if (prov.errors.length === 0) {
-                if (reason === 'incompatible') {
+            if (prov.errors.length === 0 || abiTooNew) {
+                if (reason === 'incompatible' || abiTooNew) {
                     this.deps.logger.warn('The published Pro module does not yet support this host version — staying ' +
                         'Community. Update Editmamei when a compatible release ships; ' +
                         '`editmamei report` files a diagnostic.');
@@ -175,6 +216,11 @@ export class ModuleLifecycle {
                 this.deps.logger.info(`Pro module updated to v${m.version} — restart to load.`);
             }
             for (const e of prov.errors) {
+                if (e.code === 'abi_too_new') {
+                    this.deps.logger.info(`A newer Pro module is published but needs a newer Editmamei than this ` +
+                        `one — staying on the installed version, which works. Update Editmamei to get it.`);
+                    continue;
+                }
                 this.deps.logger.warn(`Pro-module freshness check could not provision the ${e.sku} module ` +
                     `(staying on the installed version): ${e.message}`);
             }

package/dist/modules/ce/index.js

@@ -30,7 +30,7 @@ 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 = [
+export const ceFactories = [
     createDocumentTools,
     createLayerTools,
     createGroupTools,

package/dist/perception/grounding-locate.js

@@ -254,17 +254,19 @@ export const PLACEMENT_SCHEMA = {
     type: 'object',
     description: 'ANCHOR-RELATIONAL placement (preferred over guessing pixels): name anchors + a relation and the ' +
         'spatial-grounding resolver computes the geometry, verified by an objective gate; the action runs ONLY if the ' +
-        'gate PASSES. For a HARD or ambiguous placement, first concur on ps_resolve_placement (review_crop: true) — a ' +
-        'read-only zoomed crop with a marker at the resolved spot — then pass the SAME anchors + relation here. See ' +
-        'ps_resolve_placement for the full anchors + relation vocabulary.',
+        'gate PASSES. For a HARD or ambiguous placement, first concur with the placement-resolver tool — when this ' +
+        'build has one, it appears in tools/list — by calling it with review_crop: true for a read-only zoomed crop ' +
+        'with a marker at the resolved spot, then pass the SAME anchors + relation here. The full anchors + relation ' +
+        'vocabulary is documented on that tool.',
     properties: {
         anchors: {
             type: 'array',
-            description: 'Named anchors, same vocabulary as ps_resolve_placement (face/object/grid/extremum/corner/edge/landmark).',
+            description: 'Named anchors, same vocabulary as the placement-resolver tool, when this build has one ' +
+                '(face/object/grid/extremum/corner/edge/landmark).',
         },
         relation: {
             type: 'object',
-            description: 'The relation, same vocabulary as ps_resolve_placement.',
+            description: 'The relation, same vocabulary as the placement-resolver tool, when this build has one.',
         },
         max_dimension: {
             type: 'number',

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 {

package/dist/tools/document-tools.js

@@ -36,6 +36,17 @@ const createDocumentSchema = {
     },
     required: ['width', 'height'],
 };
+const documentTargetProps = {
+    name: {
+        type: 'string',
+        description: "Target an open document by its exact Photoshop name, INCLUDING the extension as shown in the tab (e.g. 'portrait.jpg', not 'portrait'). If two open documents share a name the call fails rather than guessing — target by id instead.",
+    },
+    id: {
+        type: 'integer',
+        minimum: 1,
+        description: 'Target an open document by its Photoshop document id. Unambiguous — prefer this when names collide.',
+    },
+};
 const closeDocumentSchema = {
     type: 'object',
     properties: {
@@ -44,8 +55,22 @@ const closeDocumentSchema = {
             description: 'Whether to save changes before closing',
             default: false,
         },
+        ...documentTargetProps,
     },
 };
+const DOCUMENT_OPS = ['list', 'activate'];
+const documentSchema = {
+    type: 'object',
+    properties: {
+        op: {
+            type: 'string',
+            enum: [...DOCUMENT_OPS],
+            description: 'list: every open document (index, id, name, path, saved, active, dimensions) — safe to call when NOTHING is open, which is the point. activate: make one of them the active document, by name or id.',
+        },
+        ...documentTargetProps,
+    },
+    required: ['op'],
+};
 const openDocumentSchema = {
     type: 'object',
     properties: {
@@ -180,10 +205,56 @@ export function createDocumentTools(connection, snippetClient) {
             },
             handler: async (args) => createDocument(connection, snippetClient, args),
         },
+        {
+            tool: {
+                name: 'ps_document',
+                description: "See and steer WHICH documents are open, without touching their content. op=list answers 'what is open, which one is active, and does it have unsaved changes' — and it is the one document tool that works when nothing is open at all, so it is the recovery read after a 'No document is open' failure. op=activate switches the active document by name or id, which is how you fix having edited the wrong one. Read-only with respect to pixels; use ps_open_document to load a file and ps_close_document to close one.",
+                inputSchema: documentSchema,
+                outputSchema: {
+                    type: 'object',
+                    properties: {
+                        op: { type: 'string' },
+                        count: { type: 'number' },
+                        documents: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    index: { type: 'number' },
+                                    id: { type: 'number' },
+                                    name: { type: 'string' },
+                                    path: {
+                                        type: ['string', 'null'],
+                                        description: 'Absolute path, or null for a document never saved to disk.',
+                                    },
+                                    saved: {
+                                        type: ['boolean', 'null'],
+                                        description: 'False when the document has unsaved changes. Null when Photoshop would not report it.',
+                                    },
+                                    active: { type: 'boolean' },
+                                    width_px: { type: ['number', 'null'] },
+                                    height_px: { type: ['number', 'null'] },
+                                },
+                            },
+                        },
+                        activated: { type: 'boolean' },
+                        id: { type: 'number' },
+                        name: { type: 'string' },
+                        context: { type: 'object' },
+                    },
+                    required: ['op'],
+                },
+                annotations: {
+                    title: 'List / Activate Documents',
+                    idempotentHint: true,
+                },
+            },
+            handler: async (args) => documentOp(connection, snippetClient, args),
+        },
         {
             tool: {
                 name: 'ps_close_document',
-                description: 'Close the active Photoshop document. Destructive if save=false and the document has unsaved changes. Returns the closed document name plus a fresh context block (which document, if any, is active afterwards).',
+                description: 'Close a Photoshop document — the active one by default, or a specific one by name or id. Destructive if save=false and the document has unsaved changes. If two open documents share the requested name the call fails rather than guessing. Returns the closed document name plus a fresh context block (which document, if any, is active afterwards).',
                 inputSchema: closeDocumentSchema,
                 outputSchema: {
                     type: 'object',
@@ -340,11 +411,80 @@ async function createDocument(connection, snippetClient, rawArgs) {
         successText: (_result, args) => `Document created: ${args.width}x${args.height}px at ${args.resolution}dpi (${args.color_mode})`,
     });
 }
+function documentTargetArgs(args) {
+    const out = {};
+    if (typeof args.name === 'string' && args.name !== '')
+        out.name = args.name;
+    if (typeof args.id === 'number')
+        out.id = args.id;
+    return out;
+}
+function emptySelectorError(args) {
+    if (typeof args.name === 'string' && args.name === '') {
+        return 'name was an empty string. Pass a real document name, or omit name entirely to act on the active document.';
+    }
+    return null;
+}
+async function documentOp(connection, snippetClient, rawArgs) {
+    let errorPrefix = 'Error reading documents';
+    try {
+        const args = validateArgs(documentSchema, rawArgs);
+        const op = args.op;
+        const target = documentTargetArgs(args);
+        if (op === 'activate') {
+            errorPrefix = 'Error activating document';
+            const empty = emptySelectorError(args);
+            if (empty !== null)
+                return toolErrorResult(errorPrefix, new Error(empty));
+            if (Object.keys(target).length === 0) {
+                return toolErrorResult(errorPrefix, new Error('op=activate needs a name or an id. Call op=list to see what is open.'));
+            }
+            const script = await snippetClient.build('activateDocument', target);
+            const result = (await runScript(connection, script));
+            return {
+                content: [{ type: 'text', text: `Activated "${result.name}" (id ${result.id}).` }],
+                structuredContent: {
+                    op,
+                    activated: true,
+                    id: result.id,
+                    name: result.name,
+                    context: result.context,
+                },
+            };
+        }
+        const script = await snippetClient.build('listDocuments', {});
+        const result = (await runScript(connection, script));
+        const docs = result.documents ?? [];
+        const summary = docs.length
+            ? `${docs.length} open document(s): ${docs
+                .map((d) => `${d.name} (id ${d.id}${d.active ? ', ACTIVE' : ''}${d.saved === false ? ', unsaved changes' : ''})`)
+                .join('; ')}.`
+            : 'No documents are open in Photoshop. Open one with ps_open_document, or create one with ps_create_document.';
+        return {
+            content: [{ type: 'text', text: summary }],
+            structuredContent: {
+                op,
+                count: docs.length,
+                documents: docs,
+                context: result.context,
+            },
+        };
+    }
+    catch (error) {
+        return toolErrorResult(errorPrefix, error);
+    }
+}
 async function closeDocument(connection, snippetClient, rawArgs) {
     try {
         const args = validateArgs(closeDocumentSchema, rawArgs);
         const save = args.save;
-        const script = await snippetClient.build('closeDocument', { save });
+        const empty = emptySelectorError(args);
+        if (empty !== null)
+            return toolErrorResult('Error closing document', new Error(empty));
+        const script = await snippetClient.build('closeDocument', {
+            save,
+            ...documentTargetArgs(args),
+        });
         const result = (await runScript(connection, script));
         return {
             content: [

package/dist/tools/image-tools.js

@@ -29,7 +29,8 @@ const cropDocumentSchema = {
             ...PLACEMENT_SCHEMA,
             description: 'ANCHOR-RELATIONAL crop (preferred over guessing pixels): a REGION relation (inside/gap) → the crop is the ' +
                 'resolved region bounding box, verified by the gate. Crops ONLY if the gate PASSES. When set, ' +
-                'left/top/right/bottom are ignored. See ps_resolve_placement for the anchors + relation vocabulary.',
+                'left/top/right/bottom are ignored. See the placement-resolver tool, when this build has one, for the ' +
+                'anchors + relation vocabulary.',
         },
         left: {
             type: 'integer',

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

@@ -82,7 +82,8 @@ const moveLayerSchema = {
             description: 'ANCHOR-RELATIONAL move (preferred over guessing a pixel): a POINT relation (centroid/midpoint/offset) → ' +
                 'the layer\'s CENTER is moved to the resolved, gate-verified point (e.g. "center this layer on the detected ' +
                 'subject" / "…in the gap between the two people"). Moves ONLY if the gate PASSES. When set, delta_*/' +
-                'absolute_*/center_on_* are ignored. See ps_resolve_placement for the anchors + relation vocabulary.',
+                'absolute_*/center_on_* are ignored. See the placement-resolver tool, when this build has one, for the ' +
+                'anchors + relation vocabulary.',
         },
     },
 };

package/dist/tools/path-tools.js

@@ -73,7 +73,7 @@ const pathInputSchema = {
         tool: {
             type: 'string',
             enum: SUPPORTED_BRUSH_TOOLS,
-            description: "stroke only: which brush-family tool paints the path. Default 'brush'. Same 16-tool set as ps_apply_brush_stroke.",
+            description: "stroke only: which brush-family tool paints the path (see this field's own enum for the full supported set). Default 'brush'.",
             default: 'brush',
         },
         color: {

package/dist/tools/scene-tools.js

@@ -4,7 +4,7 @@ import { OnnxDetectionClient } from '../detection/detection-client.js';
 import { ANNOTATED_PREVIEW_JPEG_QUALITY } from '../utils/jpeg-quality.js';
 import { buildSceneModel } from '../perception/scene-model.js';
 import { resolveSelection, SELECT_REFERENCE_TARGETS, } from '../perception/select-recipes.js';
-import { precomputeRegions, loadPrecomputedRegion, saveSelectionAsSceneChannel, CHANNEL_PREFIX, } from '../perception/region-precompute.js';
+import { precomputeRegions, candidateMenu, invalidateSceneChannelsIfStale, loadPrecomputedRegion, saveSelectionAsSceneChannel, CHANNEL_PREFIX, } from '../perception/region-precompute.js';
 import { toolErrorResult } from '../utils/tool-helpers.js';
 import { Logger } from '../utils/logger.js';
 import { isProEntitled } from '../license/entitlement.js';
@@ -54,7 +54,6 @@ function faceMenuFor(model, hasPro) {
         key: `${CHANNEL_PREFIX}${target}`,
         target,
         method: 'face_mesh',
-        confidence: 1,
         bounds: null,
         on_demand: true,
     }));
@@ -82,8 +81,8 @@ const sceneSchema = {
         },
         save_regions: {
             type: 'boolean',
-            default: true,
-            description: 'Precompute every confident region (sky/ground/shadows/highlights/skin/subject/face — and, on a Pro host with a face, the face-feature set scene:face_skin/_eyes/_brows/_lips/_teeth/_nose/_under_eye/_cheeks) and SAVE each as a managed `scene:*` alpha channel, returning the `regions` MENU of what is confidently selectable (each with its method + confidence). ps_select_by_reference then loads the saved channel instantly. Set false for a light read with no channels. The `scene:` channel-name prefix is RESERVED: channels matching it are treated as derived and are deleted on the next scene read and on ps_save_psd, so do not give a channel you want to keep a `scene:`-prefixed name.',
+            default: false,
+            description: 'EAGERLY derive every region (sky/ground/shadows/highlights/skin/subject/face) up front and SAVE each confident one as a managed `scene:*` alpha channel, so the returned menu carries a verified method + confidence for each. Costs one derive per target — measured at ~21s on a 4898x3265 layered document, against a 30s script timeout — so it is OFF by default. Leave it off unless you specifically need every region scored in one call: the default advertises the same menu as `on_demand` entries and ps_select_by_reference derives whichever region you actually ask for (then saves its channel, so repeats of THAT region are instant). The `scene:` channel-name prefix is RESERVED: channels matching it are treated as derived and are deleted on the next scene read and on ps_save_psd, so do not give a channel you want to keep a `scene:`-prefixed name.',
         },
         composition_context: {
             type: 'object',
@@ -143,7 +142,7 @@ async function scene(connection, snippet, client, rawArgs, proRefine, hasPro = f
         const args = validateArgs(sceneSchema, rawArgs);
         const annotate = args.annotate ?? true;
         const refresh = args.refresh ?? false;
-        const saveRegions = args.save_regions ?? true;
+        const saveRegions = args.save_regions ?? false;
         const built = await buildSceneModel(connection, snippet, client, {
             useCache: !refresh,
             maxDimension: args.max_dimension,
@@ -165,6 +164,14 @@ async function scene(connection, snippet, client, rawArgs, proRefine, hasPro = f
                 precomputeOk = false;
             }
         }
+        else {
+            try {
+                await invalidateSceneChannelsIfStale(connection, model.provenance.cache_key);
+            }
+            catch {
+            }
+            regions = [...candidateMenu(model), ...faceMenuFor(model, hasPro)];
+        }
         const content = [];
         if (annotate && built.decoded) {
             try {
@@ -181,19 +188,25 @@ async function scene(connection, snippet, client, rawArgs, proRefine, hasPro = f
             catch {
             }
         }
-        const menuText = !saveRegions
-            ? ''
-            : regions.length
+        const named = (r) => `${r.target}${r.label ? `:${r.label}` : ''}`;
+        const menuText = !regions.length
+            ? saveRegions
+                ? ' No confident named regions detected here.'
+                : ''
+            : saveRegions
                 ? ` Confident regions (select by name): ${regions
-                    .map((r) => `${r.target}${r.label ? `:${r.label}` : ''} ${r.confidence.toFixed(2)}`)
+                    .map((r) => `${named(r)}${r.confidence === undefined ? '' : ` ${r.confidence.toFixed(2)}`}`)
                     .join(', ')}.`
-                : ' No confident named regions detected here.';
+                :
+                    ` Selectable by name (each resolved when you ask for it, not yet scored): ${regions
+                        .map(named)
+                        .join(', ')}.`;
         content.push({ type: 'text', text: summarizeScene(model) + menuText });
         return {
             content,
             structuredContent: {
                 ...model,
-                regions: reconcileRegions(model, regions, saveRegions && precomputeOk),
+                regions: reconcileRegions(model, regions, saveRegions ? (precomputeOk ? 'resolved' : 'unresolved') : 'candidate'),
                 region_menu: regions,
             },
         };
@@ -202,15 +215,23 @@ async function scene(connection, snippet, client, rawArgs, proRefine, hasPro = f
         return toolErrorResult('Error reading scene', error);
     }
 }
-function reconcileRegions(model, menu, resolved) {
+export const SELECTABLE_STATES = [
+    'selectable',
+    'not_selectable',
+    'candidate',
+    'not_resolved',
+];
+function reconcileRegions(model, menu, mode) {
     return model.regions.map((r) => {
         const base = r;
-        if (!resolved) {
+        if (mode !== 'resolved') {
+            const advertised = mode === 'candidate' && menu.some((m) => m.target === r.kind);
             return {
                 ...base,
                 coverage_is_estimate: true,
                 selectable: null,
-                selectable_state: 'not_resolved',
+                selectable_state: advertised ? 'candidate' : 'not_resolved',
+                ...(advertised ? { selectable_via: 'on_demand' } : {}),
             };
         }
         const hit = menu.find((m) => m.target === r.kind);
@@ -290,14 +311,17 @@ async function selectByReference(connection, snippet, client, rawArgs, proRefine
         const args = validateArgs(selectByReferenceSchema, rawArgs);
         const target = args.target;
         const refresh = args.refresh ?? false;
-        if (!refresh) {
+        const discriminated = args.label !== undefined ||
+            args.instance !== undefined ||
+            args.composition_context !== undefined;
+        if (!refresh && !discriminated) {
             const loaded = await loadPrecomputedRegion(connection, target);
             if (loaded) {
                 return {
                     content: [
                         {
                             type: 'text',
-                            text: `Selected "${target}" from the saved scene:${target} channel (precomputed by ps_read_scene). Verify with ps_get_selection_preview.`,
+                            text: `Selected "${target}" from the saved scene:${target} channel (cached by an earlier derive). If the image changed since, re-run with refresh:true. Verify with ps_get_selection_preview.`,
                         },
                     ],
                     structuredContent: {
@@ -326,7 +350,7 @@ async function selectByReference(connection, snippet, client, rawArgs, proRefine
             proRefine,
             skyCtx: skyCtxFrom(built),
         });
-        if (res.passed && target.startsWith('face_')) {
+        if (res.passed && !discriminated) {
             try {
                 await saveSelectionAsSceneChannel(connection, target);
             }
@@ -392,12 +416,12 @@ export function createSceneTools(connection, snippetClient, opts = {}) {
                                     },
                                     selectable_state: {
                                         type: 'string',
-                                        enum: ['selectable', 'not_selectable', 'not_resolved'],
-                                        description: '`selectable`: a precomputed channel is ready to load. `not_selectable`: resolution ran and this region did not pass the confidence gate. `not_resolved`: precompute did not run or failed, so absence here is NOT evidence the region is unavailable.',
+                                        enum: [...SELECTABLE_STATES],
+                                        description: '`selectable`: a precomputed channel is ready to load. `not_selectable`: resolution ran and this region did not pass the confidence gate. `candidate`: the DEFAULT read advertised this region without deriving it — ps_select_by_reference scores it when you ask, and it may still turn out not to pass. `not_resolved`: an eagerly-requested precompute did not run or failed, so absence here is NOT evidence the region is unavailable.',
                                     },
                                     selectable_via: {
                                         type: 'string',
-                                        description: 'The method that resolved it (only when selectable).',
+                                        description: "The method that resolved it, when one did. Reads 'on_demand' for a `candidate` — nothing has resolved it yet and the method is chosen at derive time.",
                                     },
                                     selectable_confidence: { type: 'number' },
                                 },
@@ -421,7 +445,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, loaded instantly from the scene:face_* channel ps_read_scene precomputes. `passed`/`confidence` are returned. 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). 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.',
                 inputSchema: selectByReferenceSchema,
                 outputSchema: {
                     type: 'object',

package/dist/tools/selection-tools.js

@@ -466,7 +466,7 @@ const SELECT_INPUT_SCHEMA = {
         ...selectPolygonSchema.properties,
         placement: {
             ...PLACEMENT_SCHEMA,
-            description: 'Grounded coordinates (rectangle/ellipse/magic_wand): NAME anchors + a relation instead of guessing pixels. rectangle/ellipse ← a REGION relation (inside/gap) → the selection bounding box; magic_wand ← a POINT relation (centroid/extremum/grid) → the click. Verified by the objective gate; wins over the raw edges/x-y. See ps_resolve_placement for the vocabulary.',
+            description: 'Grounded coordinates (rectangle/ellipse/magic_wand): NAME anchors + a relation instead of guessing pixels. rectangle/ellipse ← a REGION relation (inside/gap) → the selection bounding box; magic_wand ← a POINT relation (centroid/extremum/grid) → the click. Verified by the objective gate; wins over the raw edges/x-y. See the placement-resolver tool, when this build has one, for the vocabulary.',
         },
     },
     required: ['mode'],

package/dist/tools/shape-tools.js

@@ -31,7 +31,7 @@ const shapeInputSchema = {
                 'edge or a Pro face-mesh landmark curve) → 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 ps_resolve_placement for the anchors + relation vocabulary.',
+                'applies. See the placement-resolver tool, when this build has one, for the anchors + relation vocabulary.',
         },
         left: {
             type: 'number',

package/dist/utils/session-log.js

@@ -38,6 +38,19 @@ export const ERROR_CLASS_TABLE = [
         pattern: /file not found|map not found|lut not found|could not open lut/i,
     },
     { errorClass: 'face_not_found', pattern: /no face mesh|no face detected/i },
+    {
+        errorClass: 'perception_export_failed',
+        pattern: /saveAs reported success but no file/i,
+    },
+    { errorClass: 'image_decode_failed', pattern: /failed to decode jpeg/i },
+    {
+        errorClass: 'detection_unavailable',
+        pattern: /onnxruntime|onnx runtime/i,
+    },
+    {
+        errorClass: 'file_io',
+        pattern: /\b(ENOENT|EBUSY|EACCES|EPERM|EMFILE|ENOSPC)\b/,
+    },
     {
         errorClass: 'schema_validation',
         pattern: /\bvalidat|required.*field|missing required argument|must be.*type|invalid (input|argument)/i,

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '1.2.0';
+export const VERSION = '1.3.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "editmamei",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Photoshop MCP server: natural-language AI photo editing with your own Photoshop (Community Edition)",
   "mcpName": "io.github.editmamei/editmamei",
   "editmamei": {
@@ -11,6 +11,9 @@
       "1.2.0": [
         "ps_delete_layer",
         "ps_select_layer"
+      ],
+      "1.2.1": [
+        "ps_read_scene"
       ]
     }
   },