editmamei 0.23.0 → 1.0.0

package/dist/tools/adjustment-tools.js

@@ -1,5 +1,6 @@
 import { runScript } from '../utils/run-script.js';
 import { validateArgs } from '../utils/validate.js';
+import { toolErrorResult, runSnippetTool, applyToActiveLayerProp } from '../utils/tool-helpers.js';
 const addAdjustmentLayerSchema = {
     type: 'object',
     properties: {
@@ -422,9 +423,24 @@ const addAdjustmentLayerSchema = {
         gm_preset: {
             type: 'string',
             enum: ['black_to_white', 'sepia', 'tint'],
-            description: 'For type=gradient_map. Preset gradient. "black_to_white" is the canonical tonal B&W via gradient. "sepia" is a warm vintage tone. "tint" maps black→tint_color→white using gm_tint_color_hex. Custom gradient stops are not supported in v1 — record an Action for arbitrary gradients.',
+            description: 'For type=gradient_map. Preset gradient. "black_to_white" is the canonical tonal B&W via gradient. "sepia" is a warm vintage tone. "tint" maps black→tint_color→white using gm_tint_color_hex. For arbitrary color mappings pass gm_stops instead (overrides the preset).',
             default: 'black_to_white',
         },
+        gm_stops: {
+            type: 'array',
+            description: 'For type=gradient_map. Custom color stops overriding gm_preset — each {red,green,blue (0-255), location (0-100 shadows→highlights), midpoint (5-95, default 50)}. At least 2; sorted by location. E.g. a blue→orange stylized grade: [{red:20,green:40,blue:120,location:0},{red:250,green:150,blue:50,location:100}].',
+            items: {
+                type: 'object',
+                properties: {
+                    red: { type: 'integer', minimum: 0, maximum: 255 },
+                    green: { type: 'integer', minimum: 0, maximum: 255 },
+                    blue: { type: 'integer', minimum: 0, maximum: 255 },
+                    location: { type: 'number', minimum: 0, maximum: 100 },
+                    midpoint: { type: 'number', minimum: 5, maximum: 95, default: 50 },
+                },
+                required: ['red', 'green', 'blue', 'location'],
+            },
+        },
         gm_tint_color_hex: {
             type: 'string',
             description: 'For type=gradient_map with gm_preset=tint. Mid-tone tint color as a hex string like "#5588CC". Only used when gm_preset=tint.',
@@ -510,22 +526,14 @@ const colorLookupBakeSchema = {
             type: 'string',
             description: 'Leaf name of a 3DLUT file in PS\'s Presets/3DLUTs/ folder (e.g. "TealOrangePlusContrast.3DL", "FallColors.look", "Kodak 5205 Fuji 3510 (by Adobe).cube") OR an absolute path to a .3DL / .look / .cube file. Extension-agnostic leaf-name resolution (the same base name with a different extension still matches).',
         },
-        apply_to_active_layer: {
-            type: 'boolean',
-            description: 'If false (default), runs on a DUPLICATE of the active layer; the original is preserved. If true, bakes into the active layer in place.',
-            default: false,
-        },
+        apply_to_active_layer: applyToActiveLayerProp('the color lookup'),
     },
     required: ['cl_lut_name'],
 };
 const equalizeSchema = {
     type: 'object',
     properties: {
-        apply_to_active_layer: {
-            type: 'boolean',
-            description: 'If false (default), the operation runs on a DUPLICATE of the active layer and the original is preserved. If true, bakes into the active layer in place. Use false unless you specifically want the destructive-in-place behavior.',
-            default: false,
-        },
+        apply_to_active_layer: applyToActiveLayerProp('the equalize'),
     },
 };
 const shadowsHighlightsSchema = {
@@ -601,11 +609,7 @@ const shadowsHighlightsSchema = {
             maximum: 50,
             default: 0.01,
         },
-        apply_to_active_layer: {
-            type: 'boolean',
-            description: 'If false (default), the op is applied to a duplicate of the active layer named "Shadows/Highlights (<Original Name>)" — original preserved. If true, bakes directly into the active layer.',
-            default: false,
-        },
+        apply_to_active_layer: applyToActiveLayerProp('the op'),
     },
 };
 const APPLY_ADJUSTMENT_TYPES = ['shadows_highlights', 'equalize', 'color_lookup'];
@@ -632,7 +636,7 @@ export function createAdjustmentTools(connection, snippetClient) {
         {
             tool: {
                 name: 'ps_apply_adjustment',
-                description: "Apply a DESTRUCTIVE tonal adjustment that Photoshop does NOT offer as an adjustment layer — chosen via `type`. Runs on a DUPLICATE of the active layer by default (auto-duplicate-first per Bundle O — the original is preserved; revert by deleting the copy); pass `apply_to_active_layer: true` to bake in place. Auto-rasterizes text/smart-object layers. `shadows_highlights` recovers blown highlights + crushed shadows in one pass (defaults match Adobe's dialog: 35 shadow amount, +20 color correction); `equalize` stretches/flattens the histogram (parameter-free); `color_lookup` bakes a 3DLUT grade (cl_lut_name required — leaf name of a file in Presets/3DLUTs/ or an absolute .cube/.3dl/.look path). For EDITABLE tonal/color work, prefer ps_add_adjustment_layer.",
+                description: "Apply a DESTRUCTIVE tonal adjustment that Photoshop does NOT offer as an adjustment layer — chosen via `type`. Runs on a DUPLICATE of the active layer by default (auto-duplicate-first — the original is preserved; revert by deleting the copy); pass `apply_to_active_layer: true` to bake in place. Auto-rasterizes text/smart-object layers. `shadows_highlights` recovers blown highlights + crushed shadows in one pass (defaults match Adobe's dialog: 35 shadow amount, +20 color correction); `equalize` stretches/flattens the histogram (parameter-free); `color_lookup` bakes a 3DLUT grade (cl_lut_name required — leaf name of a file in Presets/3DLUTs/ or an absolute .cube/.3dl/.look path). For EDITABLE tonal/color work, prefer ps_add_adjustment_layer.",
                 inputSchema: APPLY_ADJUSTMENT_INPUT_SCHEMA,
                 outputSchema: {
                     type: 'object',
@@ -665,7 +669,7 @@ export function createAdjustmentTools(connection, snippetClient) {
         {
             tool: {
                 name: 'ps_add_adjustment_layer',
-                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.",
+                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 `ps_merge` (mode=visible). 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 `ps_apply_adjustment` (type=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',
@@ -783,6 +787,7 @@ const FORWARDED_KEYS = new Set([
     'gm_tint_color_hex',
     'gm_reverse',
     'gm_dither',
+    'gm_stops',
     'exp_exposure',
     'exp_offset',
     'exp_gamma',
@@ -839,125 +844,68 @@ async function addAdjustmentLayer(connection, snippetClient, rawArgs) {
         };
     }
     catch (error) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error adding adjustment layer: ${error instanceof Error ? error.message : String(error)}`,
-                },
-            ],
-            isError: true,
-        };
+        return toolErrorResult('Error adding adjustment layer', error);
     }
 }
 async function applyColorLookup(connection, snippetClient, rawArgs) {
-    try {
-        const args = validateArgs(colorLookupBakeSchema, rawArgs);
-        const lutName = args.cl_lut_name;
-        const applyToActiveLayer = args.apply_to_active_layer ?? false;
-        const script = await snippetClient.build('applyColorLookup', { lutName, applyToActiveLayer });
-        const result = await runScript(connection, script);
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Color Lookup applied (BAKE, experimental):\n${JSON.stringify(result, null, 2)}`,
-                },
-            ],
-            structuredContent: result,
-        };
-    }
-    catch (error) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error applying color lookup: ${error instanceof Error ? error.message : String(error)}`,
-                },
-            ],
-            isError: true,
-        };
-    }
+    return runSnippetTool({
+        connection,
+        snippetClient,
+        rawArgs,
+        schema: colorLookupBakeSchema,
+        snippet: 'applyColorLookup',
+        errorPrefix: 'Error applying color lookup',
+        params: (args) => ({
+            lutName: args.cl_lut_name,
+            applyToActiveLayer: args.apply_to_active_layer ?? false,
+        }),
+        successText: (result) => `Color Lookup applied (BAKE, experimental):\n${JSON.stringify(result, null, 2)}`,
+    });
 }
 async function applyEqualize(connection, snippetClient, rawArgs) {
-    try {
-        const args = validateArgs(equalizeSchema, rawArgs);
-        const applyToActiveLayer = args.apply_to_active_layer ?? false;
-        const script = await snippetClient.build('applyEqualize', { applyToActiveLayer });
-        const result = await runScript(connection, script);
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Equalize applied:\n${JSON.stringify(result, null, 2)}`,
-                },
-            ],
-            structuredContent: result,
-        };
-    }
-    catch (error) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error applying equalize: ${error instanceof Error ? error.message : String(error)}`,
-                },
-            ],
-            isError: true,
-        };
-    }
+    return runSnippetTool({
+        connection,
+        snippetClient,
+        rawArgs,
+        schema: equalizeSchema,
+        snippet: 'applyEqualize',
+        errorPrefix: 'Error applying equalize',
+        params: (args) => ({
+            applyToActiveLayer: args.apply_to_active_layer ?? false,
+        }),
+        successText: (result) => `Equalize applied:\n${JSON.stringify(result, null, 2)}`,
+    });
 }
 async function applyShadowsHighlights(connection, snippetClient, rawArgs) {
-    try {
-        const args = validateArgs(shadowsHighlightsSchema, rawArgs);
-        const shadowAmount = args.shadow_amount ?? 35;
-        const shadowWidth = args.shadow_width ?? 50;
-        const shadowRadius = args.shadow_radius ?? 30;
-        const highlightAmount = args.highlight_amount ?? 0;
-        const highlightWidth = args.highlight_width ?? 50;
-        const highlightRadius = args.highlight_radius ?? 30;
-        const colorCorrection = args.color_correction ?? 20;
-        const midtoneContrast = args.midtone_contrast ?? 0;
-        const blackClip = args.black_clip ?? 0.01;
-        const whiteClip = args.white_clip ?? 0.01;
-        const applyToActiveLayer = args.apply_to_active_layer ?? false;
-        const script = await snippetClient.build('applyShadowsHighlights', {
-            shadowAmount,
-            shadowWidth,
-            shadowRadius,
-            highlightAmount,
-            highlightWidth,
-            highlightRadius,
-            colorCorrection,
-            midtoneContrast,
-            blackClip,
-            whiteClip,
-            applyToActiveLayer,
-        });
-        const result = await runScript(connection, script);
-        const r = result;
-        const target = r.target_was_copy
-            ? `new copy "${r.target_layer_name ?? '?'}"`
-            : 'active layer (in place)';
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Shadows/Highlights applied to ${target} (shadow ${shadowAmount}, highlight ${highlightAmount}, color ${colorCorrection}).`,
-                },
-            ],
-            structuredContent: result,
-        };
-    }
-    catch (error) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error applying shadows/highlights: ${error instanceof Error ? error.message : String(error)}`,
-                },
-            ],
-            isError: true,
-        };
-    }
+    return runSnippetTool({
+        connection,
+        snippetClient,
+        rawArgs,
+        schema: shadowsHighlightsSchema,
+        snippet: 'applyShadowsHighlights',
+        errorPrefix: 'Error applying shadows/highlights',
+        params: (args) => ({
+            shadowAmount: args.shadow_amount ?? 35,
+            shadowWidth: args.shadow_width ?? 50,
+            shadowRadius: args.shadow_radius ?? 30,
+            highlightAmount: args.highlight_amount ?? 0,
+            highlightWidth: args.highlight_width ?? 50,
+            highlightRadius: args.highlight_radius ?? 30,
+            colorCorrection: args.color_correction ?? 20,
+            midtoneContrast: args.midtone_contrast ?? 0,
+            blackClip: args.black_clip ?? 0.01,
+            whiteClip: args.white_clip ?? 0.01,
+            applyToActiveLayer: args.apply_to_active_layer ?? false,
+        }),
+        successText: (result, args) => {
+            const r = result;
+            const target = r.target_was_copy
+                ? `new copy "${r.target_layer_name ?? '?'}"`
+                : 'active layer (in place)';
+            const shadowAmount = args.shadow_amount ?? 35;
+            const highlightAmount = args.highlight_amount ?? 0;
+            const colorCorrection = args.color_correction ?? 20;
+            return `Shadows/Highlights applied to ${target} (shadow ${shadowAmount}, highlight ${highlightAmount}, color ${colorCorrection}).`;
+        },
+    });
 }

package/dist/tools/brush-tools.js

@@ -1,6 +1,7 @@
 import { SUPPORTED_BRUSH_TOOLS } from '../api/brush-tool-names.js';
 import { runScript } from '../utils/run-script.js';
 import { validateArgs } from '../utils/validate.js';
+import { toolErrorResult, applyToActiveLayerProp } from '../utils/tool-helpers.js';
 import { OnnxLandmarkDetectionClient } from '../detection/landmark-detection-client.js';
 import { resolveExpectedPlacement, PLACEMENT_SCHEMA } from '../perception/grounding-locate.js';
 const TOOLS_REQUIRING_SOURCE = ['clone_stamp', 'healing_brush'];
@@ -109,11 +110,7 @@ const applyBrushStrokeSchema = {
             maximum: 50,
             default: 0,
         },
-        apply_to_active_layer: {
-            type: 'boolean',
-            description: 'If false (default), the stroke runs on a duplicate named "Brush Stroke (<original name>)" — the original is preserved, undo is delete-the-copy (Bundle O pattern). If true, the stroke bakes into the active layer directly.',
-            default: false,
-        },
+        apply_to_active_layer: applyToActiveLayerProp('the stroke'),
     },
     required: ['tool', 'brush_size'],
 };
@@ -122,7 +119,7 @@ export function createBrushTools(connection, snippetClient, client = new OnnxLan
         {
             tool: {
                 name: 'ps_apply_brush_stroke',
-                description: 'Paint along a path with one of PS\'s 16 brush-family tools — supply the path EITHER as an anchor-relational `placement` (preferred: a path relation → the stroke traces a resolved, gate-verified curve along a traced edge / landmark / between two anchors, no pixel-guessing) OR as an explicit `path` list of anchor points — the retouch tools (`healing_brush`, `clone_stamp`, `burn`, `dodge`, `blur`, `sharpen`, `smudge`), the paint family (`brush`, `pencil`, `eraser`), and the specialty tools (`pattern_stamp`, `art_history_brush`, `history_brush`, `color_replacement`, `background_eraser`, `sponge`). The `path` parameter takes a list of anchor points with optional bezier handles, so the same tool handles straight-line strokes, freeform curves, and closed shapes — all by varying the path geometry. **Reach for this when**: (a) cloning out a distraction along a specific shape (clone_stamp with a source_point + a path tracing the unwanted edge); (b) healing a scratch or seam (healing_brush with source_point); (c) dodging / burning to redirect tonal balance along a contour; (d) painting a freehand line into the canvas (brush + foreground_color). Active layer must be a normal pixel layer (background auto-promotes); rasterize adjustment/shape/text/smart-object layers first. Auto-duplicates per Bundle O — the original is preserved and a "Brush Stroke (<name>)" copy receives the paint. **Brush dynamics**: hardness, opacity, and flow are independently settable via `hardness_pct` / `opacity_pct` / `flow_pct` (the live tool options are mutated before stroking and restored to the user\'s prior state in `finally`). Sampled brushes (custom shape-stamp presets) silently ignore hardness/diameter mutations — vary their character via `brush_preset` instead.',
+                description: 'Paint along a path with one of PS\'s 16 brush-family tools — supply the path EITHER as an anchor-relational `placement` (preferred: a path relation → the stroke traces a resolved, gate-verified curve along a traced edge / landmark / between two anchors, no pixel-guessing) OR as an explicit `path` list of anchor points — the retouch tools (`healing_brush`, `clone_stamp`, `burn`, `dodge`, `blur`, `sharpen`, `smudge`), the paint family (`brush`, `pencil`, `eraser`), and the specialty tools (`pattern_stamp`, `art_history_brush`, `history_brush`, `color_replacement`, `background_eraser`, `sponge`). The `path` parameter takes a list of anchor points with optional bezier handles, so the same tool handles straight-line strokes, freeform curves, and closed shapes — all by varying the path geometry. **Reach for this when**: (a) cloning out a distraction along a specific shape (clone_stamp with a source_point + a path tracing the unwanted edge); (b) healing a scratch or seam (healing_brush with source_point); (c) dodging / burning to redirect tonal balance along a contour; (d) painting a freehand line into the canvas (brush + foreground_color). Active layer must be a normal pixel layer (background auto-promotes); rasterize adjustment/shape/text/smart-object layers first. Auto-duplicates — the original is preserved and a "Brush Stroke (<name>)" copy receives the paint. **Brush dynamics**: hardness, opacity, and flow are independently settable via `hardness_pct` / `opacity_pct` / `flow_pct` (the live tool options are mutated before stroking and restored to the user\'s prior state in `finally`). Sampled brushes (custom shape-stamp presets) silently ignore hardness/diameter mutations — vary their character via `brush_preset` instead.',
                 inputSchema: applyBrushStrokeSchema,
                 outputSchema: {
                     type: 'object',
@@ -292,15 +289,7 @@ async function applyBrushStroke(connection, snippetClient, client, rawArgs) {
         };
     }
     catch (error) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error applying brush stroke: ${error instanceof Error ? error.message : String(error)}`,
-                },
-            ],
-            isError: true,
-        };
+        return toolErrorResult('Error applying brush stroke', error);
     }
 }
 function deterministicNoise(i, anchorSeed, axisSalt) {

package/dist/tools/channel-compose-tools.js

@@ -1,5 +1,6 @@
 import { runScript } from '../utils/run-script.js';
 import { validateArgs } from '../utils/validate.js';
+import { toolErrorResult, applyToActiveLayerProp } from '../utils/tool-helpers.js';
 const BLEND_MODES = [
     'normal',
     'multiply',
@@ -45,11 +46,7 @@ const applyImageSchema = {
             maximum: 100,
             default: 100,
         },
-        apply_to_active_layer: {
-            type: 'boolean',
-            description: 'If false (default) the composite is baked onto a DUPLICATE of the active layer (original preserved — delete the copy to revert). Set true to bake destructively in place.',
-            default: false,
-        },
+        apply_to_active_layer: applyToActiveLayerProp('the composite'),
     },
     required: ['blend'],
 };
@@ -182,15 +179,7 @@ async function applyImage(connection, snippetClient, rawArgs) {
         };
     }
     catch (error) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error in ps_apply_image: ${error instanceof Error ? error.message : String(error)}`,
-                },
-            ],
-            isError: true,
-        };
+        return toolErrorResult('Error in ps_apply_image', error);
     }
 }
 async function calculations(connection, snippetClient, rawArgs) {
@@ -228,14 +217,6 @@ async function calculations(connection, snippetClient, rawArgs) {
         };
     }
     catch (error) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error in ps_calculations: ${error instanceof Error ? error.message : String(error)}`,
-                },
-            ],
-            isError: true,
-        };
+        return toolErrorResult('Error in ps_calculations', error);
     }
 }

package/dist/tools/detection-tools.js

@@ -1,7 +1,11 @@
-import { decode, encode } from 'jpeg-js';
+import { encode } from 'jpeg-js';
 import { validateArgs } from '../utils/validate.js';
 import { detectActiveDoc } from '../detection/detect-active-doc.js';
+import { ANNOTATED_PREVIEW_JPEG_QUALITY } from '../utils/jpeg-quality.js';
 import { OnnxDetectionClient, } from '../detection/detection-client.js';
+import { toolErrorResult } from '../utils/tool-helpers.js';
+import { computePixelIdentity, docKeyFrom, samePixelIdentity, } from '../perception/pixel-identity.js';
+import { ANNOTATION_RGB, annotationThickness, drawBoxOutline, } from '../perception/overlay.js';
 const detectSchema = {
     type: 'object',
     properties: {
@@ -46,36 +50,15 @@ const detectSchema = {
         },
     },
 };
-function drawBoxes(bytes, boxes) {
-    const img = decode(bytes, { useTArray: true, formatAsRGBA: true });
-    const { width: w, height: h, data } = img;
-    const thickness = Math.max(2, Math.round(Math.max(w, h) / 400));
-    const setPx = (x, y, r, g, b) => {
-        if (x < 0 || y < 0 || x >= w || y >= h)
-            return;
-        const i = (y * w + x) * 4;
-        data[i] = r;
-        data[i + 1] = g;
-        data[i + 2] = b;
-        data[i + 3] = 255;
-    };
+export function drawBoxes(img, boxes) {
+    const { width: w, height: h } = img;
+    const data = Uint8Array.from(img.data);
+    const out = { data, width: w, height: h };
+    const thickness = annotationThickness(out);
     for (const { bbox, rgb } of boxes) {
-        const x1 = Math.round(bbox[0]);
-        const y1 = Math.round(bbox[1]);
-        const x2 = Math.round(bbox[2]);
-        const y2 = Math.round(bbox[3]);
-        for (let x = x1; x <= x2; x++)
-            for (let k = 0; k < thickness; k++) {
-                setPx(x, y1 + k, rgb[0], rgb[1], rgb[2]);
-                setPx(x, y2 - k, rgb[0], rgb[1], rgb[2]);
-            }
-        for (let y = y1; y <= y2; y++)
-            for (let k = 0; k < thickness; k++) {
-                setPx(x1 + k, y, rgb[0], rgb[1], rgb[2]);
-                setPx(x2 - k, y, rgb[0], rgb[1], rgb[2]);
-            }
+        drawBoxOutline(out, bbox, rgb, thickness);
     }
-    return encode({ data, width: w, height: h }, 88).data;
+    return encode({ data, width: w, height: h }, ANNOTATED_PREVIEW_JPEG_QUALITY).data;
 }
 function summarizeObjects(objects) {
     if (!objects || objects.length === 0)
@@ -85,13 +68,27 @@ function summarizeObjects(objects) {
         counts.set(o.label, (counts.get(o.label) ?? 0) + 1);
     return [...counts.entries()].map(([l, n]) => (n > 1 ? `${l}×${n}` : l)).join(', ');
 }
-async function detect(connection, client, rawArgs) {
+let detectCache = null;
+export function __clearDetectCache() {
+    detectCache = null;
+}
+async function detect(connection, client, rawArgs, detectDeps) {
     try {
         const args = validateArgs(detectSchema, rawArgs);
         const target = args.target ?? 'both';
         const annotate = args.annotate ?? true;
         const wantFaces = target === 'faces' || target === 'both';
         const wantObjects = target === 'objects' || target === 'both';
+        const detectKey = JSON.stringify({
+            faces: wantFaces,
+            objects: wantObjects,
+            maxDimension: args.max_dimension ?? null,
+            faceThreshold: args.face_threshold ?? null,
+            objectThreshold: args.object_threshold ?? null,
+            maxObjects: args.max_objects ?? null,
+        });
+        let hit = null;
+        let pendingIdentity = null;
         const det = await detectActiveDoc(connection, client, {
             faces: wantFaces,
             objects: wantObjects,
@@ -99,22 +96,41 @@ async function detect(connection, client, rawArgs) {
             faceThreshold: args.face_threshold,
             objectThreshold: args.object_threshold,
             maxObjects: args.max_objects,
-        });
-        const mapped = det.result;
+            shouldDetect: ({ decoded, context, docWidth, docHeight }) => {
+                if (!decoded)
+                    return true;
+                const identity = computePixelIdentity(decoded, docKeyFrom(context, docWidth, docHeight));
+                if (detectCache &&
+                    detectCache.optionsKey === detectKey &&
+                    samePixelIdentity(detectCache.identity, identity)) {
+                    hit = detectCache;
+                    return false;
+                }
+                pendingIdentity = identity;
+                return true;
+            },
+        }, detectDeps);
+        const mapped = hit ? hit.result : det.result;
+        const rawDetections = hit ? hit.raw : det.raw;
+        if (!hit && pendingIdentity) {
+            detectCache = {
+                identity: pendingIdentity,
+                optionsKey: detectKey,
+                result: det.result,
+                raw: det.raw,
+            };
+        }
         const content = [];
-        if (annotate) {
+        if (annotate && det.decoded) {
             try {
                 const boxes = [
-                    ...(det.raw.faces ?? []).map((f) => ({
-                        bbox: f.bbox,
-                        rgb: [0, 220, 255],
-                    })),
-                    ...(det.raw.objects ?? []).map((o) => ({
+                    ...(rawDetections.faces ?? []).map((f) => ({ bbox: f.bbox, rgb: ANNOTATION_RGB.face })),
+                    ...(rawDetections.objects ?? []).map((o) => ({
                         bbox: o.bbox,
-                        rgb: [255, 0, 220],
+                        rgb: ANNOTATION_RGB.object,
                     })),
                 ];
-                const annotated = drawBoxes(det.exportBytes, boxes);
+                const annotated = drawBoxes(det.decoded, boxes);
                 content.push({
                     type: 'image',
                     data: annotated.toString('base64'),
@@ -150,14 +166,10 @@ async function detect(connection, client, rawArgs) {
         };
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return {
-            content: [{ type: 'text', text: `Error during detection: ${msg}` }],
-            isError: true,
-        };
+        return toolErrorResult('Error during detection', error);
     }
 }
-export function createDetectionTools(connection, _snippetClient, client = new OnnxDetectionClient()) {
+export function createDetectionTools(connection, _snippetClient, client = new OnnxDetectionClient(), detectDeps) {
     return [
         {
             tool: {
@@ -203,7 +215,7 @@ export function createDetectionTools(connection, _snippetClient, client = new On
                     idempotentHint: true,
                 },
             },
-            handler: async (args) => detect(connection, client, args),
+            handler: async (args) => detect(connection, client, args, detectDeps),
         },
     ];
 }