editmamei 0.22.3 → 0.23.0

package/dist/api/extendscript/_helpers.js

@@ -205,7 +205,29 @@ export function duplicateForOp(opName, applyToActiveLayer) {
     var __opTargetIsCopy = true;
     `;
 }
+export const countLayersRecursiveHelper = `
+function __countLayersRecursive(layers) {
+  var total = 0;
+  var n = 0;
+  try { n = layers.length; } catch (eN) { n = 0; }
+  for (var i = 0; i < n; i++) {
+    var candidate = null;
+    try { candidate = layers[i]; } catch (eC) { continue; }
+    if (!candidate) continue;
+    total++;
+    var isGroup = false;
+    try { isGroup = (candidate instanceof LayerSet); } catch (eG) {}
+    if (isGroup) {
+      var childLayers = null;
+      try { childLayers = candidate.layers; } catch (eCl) { childLayers = null; }
+      if (childLayers) total += __countLayersRecursive(childLayers);
+    }
+  }
+  return total;
+}
+`;
 export const getContextInfo = `
+${countLayersRecursiveHelper}
 function getContextInfo() {
   // The whole body is wrapped in try/catch — a destructive op that
   // succeeded but then triggered "document closed" / "active layer gone"
@@ -228,6 +250,7 @@ function getContextInfo() {
         resolution: doc.resolution,
         colorMode: String(doc.mode),
         layerCount: doc.layers.length,
+        total_layer_count: __countLayersRecursive(doc.layers),
         hasSelection: (function () {
           // ExtendScript throws "No such element" when accessing doc.selection.bounds
           // with no active selection, and that error is NOT catchable when DoJavaScript
@@ -242,12 +265,35 @@ function getContextInfo() {
 
       if (doc.activeLayer) {
         var layer = doc.activeLayer;
+
+        // layer.visible on the ExtendScript DOM returns EFFECTIVE
+        // visibility (parent-chain AND own flag) NO MATTER which proxy
+        // resolves it -- re-reading through a fresh doc.layers walk does
+        // NOT recover the layer's own flag (verified live 2026-07: a
+        // visible child inside a hidden group reads visible:false from
+        // every DOM proxy, active-layer or walked). The own flag is only
+        // readable via Action Manager's Vsbl property, keyed by the
+        // layer's stable id (putIdentifier, not putName -- names aren't
+        // unique). Confirmed live on both an ArtLayer and a LayerSet.
+        // Falls back to the DOM (effective) value if the AM read throws,
+        // so a failure degrades to the old behavior instead of breaking
+        // the context block every tool returns.
+        var __effectiveVisible = layer.visible;
+        var __ownVisible = __effectiveVisible;
+        try {
+          var __visRef = new ActionReference();
+          __visRef.putProperty(app.charIDToTypeID('Prpr'), app.charIDToTypeID('Vsbl'));
+          __visRef.putIdentifier(app.charIDToTypeID('Lyr '), layer.id);
+          __ownVisible = app.executeActionGet(__visRef).getBoolean(app.charIDToTypeID('Vsbl'));
+        } catch (eOwn) {}
+
         context.activeLayer = {
           name: layer.name,
           kind: String(layer.kind),
           opacity: layer.opacity,
           blendMode: String(layer.blendMode),
-          visible: layer.visible,
+          visible: __ownVisible,
+          effectively_visible: __effectiveVisible,
           locked: layer.allLocked,
           isBackground: layer.isBackgroundLayer
         };
@@ -302,3 +348,141 @@ function getMinimalContextInfo() {
   }
 }
 `;
+export const parentPathHelper = `
+function __parentPathOf(doc, layer) {
+  function __ppWalk(layers, trail) {
+    var n = 0;
+    try { n = layers.length; } catch (eN) {}
+    for (var i = 0; i < n; i++) {
+      var candidate = null;
+      try { candidate = layers[i]; } catch (eC) { continue; }
+      if (!candidate) continue;
+      if (candidate === layer) return trail;
+      var isGroup = false;
+      try { isGroup = (candidate instanceof LayerSet); } catch (eG) {}
+      if (isGroup) {
+        var cname = null;
+        try { cname = candidate.name; } catch (eNm) {}
+        var childLayers = null;
+        try { childLayers = candidate.layers; } catch (eCl) {}
+        if (childLayers) {
+          var found = __ppWalk(childLayers, trail.concat([cname]));
+          if (found !== null) return found;
+        }
+      }
+    }
+    return null;
+  }
+  return __ppWalk(doc.layers, []);
+}
+`;
+export const hoistFromActiveGroupHelper = `
+function __hoistFromActiveGroupIfNeeded(doc, preMkActive, newLayer, intoActiveGroup) {
+  if (intoActiveGroup) return false;
+  var preWasGroup = false;
+  try { preWasGroup = (preMkActive instanceof LayerSet); } catch (eG) {}
+  if (!preWasGroup) return false;
+  var landedInside = false;
+  try {
+    var n = preMkActive.layers.length;
+    for (var i = 0; i < n; i++) {
+      if (preMkActive.layers[i] === newLayer) { landedInside = true; break; }
+    }
+  } catch (eIn) {}
+  if (!landedInside) return false;
+  try {
+    newLayer.move(preMkActive, ElementPlacement.PLACEBEFORE);
+    try { doc.activeLayer = newLayer; } catch (eA) {}
+    return true;
+  } catch (eMove) {}
+  return false;
+}
+`;
+export const layerResolveHelpers = `
+function __safeGet(fn, fallback) {
+  try { var v = fn(); return (v === undefined ? fallback : v); }
+  catch (e) { return fallback; }
+}
+
+function __findLayerPath(layers, target, prefix) {
+  var n = __safeGet(function () { return layers.length; }, 0);
+  for (var i = 0; i < n; i++) {
+    var candidate = __safeGet(function () { return layers[i]; }, null);
+    if (!candidate) continue;
+    if (candidate === target) return prefix.concat([i]);
+    var isGroup = false;
+    try { isGroup = (candidate instanceof LayerSet); } catch (eG) {}
+    if (isGroup) {
+      var childLayers = __safeGet(function () { return candidate.layers; }, null);
+      if (childLayers) {
+        var found = __findLayerPath(childLayers, target, prefix.concat([i]));
+        if (found) return found;
+      }
+    }
+  }
+  return null;
+}
+
+function __findLayerById(layers, id) {
+  var n = __safeGet(function () { return layers.length; }, 0);
+  for (var i = 0; i < n; i++) {
+    var candidate = __safeGet(function () { return layers[i]; }, null);
+    if (!candidate) continue;
+    var cid = __safeGet(function () { return candidate.id; }, null);
+    if (cid === id) return candidate;
+    var isGroup = false;
+    try { isGroup = (candidate instanceof LayerSet); } catch (eG) {}
+    if (isGroup) {
+      var childLayers = __safeGet(function () { return candidate.layers; }, null);
+      if (childLayers) {
+        var found = __findLayerById(childLayers, id);
+        if (found) return found;
+      }
+    }
+  }
+  return null;
+}
+
+function __resolvePath(doc, path) {
+  var current = doc;
+  for (var i = 0; i < path.length; i++) {
+    var idx = path[i];
+    current = __safeGet(function () { return current.layers[idx]; }, null);
+    if (!current) return null;
+  }
+  return current;
+}
+
+function __captureLayerIdentity(doc, layer) {
+  var id = null;
+  try { if (typeof layer.id !== 'undefined') { id = layer.id; } } catch (eId) {}
+  var path = null;
+  if (id === null) {
+    path = __findLayerPath(doc.layers, layer, []);
+  }
+  return { id: id, path: path };
+}
+
+function __resolveLayerFresh(doc, identity) {
+  if (identity.id !== null) {
+    var byId = __findLayerById(doc.layers, identity.id);
+    if (byId) return byId;
+  }
+  if (identity.path) {
+    return __resolvePath(doc, identity.path);
+  }
+  return null;
+}
+
+function __resolveLayerFreshOrActive(doc, identity) {
+  var resolved = __resolveLayerFresh(doc, identity);
+  if (resolved) return resolved;
+  // Identity resolution came up empty even though the write may have
+  // landed — e.g. Photoshop auto-promoting a Background layer as a side
+  // effect of the property write. Fall back to the current active layer
+  // (these setters always operate on doc.activeLayer, and Photoshop keeps
+  // it pointed at the promoted layer) rather than treating an unresolved
+  // identity as proof the write failed.
+  return __safeGet(function () { return doc.activeLayer; }, null);
+}
+`;

package/dist/core/server.js

@@ -330,6 +330,37 @@ export class EditmameiServer {
                 `${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    async ensureEntitledModuleFresh(delivery = {}) {
+        if (this.moduleSkipReason !== null)
+            return;
+        if (!isProEntitled())
+            return;
+        const underTest = process.env.VITEST !== undefined || process.env.NODE_ENV === 'test';
+        if (underTest && !delivery.fetchImpl)
+            return;
+        const license = readLicense();
+        if (!license)
+            return;
+        try {
+            const prov = await provisionModules(license.key, {
+                config: delivery.config,
+                fetchImpl: delivery.fetchImpl,
+                signingKeys: delivery.signingKeys,
+                sleep: delivery.sleep,
+            });
+            for (const m of prov.installed) {
+                this.logger.info(`Pro module updated to v${m.version} — restart to load.`);
+            }
+            for (const e of prov.errors) {
+                this.logger.warn(`Pro-module freshness check could not provision the ${e.sku} module ` +
+                    `(staying on the installed version): ${e.message}`);
+            }
+        }
+        catch (err) {
+            this.logger.warn(`Background Pro-module freshness check failed (staying on the installed version): ` +
+                `${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     assertToolsClassified() {
         for (const tool of this.toolRegistry.list()) {
             tierOf(tool.name);
@@ -485,6 +516,7 @@ export class EditmameiServer {
         await this.server.connect(transport);
         void this.session.initialize().catch(() => undefined);
         void this.reprovisionIfModuleSkipped();
+        void this.ensureEntitledModuleFresh();
         this.telemetry.start();
         void this.telemetry.flushOutboxOnStartup();
         this.server.onclose = () => {

package/dist/license/entitlement.js

@@ -4,8 +4,8 @@ import { readLicense, writeLicense, clearLicense, } from './store.js';
 import { PolarLicenseClient, PolarLicenseError } from './polar-client.js';
 import { Logger } from '../utils/logger.js';
 const logger = new Logger('License');
-export const GRACE_MS = 30 * 24 * 60 * 60 * 1000;
-export const REFRESH_AFTER_MS = 7 * 24 * 60 * 60 * 1000;
+export const GRACE_MS = 7 * 24 * 60 * 60 * 1000;
+export const REFRESH_AFTER_MS = 24 * 60 * 60 * 1000;
 export const EXPIRED_REFRESH_TIMEOUT_MS = 5_000;
 export const CLOCK_SKEW_TOLERANCE_MS = 24 * 60 * 60 * 1000;
 export function evaluateEntitlement(rec, now) {

package/dist/license/ping-refresh.js

@@ -1,10 +1,14 @@
 import { refreshIfStale } from './entitlement.js';
-export function createPingLicenseRefresher(refresh = refreshIfStale) {
-    let fired = false;
+export const PING_REFRESH_MIN_INTERVAL_MS = 15 * 60_000;
+export function createPingLicenseRefresher(refresh = refreshIfStale, opts = {}) {
+    const now = opts.now ?? Date.now;
+    const minIntervalMs = opts.minIntervalMs ?? PING_REFRESH_MIN_INTERVAL_MS;
+    let lastAttemptAt = Number.NEGATIVE_INFINITY;
     return () => {
-        if (fired)
+        const t = now();
+        if (t - lastAttemptAt < minIntervalMs)
             return;
-        fired = true;
+        lastAttemptAt = t;
         try {
             void refresh().catch(() => { });
         }

package/dist/platform/macos-executor.js

@@ -83,28 +83,34 @@ export class MacOSExecutor {
         const dir = await TempDir.create('editmamei-mac-');
         try {
             const jsxPath = await dir.write('script.jsx', script);
-            const wrapperPath = await dir.write('wrapper.scpt', this.createAppleScriptWrapper(jsxPath));
-            const { stdout, stderr } = await runChildWithTimeout('osascript', [wrapperPath], {
+            const wrapperPath = await dir.write('wrapper.scpt', this.createAppleScriptWrapper(jsxPath, timeout));
+            const { stdout, stderr, exitCode } = await runChildWithTimeout('osascript', [wrapperPath], {
                 timeout,
                 diagLabel: 'osascript wrapper.scpt',
             });
             if (stderr) {
                 this.logger.warn('Script execution warning:', stderr);
             }
+            if (exitCode !== 0) {
+                throw new Error(`osascript exited with code ${exitCode}: ${stderr.trim() || '(no stderr)'}`);
+            }
             return this.parseResult(stdout);
         }
         finally {
             await dir.cleanup();
         }
     }
-    createAppleScriptWrapper(jsxPath) {
+    createAppleScriptWrapper(jsxPath, timeoutMs = 30000) {
         const posixPath = jsxPath.replace(/\\/g, '/');
         if (posixPath.includes('"') || posixPath.includes("'") || posixPath.includes('\n')) {
             throw new Error('jsxPath contains a character that would break AppleScript interpolation');
         }
-        return `tell application "${this.appName}"
-\tdo javascript "$.evalFile(decodeURI('${encodeURI(posixPath)}'))"
-end tell`;
+        const timeoutSeconds = Number.isFinite(timeoutMs) && timeoutMs > 0 ? Math.max(1, Math.ceil(timeoutMs / 1000)) : 1;
+        return `with timeout of ${timeoutSeconds} seconds
+\ttell application "${this.appName}"
+\t\tdo javascript "$.evalFile(decodeURI('${encodeURI(posixPath)}'))"
+\tend tell
+end timeout`;
     }
     parseResult(output) {
         const trimmed = output.trim();

package/dist/platform/run-child.js

@@ -87,9 +87,12 @@ export async function runChildWithTimeout(command, args, options) {
         });
         child.on('exit', (code, signal) => {
             if (timedOut) {
-                settle(() => reject(new Error(`Script execution timeout after ${timeout}ms (${diagLabel}). The child process was killed; ` +
-                    `if Photoshop has a modal dialog open (license, missing font, GPU init, "Discard?" prompt), ` +
-                    `dismiss it in Photoshop and retry.`)));
+                settle(() => reject(new Error(`Script execution timeout after ${timeout}ms (${diagLabel}). The child process was killed, ` +
+                    `but Photoshop runs as a separate process and may have kept executing — the operation ` +
+                    `could still have completed. Check Photoshop's actual state before retrying. Common ` +
+                    `causes: a genuinely slow operation (e.g. a large RAW file's first Camera Raw engine ` +
+                    `init) exceeding the timeout, or a modal dialog open in Photoshop (license, missing ` +
+                    `font, GPU init, "Discard?" prompt) — dismiss it if present.`)));
                 return;
             }
             if (overflowed) {

package/dist/tools/adjustment-tools.js

@@ -495,6 +495,11 @@ const addAdjustmentLayerSchema = {
             description: 'Only meaningful when mask_from_selection is true AND there is an active selection. If true, the resulting mask is inverted — so the adjustment affects EVERYTHING OUTSIDE the selection rather than inside. Common idiom: "I selected the sky but want to adjust everything else." Defaults to false.',
             default: false,
         },
+        into_active_group: {
+            type: 'boolean',
+            description: "Photoshop's Mk-AdjL descriptor carries no placement target, so with a GROUP active it would natively nest the new layer INSIDE that group. Default false hoists the new layer back out so it lands above the active layer/group as a sibling, matching this tool's documented placement. Pass true to keep the new layer nested inside the active group instead.",
+            default: false,
+        },
     },
     required: ['type'],
 };
@@ -660,7 +665,7 @@ export function createAdjustmentTools(connection, snippetClient) {
         {
             tool: {
                 name: 'ps_add_adjustment_layer',
-                description: "Create a non-destructive adjustment layer above the active layer. Supports the full real-Photoshop tonal/color surface: Curves (with S-curve presets), Levels, Hue/Saturation, Brightness/Contrast, Black & White (with optional tint), Color Balance, Photo Filter (preset or custom color), Vibrance, Channel Mixer, Selective Color, Gradient Map (preset), Exposure (stops + offset + gamma), Color Lookup (3DLUT presets or custom file path), and Invert. Values are editable, maskable, and removable. This is the canonical entry point for ALL tonal/color adjustments; the old destructive bake tools (auto_levels / auto_contrast / desaturate / invert) were removed on 2026-05-31 — if you genuinely need a pixel bake, follow this call with `photoshop_merge_visible_layers`. Optionally clips the adjustment to only affect the layer directly below it. If a selection is active at call time, the new layer is automatically masked by it (toggle with mask_from_selection / mask_inverted). For destructive ops that don't have an adjustment-layer equivalent in Photoshop (Shadows/Highlights — single-pass shadow/highlight recovery), use `photoshop_apply_shadows_highlights` which auto-duplicates the active layer to keep the original intact. Returns context — the new adjustment layer becomes active.",
+                description: "Create a non-destructive adjustment layer above the active layer — hoisted out of the active layer's group by default even though Photoshop's own Mk-AdjL placement rule would otherwise nest it INSIDE that group (pass into_active_group:true to keep that native nesting). Supports the full real-Photoshop tonal/color surface: Curves (with S-curve presets), Levels, Hue/Saturation, Brightness/Contrast, Black & White (with optional tint), Color Balance, Photo Filter (preset or custom color), Vibrance, Channel Mixer, Selective Color, Gradient Map (preset), Exposure (stops + offset + gamma), Color Lookup (3DLUT presets or custom file path), and Invert. Values are editable, maskable, and removable. This is the canonical entry point for ALL tonal/color adjustments; the old destructive bake tools (auto_levels / auto_contrast / desaturate / invert) were removed on 2026-05-31 — if you genuinely need a pixel bake, follow this call with `photoshop_merge_visible_layers`. Optionally clips the adjustment to only affect the layer directly below it. If a selection is active at call time, the new layer is automatically masked by it (toggle with mask_from_selection / mask_inverted). For destructive ops that don't have an adjustment-layer equivalent in Photoshop (Shadows/Highlights — single-pass shadow/highlight recovery), use `photoshop_apply_shadows_highlights` which auto-duplicates the active layer to keep the original intact. Returns context (the new adjustment layer becomes active) plus parent_path — the actual containing-group chain, so placement is never silent.",
                 inputSchema: addAdjustmentLayerSchema,
                 outputSchema: {
                     type: 'object',
@@ -677,6 +682,15 @@ export function createAdjustmentTools(connection, snippetClient) {
                         mask_inverted: { type: 'boolean' },
                         mask_inversion_error: { type: ['string', 'null'] },
                         clipError: { type: 'string' },
+                        hoisted: {
+                            type: 'boolean',
+                            description: 'True when the new layer had to be moved back out of the previously-active group to honor into_active_group:false (the default). False when it landed correctly on its own, or when the move-back itself failed — check the layer tree if this matters and hoisted is false.',
+                        },
+                        parent_path: {
+                            type: ['array', 'null'],
+                            items: { type: 'string' },
+                            description: 'The containing-group name chain (outermost first), empty array at the document root.',
+                        },
                         context: { type: 'object' },
                     },
                 },
@@ -785,6 +799,7 @@ async function addAdjustmentLayer(connection, snippetClient, rawArgs) {
         const name = args.name;
         const maskFromSelection = args.mask_from_selection ?? true;
         const maskInverted = args.mask_inverted ?? false;
+        const intoActiveGroup = args.into_active_group ?? false;
         const params = {};
         for (const key of FORWARDED_KEYS) {
             if (args[key] !== undefined)
@@ -806,6 +821,7 @@ async function addAdjustmentLayer(connection, snippetClient, rawArgs) {
             clip_to_below: clipToBelow,
             mask_from_selection: maskFromSelection,
             mask_inverted: maskInverted,
+            into_active_group: intoActiveGroup,
             ...params,
         };
         if (name !== undefined)

package/dist/tools/document-tools.js

@@ -1,5 +1,6 @@
 import { runScript } from '../utils/run-script.js';
 import { validateArgs } from '../utils/validate.js';
+import { OPEN_DOCUMENT_TIMEOUT_MS, OPEN_DOCUMENT_REPROBE_TIMEOUT_MS, } from '../utils/operation-timeouts.js';
 const createDocumentSchema = {
     type: 'object',
     properties: {
@@ -375,13 +376,27 @@ async function closeDocument(connection, snippetClient, rawArgs) {
         };
     }
 }
+function isScriptTimeoutError(message) {
+    return /Script execution timeout|AppleEvent timed out|(?:^|[\s(])-1712(?:[\s)]|$)/i.test(message);
+}
+async function reprobeOpenDocument(connection, snippetClient, filePath) {
+    try {
+        const probeScript = await snippetClient.build('probeOpenDocument', { filePath });
+        const result = (await runScript(connection, probeScript, OPEN_DOCUMENT_REPROBE_TIMEOUT_MS));
+        return result.success ? result : null;
+    }
+    catch {
+        return null;
+    }
+}
 async function openDocumentPipeline(connection, snippetClient, rawArgs) {
+    let filePath;
     try {
         const args = validateArgs(openDocumentSchema, rawArgs);
-        const filePath = args.file_path;
+        filePath = args.file_path;
         const suppressDialogs = args.suppress_dialogs;
         const script = await snippetClient.build('openDocumentPipeline', { filePath, suppressDialogs });
-        const result = await runScript(connection, script);
+        const result = await runScript(connection, script, OPEN_DOCUMENT_TIMEOUT_MS);
         return {
             content: [
                 {
@@ -393,11 +408,28 @@ async function openDocumentPipeline(connection, snippetClient, rawArgs) {
         };
     }
     catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (filePath !== undefined && isScriptTimeoutError(message)) {
+            const reprobed = await reprobeOpenDocument(connection, snippetClient, filePath);
+            if (reprobed) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Document opened (the open exceeded the ${OPEN_DOCUMENT_TIMEOUT_MS}ms budget and was ` +
+                                `reported as a timeout, but a post-timeout check confirmed it actually completed):\n` +
+                                JSON.stringify(reprobed, null, 2),
+                        },
+                    ],
+                    structuredContent: reprobed,
+                };
+            }
+        }
         return {
             content: [
                 {
                     type: 'text',
-                    text: `Error opening document: ${error instanceof Error ? error.message : String(error)}`,
+                    text: `Error opening document: ${message}`,
                 },
             ],
             isError: true,

package/dist/tools/group-tools.js

@@ -27,6 +27,11 @@ const createGroupSchema = {
             items: { type: 'string' },
             description: 'Optional list of existing layer names to move into the new group. The first listed name ends up on top of the group stack. Layers not found are returned in `not_found`.',
         },
+        into_active_group: {
+            type: 'boolean',
+            description: "Photoshop's Mk-layerSection descriptor carries no placement target, so with a GROUP active it would natively nest the new group INSIDE that group. Default false hoists the new group back out so it lands above the active layer/group as a sibling, matching this tool's documented placement. Pass true to keep it nested inside the active group instead.",
+            default: false,
+        },
     },
     required: ['name'],
 };
@@ -78,7 +83,7 @@ export function createGroupTools(connection, snippetClient) {
         {
             tool: {
                 name: 'ps_create_group',
-                description: 'Create a new layer group (LayerSet) above the active layer with the given name. Optionally moves existing layers into it in one step. Non-destructive. Foundational for structured non-destructive editing — e.g. group all adjustment layers into an "edits" group so you can A/B toggle the whole stack via group visibility.',
+                description: `Create a new layer group (LayerSet) above the active layer with the given name — hoisted out of the active layer's group by default even though Photoshop's own Mk-layerSection placement rule would otherwise nest it INSIDE that group (pass into_active_group:true to keep that native nesting; this is why groups created one after another land as siblings rather than nested, so bottom-to-top group creation is safe). Optionally moves existing layers into it in one step. Non-destructive. Foundational for structured non-destructive editing — e.g. group all adjustment layers into an "edits" group so you can A/B toggle the whole stack via group visibility.`,
                 inputSchema: createGroupSchema,
                 outputSchema: {
                     type: 'object',
@@ -87,6 +92,15 @@ export function createGroupTools(connection, snippetClient) {
                         groupName: { type: 'string' },
                         moved_count: { type: 'number' },
                         not_found: { type: 'array', items: { type: 'string' } },
+                        hoisted: {
+                            type: 'boolean',
+                            description: 'True when the new group had to be moved back out of the previously-active group to honor into_active_group:false (the default). False when it landed correctly on its own, or when the move-back itself failed — check the layer tree if this matters and hoisted is false.',
+                        },
+                        parent_path: {
+                            type: ['array', 'null'],
+                            items: { type: 'string' },
+                            description: 'The containing-group name chain (outermost first), empty array at the document root.',
+                        },
                         context: { type: 'object' },
                     },
                 },
@@ -283,7 +297,8 @@ async function createGroup(connection, snippetClient, rawArgs) {
         const args = validateArgs(createGroupSchema, rawArgs);
         const name = args.name;
         const layers = args.layers;
-        const params = { name };
+        const intoActiveGroup = args.into_active_group ?? false;
+        const params = { name, into_active_group: intoActiveGroup };
         if (layers !== undefined)
             params.layerNames = layers;
         const script = await snippetClient.build('createGroup', params);

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

@@ -84,6 +84,16 @@ const duplicateLayerSchema = {
         },
     },
 };
+const copyToNewLayerSchema = {
+    type: 'object',
+    properties: {
+        into_active_group: {
+            type: 'boolean',
+            description: "Photoshop's CpTL (Layer via Copy) event carries no placement target, so with a GROUP active it would natively nest the new layer INSIDE that group. Default false hoists the new layer back out so it lands above the active layer/group as a sibling. Pass true to keep it nested inside the active group instead.",
+            default: false,
+        },
+    },
+};
 const addLayerStyleSchema = {
     type: 'object',
     properties: {
@@ -247,11 +257,20 @@ export function createLayerPropertiesTools(connection, snippetClient) {
                 outputSchema: {
                     type: 'object',
                     properties: {
-                        updated: { type: 'boolean' },
                         property: { type: 'string' },
                         value: { type: ['number', 'string'] },
+                        requested: { type: ['number', 'string', 'boolean'] },
+                        verified: { type: 'boolean' },
+                        verification_unreadable: {
+                            type: 'boolean',
+                            description: 'visibility only: true when the write itself did not throw but the own-flag verification read failed (Action Manager error, or the layer had no readable id) — verified is false, but this is NOT proof the write failed, just that it could not be confirmed.',
+                        },
                         fill_opacity: { type: 'number' },
+                        requested_fill_opacity: { type: 'number' },
+                        fill_opacity_verified: { type: 'boolean' },
                         opacity: { type: 'number' },
+                        requested_opacity: { type: ['number', 'null'] },
+                        opacity_verified: { type: ['boolean', 'null'] },
                         visible: { type: 'boolean' },
                         locked: { type: 'boolean' },
                         name: { type: 'string' },
@@ -278,6 +297,11 @@ export function createLayerPropertiesTools(connection, snippetClient) {
                     properties: {
                         originalName: { type: 'string' },
                         newName: { type: 'string' },
+                        parent_path: {
+                            type: ['array', 'null'],
+                            items: { type: 'string' },
+                            description: "The containing-group name chain (outermost first), empty array at the document root. layer.duplicate() is parent-preserving by DOM semantics, so this always matches the original layer's placement.",
+                        },
                         context: { type: 'object' },
                     },
                 },
@@ -291,8 +315,8 @@ export function createLayerPropertiesTools(connection, snippetClient) {
         {
             tool: {
                 name: 'ps_copy_to_new_layer',
-                description: 'Copy the current selection into a NEW layer above the active one — Photoshop\'s "Layer via Copy" (Ctrl+J). The source layer is left untouched and the new copied layer becomes active. With an active selection only the selected pixels are lifted; with no selection it copies the whole active layer (a plain duplicate). Reach for this to isolate a region for independent transforms or filters (stretch, light rays, a local grade) without altering the source. Returns context so the caller sees the new active layer.',
-                inputSchema: emptySchema,
+                description: 'Copy the current selection into a NEW layer above the active one — Photoshop\'s "Layer via Copy" (Ctrl+J) — hoisted out of the active layer\'s group by default even though the underlying CpTL event carries no placement target and would otherwise nest the new layer INSIDE that group (pass into_active_group:true to keep that native nesting). The source layer is left untouched and the new copied layer becomes active. With an active selection only the selected pixels are lifted; with no selection it copies the whole active layer (a plain duplicate). Reach for this to isolate a region for independent transforms or filters (stretch, light rays, a local grade) without altering the source. Returns context so the caller sees the new active layer.',
+                inputSchema: copyToNewLayerSchema,
                 outputSchema: {
                     type: 'object',
                     properties: {
@@ -301,6 +325,15 @@ export function createLayerPropertiesTools(connection, snippetClient) {
                         original_active_layer_name: { type: 'string' },
                         layer_count_before: { type: 'number' },
                         layer_count_after: { type: 'number' },
+                        hoisted: {
+                            type: 'boolean',
+                            description: 'True when the new layer had to be moved back out of the previously-active group to honor into_active_group:false (the default). False when it landed correctly on its own, or when the move-back itself failed — check the layer tree if this matters and hoisted is false.',
+                        },
+                        parent_path: {
+                            type: ['array', 'null'],
+                            items: { type: 'string' },
+                            description: 'The containing-group name chain (outermost first), empty array at the document root.',
+                        },
                         context: { type: 'object' },
                     },
                 },
@@ -309,7 +342,7 @@ export function createLayerPropertiesTools(connection, snippetClient) {
                     idempotentHint: false,
                 },
             },
-            handler: async () => layerViaCopy(connection, snippetClient),
+            handler: async (args) => layerViaCopy(connection, snippetClient, args),
         },
         {
             tool: {
@@ -493,23 +526,25 @@ async function setLayerOpacity(connection, snippetClient, rawArgs) {
         if (opacity === undefined && fillPercent === undefined) {
             throw new Error('set_layer_opacity requires opacity and/or fill_percent.');
         }
-        let label;
         let buildParams;
         if (fillPercent !== undefined) {
             buildParams = { fillOpacity: fillPercent };
             if (opacity !== undefined)
                 buildParams.opacity = opacity;
-            label =
-                opacity !== undefined
-                    ? `opacity ${opacity}% + fill ${fillPercent}%`
-                    : `fill ${fillPercent}%`;
         }
         else {
             buildParams = { opacity };
-            label = `opacity ${opacity}%`;
         }
         const script = await snippetClient.build('setLayerOpacity', buildParams);
         const result = await runScript(connection, script);
+        const r = result;
+        const parts = [];
+        const opacityActual = r.value ?? (r.requested_opacity != null ? r.opacity : undefined);
+        if (opacityActual !== undefined)
+            parts.push(`opacity ${opacityActual}%`);
+        if (r.fill_opacity !== undefined)
+            parts.push(`fill ${r.fill_opacity}%`);
+        const label = parts.length > 0 ? parts.join(' + ') : 'opacity';
         return {
             content: [
                 {
@@ -538,11 +573,13 @@ async function setLayerBlendMode(connection, snippetClient, rawArgs) {
         const blendMode = args.blend_mode;
         const script = await snippetClient.build('setLayerBlendMode', { blendMode });
         const result = await runScript(connection, script);
+        const r = result;
+        const text = r.value !== undefined ? `Layer blend mode set to ${r.value}` : 'Layer blend mode set';
         return {
             content: [
                 {
                     type: 'text',
-                    text: `Layer blend mode set to ${blendMode}`,
+                    text,
                 },
             ],
             structuredContent: result,
@@ -566,11 +603,13 @@ async function setLayerVisibility(connection, snippetClient, rawArgs) {
         const visible = args.visible;
         const script = await snippetClient.build('setLayerVisibility', { visible });
         const result = await runScript(connection, script);
+        const r = result;
+        const text = r.visible !== undefined ? `Layer ${r.visible ? 'shown' : 'hidden'}` : 'Layer visibility set';
         return {
             content: [
                 {
                     type: 'text',
-                    text: `Layer ${visible ? 'shown' : 'hidden'}`,
+                    text,
                 },
             ],
             structuredContent: result,
@@ -594,11 +633,13 @@ async function setLayerLocked(connection, snippetClient, rawArgs) {
         const locked = args.locked;
         const script = await snippetClient.build('setLayerLocked', { locked });
         const result = await runScript(connection, script);
+        const r = result;
+        const text = r.locked !== undefined ? `Layer ${r.locked ? 'locked' : 'unlocked'}` : 'Layer lock state set';
         return {
             content: [
                 {
                     type: 'text',
-                    text: `Layer ${locked ? 'locked' : 'unlocked'}`,
+                    text,
                 },
             ],
             structuredContent: result,
@@ -622,11 +663,15 @@ async function renameLayer(connection, snippetClient, rawArgs) {
         const name = args.name;
         const script = await snippetClient.build('renameLayer', { newName: name });
         const result = await runScript(connection, script);
+        const r = result;
+        const text = r.newName !== undefined
+            ? `Layer renamed to: ${r.newName}\nResult: ${JSON.stringify(result)}`
+            : `Layer renamed\nResult: ${JSON.stringify(result)}`;
         return {
             content: [
                 {
                     type: 'text',
-                    text: `Layer renamed to: ${name}\nResult: ${JSON.stringify(result)}`,
+                    text,
                 },
             ],
             structuredContent: result,
@@ -675,9 +720,13 @@ async function duplicateLayer(connection, snippetClient, rawArgs) {
         };
     }
 }
-async function layerViaCopy(connection, snippetClient) {
+async function layerViaCopy(connection, snippetClient, rawArgs) {
     try {
-        const script = await snippetClient.build('layerViaCopy');
+        const args = validateArgs(copyToNewLayerSchema, rawArgs);
+        const intoActiveGroup = args.into_active_group ?? false;
+        const script = await snippetClient.build('layerViaCopy', {
+            into_active_group: intoActiveGroup,
+        });
         const result = (await runScript(connection, script));
         return {
             content: [

package/dist/tools/layer-tools.js

@@ -86,6 +86,11 @@ const addFillLayerSchema = {
         red: { type: 'integer', description: 'Solid color red (0-255).', minimum: 0, maximum: 255 },
         green: { type: 'integer', description: 'Solid color green (0-255).', minimum: 0, maximum: 255 },
         blue: { type: 'integer', description: 'Solid color blue (0-255).', minimum: 0, maximum: 255 },
+        into_active_group: {
+            type: 'boolean',
+            description: "Photoshop's Mk-contentLayer descriptor carries no placement target, so with a GROUP active it would natively nest the new fill layer INSIDE that group. Default false hoists the new layer back out so it lands above the active layer/group as a sibling. Pass true to keep it nested inside the active group instead.",
+            default: false,
+        },
     },
     required: ['red', 'green', 'blue'],
 };
@@ -111,6 +116,11 @@ export function createLayerTools(connection, snippetClient) {
                     properties: {
                         created: { type: 'boolean' },
                         layerName: { type: 'string' },
+                        parent_path: {
+                            type: ['array', 'null'],
+                            items: { type: 'string' },
+                            description: 'The containing-group name chain (outermost first), empty array at the document root.',
+                        },
                         context: { type: 'object' },
                     },
                 },
@@ -188,7 +198,7 @@ export function createLayerTools(connection, snippetClient) {
         {
             tool: {
                 name: 'ps_add_fill_layer',
-                description: 'Add a non-destructive SOLID COLOR fill layer (an editable, re-colorable content layer — distinct from ps_fill_layer, which bakes color into the active pixel layer). The new fill layer becomes active. Use for color washes, base backgrounds, and clipped color overlays. (Gradient and pattern fill types are planned.)',
+                description: "Add a non-destructive SOLID COLOR fill layer (an editable, re-colorable content layer — distinct from ps_fill_layer, which bakes color into the active pixel layer). Hoisted out of the active layer's group by default even though Photoshop's own Mk-contentLayer placement rule would otherwise nest it INSIDE that group (pass into_active_group:true to keep that native nesting). The new fill layer becomes active. Use for color washes, base backgrounds, and clipped color overlays. (Gradient and pattern fill types are planned.)",
                 inputSchema: addFillLayerSchema,
                 outputSchema: {
                     type: 'object',
@@ -197,6 +207,15 @@ export function createLayerTools(connection, snippetClient) {
                         fill_type: { type: 'string' },
                         color: { type: 'object' },
                         layer_name: { type: 'string' },
+                        hoisted: {
+                            type: 'boolean',
+                            description: 'True when the new layer had to be moved back out of the previously-active group to honor into_active_group:false (the default). False when it landed correctly on its own, or when the move-back itself failed — check the layer tree if this matters and hoisted is false.',
+                        },
+                        parent_path: {
+                            type: ['array', 'null'],
+                            items: { type: 'string' },
+                            description: 'The containing-group name chain (outermost first), empty array at the document root.',
+                        },
                         context: { type: 'object' },
                     },
                 },
@@ -359,7 +378,13 @@ async function addFillLayer(connection, snippetClient, rawArgs) {
         const red = args.red;
         const green = args.green;
         const blue = args.blue;
-        const script = await snippetClient.build('addFillLayer', { red, green, blue });
+        const intoActiveGroup = args.into_active_group ?? false;
+        const script = await snippetClient.build('addFillLayer', {
+            red,
+            green,
+            blue,
+            into_active_group: intoActiveGroup,
+        });
         const result = await runScript(connection, script);
         return {
             content: [

package/dist/tools/preview-tools.js

@@ -4,6 +4,7 @@ import { jsLit, jsNum } from '../utils/jsx.js';
 import { runScript } from '../utils/run-script.js';
 import { TempDir, userOwnedTempRoot } from '../utils/temp.js';
 import { validateArgs } from '../utils/validate.js';
+import { ANNOTATED_PREVIEW_TIMEOUT_MS } from '../utils/operation-timeouts.js';
 const COLOR_NAME_HEX = {
     red: '#FF0000',
     blue: '#0066FF',
@@ -836,7 +837,7 @@ async function getPreview(connection, rawArgs) {
           throw e;
         }
       `;
-            const execTimeoutMs = annotations.length > 0 ? 90000 : undefined;
+            const execTimeoutMs = annotations.length > 0 ? ANNOTATED_PREVIEW_TIMEOUT_MS : undefined;
             const result = (await runScript(connection, script, execTimeoutMs));
             const bytes = await readFile(tempPath);
             const base64 = bytes.toString('base64');

package/dist/tools/selection-tools.js

@@ -4,6 +4,7 @@ import { TempDir } from '../utils/temp.js';
 import { validateArgs } from '../utils/validate.js';
 import { OnnxLandmarkDetectionClient } from '../detection/landmark-detection-client.js';
 import { resolveExpectedPlacement, PLACEMENT_SCHEMA } from '../perception/grounding-locate.js';
+import { SELECT_SUBJECT_TIMEOUT_MS, SELECT_SKY_TIMEOUT_MS } from '../utils/operation-timeouts.js';
 export const SELECTION_TYPE_ENUM = ['replace', 'add', 'subtract', 'intersect'];
 export const selectionTypeFragment = {
     type: 'string',
@@ -778,7 +779,7 @@ async function selectSubject(connection, snippetClient, rawArgs) {
         const sampleAllLayers = args.sample_all_layers ?? true;
         const selectionType = normalizeSelectionType(args.selection_type);
         const script = await snippetClient.build('selectSubject', { sampleAllLayers, selectionType });
-        const result = await runScript(connection, script, 120000);
+        const result = await runScript(connection, script, SELECT_SUBJECT_TIMEOUT_MS);
         return {
             content: [{ type: 'text', text: `Select Subject (${selectionType}) complete` }],
             structuredContent: result,
@@ -802,7 +803,7 @@ async function selectSky(connection, snippetClient, rawArgs) {
         const sampleAllLayers = args.sample_all_layers ?? true;
         const selectionType = normalizeSelectionType(args.selection_type);
         const script = await snippetClient.build('selectSky', { sampleAllLayers, selectionType });
-        const result = await runScript(connection, script, 120000);
+        const result = await runScript(connection, script, SELECT_SKY_TIMEOUT_MS);
         return {
             content: [{ type: 'text', text: `Select Sky (${selectionType}) complete` }],
             structuredContent: result,

package/dist/tools/shape-tools.js

@@ -75,6 +75,11 @@ const shapeInputSchema = {
             ...rgbColorFragment,
             description: 'rectangle/ellipse stroke color when stroke_width>0. RGB 0-255. Default black.',
         },
+        into_active_group: {
+            type: 'boolean',
+            description: "Photoshop's Mk-contentLayer descriptor carries no placement target, so with a GROUP active it would natively nest the new shape layer INSIDE that group. Default false hoists the new layer back out so it lands above the active layer/group as a sibling. Pass true to keep it nested inside the active group instead.",
+            default: false,
+        },
     },
     required: ['type'],
 };
@@ -83,7 +88,7 @@ export function createShapeTools(connection, snippetClient, client = new OnnxLan
         {
             tool: {
                 name: 'ps_shape',
-                description: 'Draw a vector SHAPE layer — `rectangle` (optionally rounded via corner_radius), `ellipse`, or `line` — filled with a solid color, optionally stroked. Aim it EITHER by anchor-relational `placement` (preferred: name anchors + a relation and the resolver computes the geometry, verified by an objective gate — no pixel-guessing; rectangle/ellipse ← a region relation, line ← a path relation) OR by ABSOLUTE document pixels (top-left origin: rectangle/ellipse take left/top/right/bottom; line takes start_x/start_y → end_x/end_y plus weight — you must know the pixel positions, so prefer the anchor-relational `placement` path above and verify the result with a preview). Creates a new vector layer (non-destructive — delete it to remove). (AM-only; verified live on PS 27.2.0.)',
+                description: "Draw a vector SHAPE layer — `rectangle` (optionally rounded via corner_radius), `ellipse`, or `line` — filled with a solid color, optionally stroked. Hoisted out of the active layer's group by default even though the underlying Mk-contentLayer descriptor carries no placement target and would otherwise nest the new layer INSIDE that group (pass into_active_group:true to keep that native nesting). Aim it EITHER by anchor-relational `placement` (preferred: name anchors + a relation and the resolver computes the geometry, verified by an objective gate — no pixel-guessing; rectangle/ellipse ← a region relation, line ← a path relation) OR by ABSOLUTE document pixels (top-left origin: rectangle/ellipse take left/top/right/bottom; line takes start_x/start_y → end_x/end_y plus weight — you must know the pixel positions, so prefer the anchor-relational `placement` path above and verify the result with a preview). Creates a new vector layer (non-destructive — delete it to remove). (AM-only; verified live on PS 27.2.0.)",
                 inputSchema: shapeInputSchema,
                 outputSchema: {
                     type: 'object',
@@ -92,6 +97,15 @@ export function createShapeTools(connection, snippetClient, client = new OnnxLan
                         shape_type: { type: 'string' },
                         layer_name: { type: 'string' },
                         stroked: { type: 'boolean' },
+                        hoisted: {
+                            type: 'boolean',
+                            description: 'True when the new layer had to be moved back out of the previously-active group to honor into_active_group:false (the default). False when it landed correctly on its own, or when the move-back itself failed — check the layer tree if this matters and hoisted is false.',
+                        },
+                        parent_path: {
+                            type: ['array', 'null'],
+                            items: { type: 'string' },
+                            description: 'The containing-group name chain (outermost first), empty array at the document root.',
+                        },
                         placement: {
                             type: 'object',
                             description: 'Present when anchor-relational placement was used: the resolved geometry + gate verdict.',
@@ -174,6 +188,7 @@ async function createShape(connection, snippetClient, client, rawArgs) {
         else
             params.weight = args.weight ?? 4;
         colorParams(args.fill_color, 'fill', params);
+        params.into_active_group = args.into_active_group ?? false;
         if (type !== 'line') {
             params.strokeWidth = args.stroke_width ?? 0;
             colorParams(args.stroke_color, 'stroke', params);

package/dist/utils/operation-timeouts.js

@@ -0,0 +1,6 @@
+export const OPEN_DOCUMENT_TIMEOUT_MS = 120_000;
+export const OPEN_DOCUMENT_REPROBE_TIMEOUT_MS = 10_000;
+export const CAMERA_RAW_FILTER_TIMEOUT_MS = 120_000;
+export const SELECT_SUBJECT_TIMEOUT_MS = 120_000;
+export const SELECT_SKY_TIMEOUT_MS = 120_000;
+export const ANNOTATED_PREVIEW_TIMEOUT_MS = 90_000;

package/dist/utils/session-log.js

@@ -24,6 +24,7 @@ export const ERROR_CLASS_TABLE = [
     },
     { errorClass: 'layer_not_found', pattern: /layer .* not found|no layer named/i },
     { errorClass: 'ps_command_unavailable', pattern: /not currently available/i },
+    { errorClass: 'timeout', pattern: /timed? ?out|Script execution timeout|exceeded.*bytes/i },
     {
         errorClass: 'ps_modal_blocking',
         pattern: /modal.*dialog|dialog.*blocking|blocked.*modal|photoshop.*modal/i,
@@ -32,7 +33,6 @@ export const ERROR_CLASS_TABLE = [
         errorClass: 'ps_not_running',
         pattern: /CreateObject|photoshop.*not.*running|cannot connect.*photoshop|connection.*failed/i,
     },
-    { errorClass: 'timeout', pattern: /timed? ?out|Script execution timeout|exceeded.*bytes/i },
 ];
 export function classifyError(error) {
     if (error === undefined)

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.22.3';
+export const VERSION = '0.23.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "editmamei",
-  "version": "0.22.3",
+  "version": "0.23.0",
   "description": "Editmamei — Unlock Photoshop with natural-language photo editing (Community Edition)",
   "main": "dist/index.js",
   "type": "module",