editmamei 1.3.0 → 1.4.0

package/README.md

@@ -47,7 +47,7 @@ Then restart your AI client and ask it: _"Is Photoshop connected?"_
 
 Prefer not to use a terminal? Claude Desktop users can install the one-click [`.mcpb` extension](https://github.com/editmamei/editmamei/releases/latest/download/editmamei.mcpb) directly (no system Node required, Claude Desktop ships its own runtime). Full walkthrough in the [install guide](docs/installation.md).
 
-**Requirements:** Adobe Photoshop 2026 (v27.x), Windows 10/11 or macOS 12+, Node.js 22+ (for the npm path), and an MCP-compatible AI client (Claude Desktop, Cursor, Claude Code).
+**Requirements:** Adobe Photoshop 2026 (v27.x), Windows 10/11 or macOS 13+, Node.js 22+ (for the npm path), and an MCP-compatible AI client (Claude Desktop, Cursor, Claude Code).
 
 ## A session, end to end
 
@@ -75,14 +75,14 @@ These are the choices that shape the surface, and the reason an AI assistant can
 
 ## Tool surface
 
-**79 tools across 16 capability groups** (59 Community, 20 Pro). Every tool is namespaced `ps_*` and discoverable at runtime via `tools/list`. Community tools ship in both editions; Pro tools unlock with a license.
+**82 tools across 16 capability groups** (62 Community, 20 Pro). Every tool is namespaced `ps_*` and discoverable at runtime via `tools/list`. Community tools ship in both editions; Pro tools unlock with a license.
 
 | Group | Edition | Tools |
 | --- | --- | --- |
 | **Core** | Community | `ping` · `overview` · `list_capabilities` · `undo` · `redo` · `report_problem` |
 | **Inspect** | Community | `inspect` · `get_preview` |
 | **Verify** | Community | `get_histogram` · `compare_regions` · `get_layer_bounds_diff` · `get_selection_preview` |
-| **Document & canvas** | Community | `create_document` · `open_document` · `close_document` · `save_psd` · `export` · `place_image` · `resize_image` · `crop_document` · `convert_image_mode` · `transform_canvas` · `guides` |
+| **Document & canvas** | Community | `document` · `create_document` · `open_document` · `close_document` · `save_psd` · `export` · `place_image` · `resize_image` · `crop_document` · `convert_image_mode` · `transform_canvas` · `guides` |
 | **Selection** | Community | `select` · `modify_selection` · `selection_channel` |
 | **Adjustments** | Community | `add_adjustment_layer` · `apply_adjustment` |
 | **Filters** | Community | `filter` |
@@ -91,7 +91,8 @@ These are the choices that shape the surface, and the reason an AI assistant can
 | **Masks & paths** | Community | `layer_mask` · `clipping_mask` · `path` · `vector_mask` · `apply_image` · `calculations` |
 | **Type** | Community | `text` |
 | **Perception** | Community | `detect` · `read_scene` · `select_by_reference` |
-| **AI selection** | Community | `select_subject` · `select_sky` |
+| **AI selection** | Community | `select_subject` · `select_sky` · `replace_sky` |
+| **Automation** | Community | `sequence` |
 | **AI selection** | Pro | `select_subject_instance` · `select_object` |
 | **Filters** | Pro | `apply_camera_raw` |
 | **Layers (warp)** | Pro | `warp_layer` |
@@ -119,7 +120,7 @@ npm run build
 npm test
 ```
 
-You need Node.js 22+ and a Go toolchain (the build compiles the `editmamei-core` binary that generates Photoshop scripts). The build warns instead of failing when Go is missing, so you can still run the test suite; set `EDITMAMEI_CORE_BIN` to a prebuilt binary if you would rather not install Go.
+You need Node.js 22+ and Go 1.21+ (the build compiles the `editmamei-core` binary that generates Photoshop scripts; it needs Go 1.27, which Go fetches for you from 1.21 on). The build warns instead of failing when Go is missing, so you can still run the test suite; set `EDITMAMEI_CORE_BIN` to a prebuilt binary if you would rather not install Go.
 
 The test suite runs without Photoshop. It verifies the ExtendScript Editmamei generates, never that Photoshop accepted it, so live verification against a real Photoshop is a separate step.
 

package/dist/core/server.js

@@ -8,7 +8,7 @@ import { groupOf, GROUPS } from './tool-groups.js';
 import { EDITION } from '../edition.js';
 import { VERSION } from '../version.js';
 import { Session } from './session.js';
-import { SessionLog, classifyError } from '../utils/session-log.js';
+import { SessionLog, classifyError, NO_ERROR_TEXT_CLASS } from '../utils/session-log.js';
 import { loadSettings, applyTelemetryEnvOverrides, applyUpdateCheckEnvOverride, } from './settings.js';
 import { TelemetryClient } from '../telemetry/client.js';
 import { resolveInstallChannel } from '../install-channel.js';
@@ -107,7 +107,7 @@ export class EditmameiServer {
                 const telemetrySuccess = entry.tool === 'ps_ping' && this.lastPingReachedPs === false ? false : entry.success;
                 const isPingDowngrade = entry.tool === 'ps_ping' && !telemetrySuccess && entry.error === undefined;
                 const errorClass = classifyError(entry.error) ??
-                    (telemetrySuccess ? null : isPingDowngrade ? 'ps_not_running' : 'other');
+                    (telemetrySuccess ? null : isPingDowngrade ? 'ps_not_running' : NO_ERROR_TEXT_CLASS);
                 this.telemetry.recordCall({
                     tool: entry.tool,
                     success: telemetrySuccess,
@@ -117,7 +117,7 @@ export class EditmameiServer {
                 if (!telemetrySuccess) {
                     this.telemetry.recordDiagnostic({
                         tool: entry.tool,
-                        error_class: errorClass ?? 'other',
+                        error_class: errorClass ?? NO_ERROR_TEXT_CLASS,
                         error_message: entry.error ||
                             (isPingDowngrade
                                 ? 'ps_ping did not reach Photoshop'

package/dist/core/tool-groups.js

@@ -76,8 +76,8 @@ export const GROUPS = {
     },
     automation: {
         id: 'automation',
-        label: 'Automation (Pro)',
-        purpose: 'Batch files, play recorded Actions, and the ExtendScript escape hatch (Pro).',
+        label: 'Automation',
+        purpose: 'Run several tool calls in one round trip (community), plus batch files, recorded Actions, and the ExtendScript escape hatch (Pro).',
     },
 };
 export const TOOL_GROUPS = {
@@ -112,7 +112,6 @@ export const TOOL_GROUPS = {
     ps_select_sky: 'select_ai',
     ps_select_subject_instance: 'select_ai',
     ps_select_object: 'select_ai',
-    ps_select_focus_area: 'select_ai',
     ps_replace_sky: 'select_ai',
     ps_add_adjustment_layer: 'adjust',
     ps_apply_adjustment: 'adjust',
@@ -166,6 +165,7 @@ export const TOOL_GROUPS = {
     ps_template_verify: 'templates',
     ps_template_recall: 'templates',
     ps_template_delete: 'templates',
+    ps_sequence: 'automation',
     ps_list_actions: 'automation',
     ps_play_action: 'automation',
     ps_execute_script: 'automation',

package/dist/core/tool-registry.js

@@ -1,4 +1,6 @@
 import { Logger } from '../utils/logger.js';
+import { getToolTimeoutMs } from '../utils/operation-timeouts.js';
+import { budgetContextFor, runWithToolBudget } from '../utils/tool-budget-context.js';
 export class ToolRegistry {
     logger;
     tools;
@@ -46,7 +48,7 @@ export class ToolRegistry {
         let error;
         let result;
         try {
-            result = await definition.handler(args);
+            result = await runWithToolBudget(budgetContextFor(name, getToolTimeoutMs(name)), () => definition.handler(args));
             if (result?.isError) {
                 success = false;
                 const firstText = result.content?.find((c) => c.type === 'text');

package/dist/core/tool-tiers.js

@@ -6,6 +6,7 @@ export const TOOL_TIERS = {
     ps_play_action: 'pro',
     ps_execute_script: 'pro',
     ps_batch: 'pro',
+    ps_sequence: 'community',
     ps_add_adjustment_layer: 'community',
     ps_apply_adjustment: 'community',
     ps_document: 'community',
@@ -68,7 +69,6 @@ export const TOOL_TIERS = {
     ps_select_sky: 'community',
     ps_select_subject_instance: 'pro',
     ps_select_object: 'pro',
-    ps_select_focus_area: 'dev',
     ps_replace_sky: 'community',
     ps_modify_selection: 'community',
     ps_get_selection_preview: 'community',

package/dist/kernel/kernel.js

@@ -35,6 +35,7 @@ export class Kernel {
             abi: KERNEL_ABI,
             registerTools: (defs) => this.registry.registerAll(defs),
             invokeTool: (name, args) => this.invokeTool(name, args),
+            hasTool: (name) => this.registry.get(name) !== undefined,
             connection: this.connection,
             executeScript: (innerBody, timeoutMs) => runScript(this.connection, innerBody, timeoutMs),
             snippet: this.snippetFor(manifest),

package/dist/modules/ce/index.js

@@ -30,6 +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';
+import { createSequenceTools } from '../../tools/sequence-tools.js';
 export const ceFactories = [
     createDocumentTools,
     createLayerTools,
@@ -67,6 +68,12 @@ export const ceModule = {
         const defs = [
             ...ceFactories.flatMap((f) => f(connection, snippet)),
             ...createSceneTools(connection, snippet, { invokeTool: host.invokeTool }),
+            ...createSequenceTools(host.invokeTool, (name) => {
+                if (!host.hasTool) {
+                    throw new Error(`cannot validate "${name}" — this host does not expose hasTool`);
+                }
+                return host.hasTool(name);
+            }),
         ].filter((def) => isToolAllowedInEdition(def.tool.name, EDITION));
         host.registerTools(defs);
     },

package/dist/perception/facets.js

@@ -41,7 +41,7 @@ export function estimateHorizon(rowMeans, docHeight, pick, mainSubjectBox, prima
     const split = pick.bright_fraction;
     const splitConfidence = Math.max(0, Math.min(1, 1 - Math.abs(0.5 - split) * 2)) * 0.6 + 0.2;
     if (!rowMeans || rowMeans.length === 0) {
-        return { y: Math.round(docHeight / 3), placement: 1 / 3, confidence: 0.2 };
+        return { detected: false, reason: 'no-row-profile' };
     }
     const R = rowMeans.length;
     let crossRow = -1;
@@ -52,14 +52,15 @@ export function estimateHorizon(rowMeans, docHeight, pick, mainSubjectBox, prima
         }
     }
     if (crossRow <= 0) {
-        return { y: Math.round(docHeight / 3), placement: 1 / 3, confidence: 0.2 };
+        return { detected: false, reason: 'no-luminance-crossing' };
     }
     const y = Math.round((crossRow / R) * docHeight);
     if ((mainSubjectBox && isDominantSubjectCrossing(y, docHeight, mainSubjectBox)) ||
         (primaryFaceBox && isPortraitFaceCrossing(y, docHeight, primaryFaceBox))) {
-        return { y: Math.round(docHeight / 3), placement: 1 / 3, confidence: 0.2 };
+        return { detected: false, reason: 'dominant-subject' };
     }
     return {
+        detected: true,
         y,
         placement: y / docHeight,
         confidence: Math.max(0, Math.min(1, splitConfidence)),

package/dist/perception/region-scorer.js

@@ -49,7 +49,7 @@ export function buildRegionSignals(info, scene) {
         centroidY = (bounds.top + bounds.bottom) / 2 / docH;
         touchesBottom = bounds.bottom >= docH * 0.97;
         touchesTop = bounds.top <= docH * 0.03;
-        if (scene.horizonConfidence > 0) {
+        if (scene.horizonConfidence > 0 && scene.horizonY !== null) {
             lowerEdgeAlign = 1 - Math.min(1, Math.abs(bounds.bottom - scene.horizonY) / docH);
             upperEdgeAlign = 1 - Math.min(1, Math.abs(bounds.top - scene.horizonY) / docH);
         }

package/dist/perception/scene-model.js

@@ -142,7 +142,7 @@ export async function buildSceneModel(connection, snippet, client, opts = {}) {
             recipe: { kind: 'posterize_region', levels: 3, sample: 'below_horizon' },
         },
     ];
-    const composition = computeComposition(mainBox, allBoxes, docW, docH, horizon.placement);
+    const composition = computeComposition(mainBox, allBoxes, docW, docH, horizon.detected ? horizon.placement : null);
     const backends = {
         faces: det.result.backends.faces,
         objects: det.result.backends.objects,

package/dist/perception/select-recipes.js

@@ -58,8 +58,8 @@ function sceneCtx(model) {
     return {
         docW: model.doc.width,
         docH: model.doc.height,
-        horizonY: model.horizon.y,
-        horizonConfidence: model.horizon.confidence,
+        horizonY: model.horizon.detected ? model.horizon.y : null,
+        horizonConfidence: model.horizon.detected ? model.horizon.confidence : 0,
         indoorObjectCount,
     };
 }
@@ -490,7 +490,18 @@ async function resolveFaceFeature(connection, snippet, target, feature, opts) {
     };
 }
 async function resolveAboveHorizon(connection, snippet, model, composition) {
-    const y = Math.max(1, Math.min(model.doc.height, model.horizon.y));
+    const horizon = model.horizon;
+    if (!horizon.detected) {
+        return {
+            target: 'above_horizon',
+            method: 'none',
+            passed: false,
+            confidence: 0,
+            reasons: [`no horizon was measured in this frame (${horizon.reason})`],
+            detail: { horizon_detected: false, horizon_reason: horizon.reason },
+        };
+    }
+    const y = Math.max(1, Math.min(model.doc.height, horizon.y));
     const result = (await runScript(connection, await snippet.build('selectRectangle', {
         left: 0,
         top: 0,

package/dist/platform/launch-readiness.js

@@ -0,0 +1,25 @@
+const DEFAULT_POLL_INTERVAL_MS = 250;
+export const LAUNCH_READY_MAX_WAIT_MS = 5_000;
+function defaultSleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms).unref();
+    });
+}
+export async function waitForLaunchReady(isReady, options = {}) {
+    const intervalMs = options.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const maxWaitMs = options.maxWaitMs ?? LAUNCH_READY_MAX_WAIT_MS;
+    const sleep = options.sleep ?? defaultSleep;
+    const isAborted = options.isAborted ?? (() => false);
+    const now = options.now ?? Date.now;
+    const deadline = now() + maxWaitMs;
+    while (now() < deadline) {
+        if (isAborted())
+            return false;
+        if (await isReady())
+            return true;
+        if (now() >= deadline)
+            break;
+        await sleep(intervalMs);
+    }
+    return false;
+}

package/dist/platform/macos-runner.js

@@ -2,12 +2,14 @@ import { exec, spawn } from 'child_process';
 import { promisify } from 'util';
 import { Logger } from '../utils/logger.js';
 import { TempDir } from '../utils/temp.js';
+import { DEFAULT_SCRIPT_TIMEOUT_MS } from '../utils/operation-timeouts.js';
 import { ScriptQueue } from './script-queue.js';
 import { runChildWithTimeout } from './run-child.js';
 import { decodeScriptResult } from './script-result.js';
+import { waitForLaunchReady } from './launch-readiness.js';
 const execAsync = promisify(exec);
-const DEFAULT_SCRIPT_TIMEOUT_MS = 30_000;
-const LAUNCH_GRACE_MS = 5_000;
+const LAUNCH_PROBE_TIMEOUT_MS = 2_000;
+const IS_RUNNING_EXEC_TIMEOUT_MS = 3_000;
 const UNSAFE_IN_APPLESCRIPT_LITERAL = /["\\\r\n\t]/;
 export class MacOSScriptRunner {
     logger = new Logger('MacOSScriptRunner');
@@ -69,7 +71,9 @@ end timeout`;
     }
     async isRunning() {
         try {
-            const { stdout } = await execAsync('pgrep -f "Adobe Photoshop"');
+            const { stdout } = await execAsync('pgrep -f "Adobe Photoshop"', {
+                timeout: IS_RUNNING_EXEC_TIMEOUT_MS,
+            });
             return stdout.trim().length > 0;
         }
         catch {
@@ -81,14 +85,20 @@ end timeout`;
             this.logger.info('Launching Photoshop', executablePath);
             const child = spawn('open', ['-a', executablePath], { detached: true, stdio: 'ignore' });
             child.unref();
-            const grace = setTimeout(() => {
-                grace.unref();
-                resolve();
-            }, LAUNCH_GRACE_MS);
+            let aborted = false;
             child.on('error', (error) => {
-                clearTimeout(grace);
+                aborted = true;
                 reject(new Error(`Could not launch Photoshop at ${executablePath}: ${error.message}`));
             });
+            const probe = () => this.run("'pong';", LAUNCH_PROBE_TIMEOUT_MS)
+                .then(() => true)
+                .catch(() => false);
+            waitForLaunchReady(probe, { isAborted: () => aborted })
+                .catch(() => false)
+                .then(() => {
+                if (!aborted)
+                    resolve();
+            });
         });
     }
 }

package/dist/platform/script-queue.js

@@ -8,23 +8,7 @@ export class ScriptQueue {
     }
     enqueue(run, timeout) {
         return new Promise((resolve, reject) => {
-            const task = {
-                run,
-                resolve,
-                reject,
-                cancelled: false,
-                settled: false,
-                timeoutId: null,
-            };
-            task.timeoutId = setTimeout(() => {
-                if (task.settled)
-                    return;
-                task.cancelled = true;
-                task.settled = true;
-                task.timeoutId = null;
-                reject(new Error('Script execution timeout'));
-            }, timeout + QUEUE_SLACK_MS);
-            this.queue.push(task);
+            this.queue.push({ run, timeout, resolve, reject, settled: false, timeoutId: null });
             void this.processQueue();
         });
     }
@@ -45,8 +29,10 @@ export class ScriptQueue {
         try {
             while (this.queue.length > 0) {
                 const task = this.queue.shift();
-                if (task.cancelled)
-                    continue;
+                task.timeoutId = setTimeout(() => {
+                    this.settleTask(task, () => task.reject(new Error('Script execution timeout')));
+                }, task.timeout + QUEUE_SLACK_MS);
+                task.timeoutId.unref?.();
                 try {
                     const result = await task.run();
                     this.settleTask(task, () => task.resolve(result));

package/dist/platform/windows-runner.js

@@ -2,12 +2,14 @@ import { exec, spawn } from 'child_process';
 import { promisify } from 'util';
 import { Logger } from '../utils/logger.js';
 import { TempDir } from '../utils/temp.js';
+import { DEFAULT_SCRIPT_TIMEOUT_MS } from '../utils/operation-timeouts.js';
 import { ScriptQueue } from './script-queue.js';
 import { runChildWithTimeout } from './run-child.js';
 import { decodeScriptResult } from './script-result.js';
+import { waitForLaunchReady } from './launch-readiness.js';
 const execAsync = promisify(exec);
-const DEFAULT_SCRIPT_TIMEOUT_MS = 30_000;
-const LAUNCH_GRACE_MS = 5_000;
+const LAUNCH_PROBE_TIMEOUT_MS = 2_000;
+const IS_RUNNING_EXEC_TIMEOUT_MS = 3_000;
 export class WindowsScriptRunner {
     logger = new Logger('WindowsScriptRunner');
     queue = new ScriptQueue(this.logger);
@@ -59,7 +61,9 @@ End If
     }
     async isRunning() {
         try {
-            const { stdout } = await execAsync('tasklist /FI "IMAGENAME eq Photoshop.exe"');
+            const { stdout } = await execAsync('tasklist /FI "IMAGENAME eq Photoshop.exe"', {
+                timeout: IS_RUNNING_EXEC_TIMEOUT_MS,
+            });
             return stdout.toLowerCase().includes('photoshop.exe');
         }
         catch {
@@ -71,14 +75,20 @@ End If
             this.logger.info('Launching Photoshop', executablePath);
             const child = spawn(executablePath, [], { detached: true, stdio: 'ignore' });
             child.unref();
-            const grace = setTimeout(() => {
-                grace.unref();
-                resolve();
-            }, LAUNCH_GRACE_MS);
+            let aborted = false;
             child.on('error', (error) => {
-                clearTimeout(grace);
+                aborted = true;
                 reject(new Error(`Could not launch Photoshop at ${executablePath}: ${error.message}`));
             });
+            const probe = () => this.run("'pong';", LAUNCH_PROBE_TIMEOUT_MS)
+                .then(() => true)
+                .catch(() => false);
+            waitForLaunchReady(probe, { isAborted: () => aborted })
+                .catch(() => false)
+                .then(() => {
+                if (!aborted)
+                    resolve();
+            });
         });
     }
 }

package/dist/telemetry/client.js

@@ -2,7 +2,7 @@ import { Logger } from '../utils/logger.js';
 import { EDITION } from '../edition.js';
 import { VERSION } from '../version.js';
 import { resolveInstallChannel } from '../install-channel.js';
-import { buildDiagnosticEvent, buildModuleStatus, buildSessionStart, buildSessionSummary, buildUsageEvent, dayBucket, isContentSafe, PS_VERSION_UNKNOWN, } from './events.js';
+import { buildDiagnosticEvent, buildModuleStatus, buildSessionStart, buildSessionSummary, buildUsageEvent, dayBucket, normalizeDayBucket, isContentSafe, PS_VERSION_UNKNOWN, } from './events.js';
 import { sanitizeMessage, sanitizeSnippet, sanitizeStderrTail } from './sanitize.js';
 import { httpTransport, resolveEndpoint } from './transport.js';
 import { appendOutboxSync, clearOutbox, clearSessionState, readOutbox, readSessionState, writeSessionStateSync, } from './outbox.js';
@@ -32,6 +32,7 @@ export class TelemetryClient {
     distinctTools = new Set();
     anyFailures = false;
     lastSessionPersistMs = 0;
+    startDayBucket = null;
     constructor(opts) {
         this.settings = opts.settings;
         this.transport = opts.transport ?? httpTransport();
@@ -70,6 +71,7 @@ export class TelemetryClient {
     recordCall(call) {
         if (!this.active || !this.settings.telemetry.usage)
             return;
+        this.ensureStartDayBucket();
         this.toolCallCount += 1;
         this.distinctTools.add(call.tool);
         if (!call.success)
@@ -81,6 +83,11 @@ export class TelemetryClient {
         const v = this.dims.getPsVersion();
         return v && v.length > 0 ? v : PS_VERSION_UNKNOWN;
     }
+    ensureStartDayBucket() {
+        if (this.startDayBucket === null)
+            this.startDayBucket = dayBucket(this.now());
+        return this.startDayBucket;
+    }
     persistSessionStateThrottled() {
         const nowMs = this.now().getTime();
         if (this.lastSessionPersistMs !== 0 &&
@@ -90,7 +97,7 @@ export class TelemetryClient {
         this.lastSessionPersistMs = nowMs;
         const state = {
             install_id: this.dims.install_id,
-            ts_bucket: dayBucket(this.now()),
+            ts_bucket: this.ensureStartDayBucket(),
             editmamei_version: this.dims.editmamei_version,
             edition: this.dims.edition,
             platform: this.dims.platform,
@@ -170,7 +177,7 @@ export class TelemetryClient {
                 tool_call_count: this.toolCallCount,
                 distinct_tools: this.distinctTools.size,
                 any_failures: this.anyFailures,
-            }, this.now()));
+            }, this.ensureStartDayBucket(), this.now()));
         }
         if (this.queue.length > 0) {
             appendOutboxSync(this.restampPsVersion(this.queue.splice(0)).filter(isContentSafe), this.outboxOpts);
@@ -225,7 +232,7 @@ function summaryFromState(s) {
         v: 2,
         type: 'session_summary',
         install_id: s.install_id,
-        ts_bucket: s.ts_bucket,
+        ts_bucket: normalizeDayBucket(s.ts_bucket, new Date()),
         editmamei_version: s.editmamei_version,
         edition: s.edition,
         platform: s.platform,

package/dist/telemetry/events.js

@@ -10,6 +10,9 @@ export function normalizeErrorClass(value) {
         .slice(0, 48);
     return cleaned.length > 0 ? cleaned : 'other';
 }
+export function normalizeDayBucket(value, now) {
+    return /^\d{4}-\d{2}-\d{2}$/.test(value) ? value : dayBucket(now);
+}
 function psVersionOf(dims) {
     const v = dims.getPsVersion();
     return v && v.length > 0 ? v : PS_VERSION_UNKNOWN;
@@ -30,12 +33,12 @@ export function buildUsageEvent(dims, call, now) {
         duration_ms: call.duration_ms,
     };
 }
-export function buildSessionSummary(dims, summary, now) {
+export function buildSessionSummary(dims, summary, tsBucket, now) {
     return {
         v: TELEMETRY_SCHEMA_VERSION,
         type: 'session_summary',
         install_id: dims.install_id,
-        ts_bucket: dayBucket(now),
+        ts_bucket: normalizeDayBucket(tsBucket, now),
         editmamei_version: dims.editmamei_version,
         edition: dims.edition,
         platform: dims.platform,

package/dist/tools/detection-tools.js

@@ -45,8 +45,8 @@ const detectSchema = {
         },
         annotate: {
             type: 'boolean',
-            default: true,
-            description: 'Return an annotated preview with the detected boxes drawn (faces cyan, objects magenta) so you can visually confirm the detections.',
+            default: false,
+            description: 'Also return an annotated preview JPEG with the detected boxes drawn (faces cyan, objects magenta). Default false: the labeled boxes returned by this call are already complete on their own — ask for the image only when you actually need to visually confirm a detection.',
         },
     },
 };
@@ -76,7 +76,7 @@ async function detect(connection, client, rawArgs, detectDeps) {
     try {
         const args = validateArgs(detectSchema, rawArgs);
         const target = args.target ?? 'both';
-        const annotate = args.annotate ?? true;
+        const annotate = args.annotate ?? false;
         const wantFaces = target === 'faces' || target === 'both';
         const wantObjects = target === 'objects' || target === 'both';
         const detectKey = JSON.stringify({
@@ -174,7 +174,7 @@ export function createDetectionTools(connection, _snippetClient, client = new On
         {
             tool: {
                 name: 'ps_detect',
-                description: 'The cheap, narrow read: labeled bounding boxes only — faces and/or COCO-80 objects (person, dog, car, chair, sofa, …) in DOCUMENT-pixel space, plus an annotated preview for visual confirmation. LOCAL on-device computer vision; the image is never sent anywhere. Use this for real coordinates before a spatially-targeted edit when boxes are all you need — far more reliable than estimating positions from a preview. For the full scene model (regions, horizon, tonal zones, composition, and a menu of selectable named regions), use ps_read_scene instead. `target` selects faces / objects / both. Read-only: renders a throwaway duplicate, never modifies the working document. Boxes are [x1, y1, x2, y2]. Validate surprising results against the annotated image before acting on them.',
+                description: 'The cheap, narrow read: labeled bounding boxes only — faces and/or COCO-80 objects (person, dog, car, chair, sofa, …) in DOCUMENT-pixel space. LOCAL on-device computer vision; the image is never sent anywhere. Use this for real coordinates before a spatially-targeted edit when boxes are all you need — far more reliable than estimating positions from a preview. For the full scene model (regions, horizon, tonal zones, composition, and a menu of selectable named regions), use ps_read_scene instead. `target` selects faces / objects / both. Read-only: renders a throwaway duplicate, never modifies the working document. Boxes are [x1, y1, x2, y2]. Pass `annotate:true` for an annotated preview JPEG (faces cyan, objects magenta) when you need to visually confirm a surprising result.',
                 inputSchema: detectSchema,
                 outputSchema: {
                     type: 'object',

package/dist/tools/preview-tools.js

@@ -162,7 +162,7 @@ const histogramSchema = {
         channel: {
             type: 'string',
             enum: ['composite', 'red', 'green', 'blue', 'luminosity', 'gray'],
-            description: 'Which channel to read. "composite" (default) is the visible flattened image; if the active layer is an adjustment/fill/shape layer the tool transparently switches to a pixel layer to read it. "red"/"green"/"blue" require an RGB doc; "gray" a grayscale doc. "luminosity" dispatches per doc mode — Lab uses the Lightness channel (exact), Grayscale uses Gray (exact), RGB synthesizes a Rec.709 weighted approximation from R+G+B (mean is exact; stdev/median are approximations). The result\'s `channel` field annotates which path landed when a fallback was used.',
+            description: 'Which channel to read. "composite" (default) is the visible flattened image; if the active layer is an adjustment/fill/shape layer the tool transparently switches to a pixel layer to read it. "red"/"green"/"blue" require an RGB doc; "gray" a grayscale doc. "luminosity" dispatches per doc mode — Lab uses the Lightness channel (exact), Grayscale uses Gray (exact), and RGB reads the per-pixel luminance Photoshop reports, weighted 0.30/0.59/0.11, so its shape and any clipping or percentile read taken from it are sound. Note that weighting is not Rec.709, so a luminosity mean will not match one computed as 0.2126/0.7152/0.0722. A channel value naming a marginal mixture means the document histogram was unavailable and the read fell back to combining the channel histograms: that mean is still sound, its shape is not. The result\'s `channel` field annotates which path landed when a fallback was used.',
             default: 'composite',
         },
     },

package/dist/tools/scene-tools.js

@@ -71,8 +71,8 @@ const sceneSchema = {
     properties: {
         annotate: {
             type: 'boolean',
-            default: true,
-            description: 'Return an annotated preview with subject boxes (magenta), faces (cyan), and the horizon line (yellow) drawn so you can visually confirm the scene model.',
+            default: false,
+            description: 'Also return an annotated preview JPEG with subject boxes (magenta), faces (cyan), and the horizon line (yellow) drawn. Default false: the structured scene model returned by this call is already complete on its own — ask for the image only when you actually need to see the annotation drawn.',
         },
         refresh: {
             type: 'boolean',
@@ -130,7 +130,9 @@ function summarizeScene(model) {
     const parts = [
         `${model.subjects.length} subject(s)${subjStr ? ` (${subjStr})` : ''}`,
         `${model.faces.length} face(s)`,
-        `horizon at y=${model.horizon.y} (${Math.round(model.horizon.placement * 100)}% down, conf ${model.horizon.confidence.toFixed(2)})`,
+        model.horizon.detected
+            ? `horizon at y=${model.horizon.y} (${Math.round(model.horizon.placement * 100)}% down, conf ${model.horizon.confidence.toFixed(2)})`
+            : `no horizon measured (${model.horizon.reason})`,
         `sky ~${Math.round((model.regions.find((r) => r.kind === 'sky')?.coverage ?? 0) * 100)}%`,
     ];
     if (main && cell)
@@ -140,7 +142,7 @@ function summarizeScene(model) {
 async function scene(connection, snippet, client, rawArgs, proRefine, hasPro = false, detectDeps) {
     try {
         const args = validateArgs(sceneSchema, rawArgs);
-        const annotate = args.annotate ?? true;
+        const annotate = args.annotate ?? false;
         const refresh = args.refresh ?? false;
         const saveRegions = args.save_regions ?? false;
         const built = await buildSceneModel(connection, snippet, client, {
@@ -177,7 +179,7 @@ async function scene(connection, snippet, client, rawArgs, proRefine, hasPro = f
             try {
                 const exportH = built.exportImage.height || 0;
                 const sy = model.doc.height > 0 ? exportH / model.doc.height : 1;
-                const horizonExportY = Math.round(model.horizon.y * sy);
+                const horizonExportY = model.horizon.detected ? Math.round(model.horizon.y * sy) : null;
                 const annotated = annotateScene(built.decoded, built.rawFaces, built.rawObjects.map((o) => o.bbox), horizonExportY);
                 content.push({
                     type: 'image',
@@ -391,7 +393,7 @@ export function createSceneTools(connection, snippetClient, opts = {}) {
         {
             tool: {
                 name: 'ps_read_scene',
-                description: 'The full scene model — run this before a spatially-targeted edit, not the cheaper ps_detect: detected subjects (with the main one flagged) and faces in document pixels, a coarse sky/ground region map, the horizon line (y + placement + confidence), tonal zones (shadow/midtone/highlight bands + coverage), composition geometry (which thirds cell the subject sits in, balance, headroom), plus an annotated preview and the menu of selectable named regions. Built using LOCAL on-device vision + classical CV; the image never leaves the machine. Select regions by name with ps_select_by_reference instead of guessing a rectangle. Read-only: renders a throwaway duplicate. Perception is cached per document state, so repeated reads are cheap.',
+                description: 'The full scene model — run this before a spatially-targeted edit, not the cheaper ps_detect: detected subjects (with the main one flagged) and faces in document pixels, a coarse sky/ground region map, the horizon line (y + placement + confidence), tonal zones (shadow/midtone/highlight bands + coverage), composition geometry (which thirds cell the subject sits in, balance, headroom), and the menu of selectable named regions. The structured model is complete on its own — pass `annotate:true` for an annotated preview JPEG when you actually need to see it drawn. Built using LOCAL on-device vision + classical CV; the image never leaves the machine. Select regions by name with ps_select_by_reference instead of guessing a rectangle. Read-only: renders a throwaway duplicate. Perception is cached per document state, so repeated reads are cheap.',
                 inputSchema: sceneSchema,
                 outputSchema: {
                     type: 'object',