editmamei 1.6.0 → 1.7.0

package/dist/tools/gimp-effect-tools.js

@@ -0,0 +1,267 @@
+import { validateArgs } from '../utils/validate.js';
+import { toolGimpErrorResult } from '../utils/tool-helpers.js';
+import { GIMP_IMAGE_PROP, GIMP_LAYER_ID_PROP, GIMP_LAYER_PROP, pickSchemaDeclaredKeys, } from './gimp-shared.js';
+const EFFECT_TYPES = [
+    'vignette',
+    'black_white',
+    'motion_blur',
+    'lens_blur',
+    'add_noise',
+    'drop_shadow',
+];
+const effectSchema = {
+    type: 'object',
+    properties: {
+        image: GIMP_IMAGE_PROP,
+        type: {
+            type: 'string',
+            enum: [...EFFECT_TYPES],
+            description: 'Which effect to create/re-edit — see the per-field descriptions below for which ' +
+                'fields apply to which effect.',
+        },
+        filter_id: {
+            type: 'integer',
+            description: "Re-edit this existing filter IN PLACE instead of adding a new one (must match `type`'s " +
+                'operation). Any per-effect field you omit keeps the value it already had — this is a ' +
+                'MERGE, not a reset. The values gimp_filter op=list reports for it are in these same ' +
+                'field names and units, so they can be passed straight back. The mask is fixed at ' +
+                'creation and cannot change on a re-edit. Only filters Editmamei created can be ' +
+                're-edited (gimp_filter op=list shows source: "editmamei"); re-editing any other filter ' +
+                '(for example one added in the GIMP GUI) is refused, because its current values cannot ' +
+                'be read back exactly — delete it and re-create it instead. A re-edit keeps the filter ' +
+                'on its own layer; `layer` and `layer_id` are ignored.',
+        },
+        layer: {
+            ...GIMP_LAYER_PROP,
+            description: GIMP_LAYER_PROP.description +
+                ' The filter applies to that ONE layer, not to the flattened image, so on a ' +
+                'multi-layer document name the layer you mean. A layer inside a layer group can be ' +
+                'named directly.',
+        },
+        layer_id: GIMP_LAYER_ID_PROP,
+        mask: {
+            type: 'string',
+            description: 'Name of a mask channel from gimp_create_mask, confining a NEW filter to it. Only valid ' +
+                "when creating (no filter_id) — a filter's mask is fixed at creation. ORDER MATTERS: " +
+                'straighten / flip / resize the canvas first (gimp_transform_canvas, gimp_resize_image), ' +
+                'then crop, THEN add masked effects — rotate, flip, and resize all refuse outright once ' +
+                'any masked filter exists on the image, or any filter not created by Editmamei, since ' +
+                'they cannot keep a mask aligned through those transforms. Cropping afterward is always ' +
+                'safe.',
+        },
+        name: {
+            type: 'string',
+            description: 'Label for a new filter, e.g. "Corner darken". Made unique automatically.',
+        },
+        radius: {
+            type: 'number',
+            minimum: 0,
+            maximum: 1500,
+            description: 'vignette: size of the untouched centre, 0..3, relative to the LAYER (not absolute ' +
+                'pixels — the same value looks visually equivalent at any resolution, and consistent ' +
+                'with center_x/center_y below). SMALLER is STRONGER. Default (when creating): 2.0, a ' +
+                'subtle vignette (corners about a quarter darker, centre untouched). At the default ' +
+                'softness and gamma, 1.5 is strong (corners more than half darker) and 1.2 or less ' +
+                'turns the corners black. ' +
+                'lens_blur: blur radius in pixels at full resolution, 0..150 ' +
+                '(default 25 when creating) — capped much lower than the other two effects here (measured ' +
+                'live: expensive at full resolution). drop_shadow: blur radius in pixels at full ' +
+                'resolution, 0..1500 (default 10 when creating), clipped to the layer bounds rather than ' +
+                'growing it. Both lens_blur and drop_shadow are SPATIAL (radius-scaled on the proxy ' +
+                'preview, see gimp_overview). The bridge enforces the precise range for whichever ' +
+                '`type` you gave.',
+        },
+        softness: {
+            type: 'number',
+            minimum: 0,
+            maximum: 1,
+            description: 'vignette only. How gradual the falloff is; 0 is a hard edge. Default (when creating): 1.0.',
+        },
+        gamma: {
+            type: 'number',
+            minimum: 0.1,
+            maximum: 10,
+            description: 'vignette only. Falloff curve shape: lower spreads the darkening further in toward the ' +
+                'centre and deepens it; higher confines it to the corners and weakens it. Default (when ' +
+                'creating): 2.0.',
+        },
+        center_x: {
+            type: 'number',
+            minimum: 0,
+            maximum: 1,
+            description: "vignette only. Vignette center, as a fraction of the LAYER's own width (not the whole " +
+                'canvas — 0 = left edge, 1 = right edge). Default (when creating): 0.5. Cropping ' +
+                're-centres the vignette on the new, smaller frame (the same fraction now means a ' +
+                'different point) — the intended behaviour, like a post-crop vignette in Lightroom, not ' +
+                'something to correct for.',
+        },
+        center_y: {
+            type: 'number',
+            minimum: 0,
+            maximum: 1,
+            description: "vignette only. Vignette center, as a fraction of the LAYER's own height (not the whole " +
+                'canvas — 0 = top edge, 1 = bottom edge). Default (when creating): 0.5. The vignette ' +
+                'color is black and not configurable yet.',
+        },
+        red_weight: {
+            type: 'number',
+            minimum: -5,
+            maximum: 5,
+            description: 'black_white only. How much the red channel contributes to the resulting gray. Default ' +
+                '(when creating): 0.333.',
+        },
+        green_weight: {
+            type: 'number',
+            minimum: -5,
+            maximum: 5,
+            description: 'black_white only. Default (when creating): 0.333.',
+        },
+        blue_weight: {
+            type: 'number',
+            minimum: -5,
+            maximum: 5,
+            description: 'black_white only. Default (when creating): 0.333.',
+        },
+        preserve_luminosity: {
+            type: 'boolean',
+            description: 'black_white only. Default (when creating): false.',
+        },
+        length: {
+            type: 'number',
+            minimum: 0,
+            maximum: 1000,
+            description: 'motion_blur only. Blur length in pixels at full resolution, 0..1000. Default (when ' +
+                'creating): 10. SPATIAL (scaled on the proxy preview, see gimp_overview).',
+        },
+        angle: {
+            type: 'number',
+            minimum: -180,
+            maximum: 180,
+            description: 'motion_blur only. Direction of the streak, in degrees: 0 is horizontal, positive angles ' +
+                'rotate clockwise (90 is vertical). Default (when creating): 0.',
+        },
+        highlight_factor: {
+            type: 'number',
+            minimum: 0,
+            maximum: 1,
+            description: 'lens_blur only. Boosts bright out-of-focus highlights (bokeh) above this threshold. ' +
+                'Default (when creating): 0 (no boost). lens_blur applies uniformly across the whole ' +
+                'layer (a soft-focus effect), not a depth-of-field falloff — mask it (see `mask`) to ' +
+                'confine it to part of the image instead.',
+        },
+        noise_amount: {
+            type: 'number',
+            minimum: 0,
+            maximum: 1,
+            description: 'add_noise only. THE amount control — sets red/green/blue uniformly (grayscale-leaning ' +
+                'noise, not a color-tinted one). Default (when creating): 0.2.',
+        },
+        alpha: {
+            type: 'number',
+            minimum: 0,
+            maximum: 1,
+            description: 'add_noise only. Noise added to the alpha channel too. Default (when creating): 0.',
+        },
+        seed: {
+            type: 'integer',
+            minimum: 0,
+            maximum: 4294967295,
+            description: 'add_noise only. RNG seed — the same seed reproduces the identical noise pattern (useful ' +
+                'for an exact re-edit round trip). Default (when creating): 0.',
+        },
+        offset_x: {
+            type: 'number',
+            minimum: -500,
+            maximum: 500,
+            description: 'drop_shadow only. Horizontal shadow offset in pixels at full resolution. Default (when ' +
+                'creating): 20. SPATIAL (scaled on the proxy preview, see gimp_overview). Only meaningful ' +
+                'on a layer with an alpha channel — a shadow is cast from what is transparent around the ' +
+                'opaque content.',
+        },
+        offset_y: {
+            type: 'number',
+            minimum: -500,
+            maximum: 500,
+            description: 'drop_shadow only. Vertical shadow offset in pixels at full resolution. Default (when ' +
+                'creating): 20. SPATIAL (scaled on the proxy preview, see gimp_overview).',
+        },
+        opacity: {
+            type: 'number',
+            minimum: 0,
+            maximum: 1,
+            description: 'drop_shadow only. Default (when creating): 0.5. The shadow color is black and not ' +
+                'configurable yet.',
+        },
+    },
+    required: ['image', 'type'],
+};
+async function gimpAddEffect(gimp, rawArgs) {
+    try {
+        const args = validateArgs(effectSchema, rawArgs);
+        const result = await gimp.call('effect', pickSchemaDeclaredKeys(effectSchema, args));
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `${rawArgs.filter_id !== undefined ? 'Updated' : 'Added'} ` +
+                        `${result.type} filter "${result.name}" (id ${result.filter_id})` +
+                        (result.mask ? ` confined to mask "${result.mask}".` : '.'),
+                },
+            ],
+            structuredContent: result,
+        };
+    }
+    catch (error) {
+        return toolGimpErrorResult('Error applying GIMP effect filter', error);
+    }
+}
+export function createGimpEffectTools(gimp) {
+    return [
+        {
+            tool: {
+                name: 'gimp_add_effect',
+                description: 'Headless GIMP: append (or, with filter_id, re-edit in place) one of a small ' +
+                    'allow-listed set of GEGL effect filters — vignette, black_white, motion_blur, ' +
+                    'lens_blur, add_noise, drop_shadow — the same non-destructive, re-editable, maskable ' +
+                    "filter mechanism gimp_add_adjustment uses, sharing the SAME stack: gimp_filter's " +
+                    "op=list/set_visibility/delete manage this tool's filters exactly as it manages " +
+                    "gimp_add_adjustment's. `type` picks the effect; a field another effect uses is " +
+                    "refused, naming this type's own fields. A filter applies to ONE layer (`layer_id` " +
+                    'or `layer`, else the selected or top layer), not to the flattened image. A re-edit ' +
+                    "(filter_id) MERGES: any field you omit keeps the filter's existing value. Only " +
+                    'filters Editmamei created can be re-edited; one added in the GIMP GUI is refused ' +
+                    '(delete and re-create it). `mask` (a channel name from gimp_create_mask) confines a ' +
+                    'NEW filter — fixed at creation, cannot change on a re-edit. ORDER MATTERS: straighten ' +
+                    '/ flip / resize the canvas first, then crop, THEN add any masked effect — rotate, ' +
+                    'flip, and resize all refuse outright once a masked filter exists, or any filter not ' +
+                    'created by Editmamei. vignette, motion_blur, and drop_shadow stay locked to the ' +
+                    'content through flip, resize, and an exact 90/180/270-degree rotate (their center/' +
+                    'angle/offset fields are updated automatically, and gimp_filter op=list reflects the ' +
+                    'new values afterward) — rotating by any OTHER angle is refused while one of these ' +
+                    'three is present, rather than letting it drift out of alignment. lens_blur is a ' +
+                    'uniform soft-focus blur, not a depth-of-field falloff. For a plain blur with no bokeh ' +
+                    'highlight boost, use gimp_add_adjustment type=gaussian_blur instead. Check the stack ' +
+                    'afterward with gimp_filter (op=list).',
+                inputSchema: effectSchema,
+                outputSchema: {
+                    type: 'object',
+                    properties: {
+                        filter_id: { type: 'number' },
+                        name: { type: 'string' },
+                        type: { type: 'string' },
+                        mask: { type: ['string', 'null'] },
+                    },
+                },
+                annotations: {
+                    title: 'Add/Update GIMP Effect Filter',
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: true,
+                },
+            },
+            handler: async (args) => gimpAddEffect(gimp, args),
+        },
+    ];
+}
+export const EFFECT_SCHEMA_FOR_TESTS = effectSchema;

package/dist/tools/gimp-filter-tools.js

@@ -9,7 +9,8 @@ const filterSchema = {
             type: 'string',
             enum: ['list', 'set_visibility', 'delete'],
             description: "'list' returns every filter on the image (including filters on layers inside groups), " +
-                'top of stack first, with id/name/operation/visible/mask/source and params. source ' +
+                'top of stack first, with layer/layer_id (which layer the filter lives on, and that ' +
+                "layer's id), id/name/operation/visible/mask/source and params. source " +
                 '"editmamei" = exact ledger record, with params in gimp_add_adjustment\'s own field names ' +
                 'and units, so they can be passed straight back on a re-edit. source "readback" = a filter ' +
                 "Editmamei did not create; its params are GIMP's raw GEGL property names and units (not " +

package/dist/tools/gimp-geometry-tools.js

@@ -38,6 +38,16 @@ const resizeSchema = {
     },
     required: ['image'],
 };
+const EFFECT_UPDATE_FAILURES_PROP = {
+    type: 'array',
+    items: { type: 'string' },
+    description: 'Names of effect filters (position/direction/size-dependent ones tracked through geometry ' +
+        'changes — a center, an angle, an offset, or a size-dependent blur radius under resize) ' +
+        'whose own params could not be updated for this transform (a live update failure) -- they ' +
+        "were restored to their OLD values in gimp_filter's own ledger (guaranteed), and the bridge " +
+        'also tried to restore those same OLD values to the live render (best effort — it can, ' +
+        'rarely, also fail). Omitted when every filter updated cleanly.',
+};
 const transformCanvasSchema = {
     type: 'object',
     properties: {
@@ -65,6 +75,17 @@ const transformCanvasSchema = {
     },
     required: ['image', 'op'],
 };
+function effectUpdateFailuresNote(failures) {
+    if (!failures || failures.length === 0)
+        return '';
+    const plural = failures.length > 1;
+    const it = plural ? 'them' : 'it';
+    return (` WARNING: ${failures.join(', ')} could not be updated for this transform and ` +
+        `${plural ? 'were' : 'was'} left at ${plural ? 'their' : 'its'} old position/angle/offset/size ` +
+        `instead -- delete ${it} (gimp_filter op=delete) and re-create ${it} if ${plural ? 'they need' : 'it needs'} ` +
+        `to track the content (re-applying THIS SAME transform again would move ${it} a second time, ` +
+        `misaligning ${it} the other way).`);
+}
 async function gimpTransformCanvas(gimp, rawArgs) {
     try {
         const args = validateArgs(transformCanvasSchema, rawArgs);
@@ -73,9 +94,10 @@ async function gimpTransformCanvas(gimp, rawArgs) {
             return unknownDiscriminator('op', op, ['rotate', 'flip']);
         }
         const result = await gimp.call(op, pickSchemaDeclaredKeys(transformCanvasSchema, args));
-        const text = op === 'rotate'
+        const text = (op === 'rotate'
             ? `Rotated ${result.degrees}°. New canvas ${result.width}x${result.height}.`
-            : `Flipped ${args.orientation}. Canvas ${result.width}x${result.height}.`;
+            : `Flipped ${args.orientation}. Canvas ${result.width}x${result.height}.`) +
+            effectUpdateFailuresNote(result.effect_update_failures);
         return {
             content: [{ type: 'text', text }],
             structuredContent: result,
@@ -92,7 +114,7 @@ export function createGimpGeometryTools(gimp) {
                 name: 'gimp_crop_document',
                 description: 'Headless GIMP: crop the canvas to an explicit rectangle (left, top, width, height in ' +
                     'document pixels) — not a scale (that is gimp_resize_image). IRREVERSIBLE in this ' +
-                    'session: there is no undo, so gimp_save_xcf first when in doubt. Every live filter, ' +
+                    'session: there is no undo, so gimp_checkpoint (or gimp_save_xcf) first when in doubt. Every live filter, ' +
                     'mask channel, and the filter ledger survive a crop — verified live; it is the one ' +
                     'geometry op that never refuses for masked-filter safety.',
                 inputSchema: cropSchema,
@@ -126,16 +148,20 @@ export function createGimpGeometryTools(gimp) {
                 description: 'Headless GIMP: scale the whole image up or down — not a crop (that is ' +
                     'gimp_crop_document). Give width+height to stretch to an exact box, one alone to keep ' +
                     'aspect, or long_edge to scale by the longer side. IRREVERSIBLE in this session: there ' +
-                    'is no undo, so gimp_save_xcf first when in doubt. REFUSES outright when the image has a ' +
-                    'masked adjustment filter, or any filter not created by Editmamei (for example one added ' +
-                    'in the GIMP GUI) — resize before adding any masked adjustment, not after. A large target (the ' +
+                    'is no undo, so gimp_checkpoint (or gimp_save_xcf) first when in doubt. REFUSES outright when the image has a ' +
+                    'masked filter, or any filter not created by Editmamei (for example one added ' +
+                    'in the GIMP GUI) — resize before adding any masked filter, not after. A large target (the ' +
                     'bridge allows up to 250 megapixels / 30000px per side) can take tens of seconds; if it ' +
                     'times out, the GIMP session restarts and any unsaved work — filters, masks, and any ' +
-                    'other open image — is lost, so save (gimp_save_xcf) before an aggressive resize.',
+                    'other open image — is lost, so make a checkpoint (gimp_checkpoint) before an aggressive resize.',
                 inputSchema: resizeSchema,
                 outputSchema: {
                     type: 'object',
-                    properties: { width: { type: 'number' }, height: { type: 'number' } },
+                    properties: {
+                        width: { type: 'number' },
+                        height: { type: 'number' },
+                        effect_update_failures: EFFECT_UPDATE_FAILURES_PROP,
+                    },
                 },
                 annotations: {
                     title: 'Resize GIMP Image',
@@ -153,7 +179,8 @@ export function createGimpGeometryTools(gimp) {
                 errorPrefix: 'Error resizing GIMP image',
                 successText: (result) => {
                     const r = result;
-                    return `Resized to ${r.width}x${r.height}.`;
+                    return (`Resized to ${r.width}x${r.height}.` +
+                        effectUpdateFailuresNote(r.effect_update_failures));
                 },
             }),
         },
@@ -162,12 +189,16 @@ export function createGimpGeometryTools(gimp) {
                 name: 'gimp_transform_canvas',
                 description: "Headless GIMP: op 'rotate' (arbitrary `degrees` — straighten — plus `expand`) | 'flip' " +
                     '(`orientation` horizontal/vertical). IRREVERSIBLE in this session: there is no undo, so ' +
-                    'gimp_save_xcf first when in doubt. REFUSES outright when the image has a masked ' +
-                    'adjustment filter, or any filter not created by Editmamei (for example one added in the ' +
-                    'GIMP GUI) — straighten/flip before adding any masked adjustment, not after (crop is the ' +
-                    'one geometry op that is always safe afterward). Rotating a very large image can take tens of seconds; ' +
+                    'gimp_checkpoint (or gimp_save_xcf) first when in doubt. REFUSES outright when the image has a masked ' +
+                    'filter, or any filter not created by Editmamei (for example one added in the ' +
+                    'GIMP GUI) — straighten/flip before adding any masked filter, not after (crop is the ' +
+                    'one geometry op that is always safe afterward). A rotate to anything other than an ' +
+                    'exact 0/90/180/270 degrees is also refused while a position/direction-dependent ' +
+                    'filter is present, since only a right angle keeps such a filter locked to the content ' +
+                    '— rotate at a right angle instead, or delete it (gimp_filter op=delete) and re-add it ' +
+                    'afterwards. Rotating a very large image can take tens of seconds; ' +
                     'if it times out, the GIMP session restarts and any unsaved work — filters, masks, and ' +
-                    'any other open image — is lost, so save (gimp_save_xcf) before rotating a large canvas.',
+                    'any other open image — is lost, so make a checkpoint (gimp_checkpoint) before rotating a large canvas.',
                 inputSchema: transformCanvasSchema,
                 outputSchema: {
                     type: 'object',
@@ -175,6 +206,7 @@ export function createGimpGeometryTools(gimp) {
                         width: { type: 'number' },
                         height: { type: 'number' },
                         degrees: { type: 'number' },
+                        effect_update_failures: EFFECT_UPDATE_FAILURES_PROP,
                     },
                 },
                 annotations: {

package/dist/tools/gimp-inspect-tools.js

@@ -1,37 +1,88 @@
 import { validateArgs } from '../utils/validate.js';
 import { toolGimpErrorResult, unknownDiscriminator } from '../utils/tool-helpers.js';
+import { pickSchemaDeclaredKeys } from './gimp-shared.js';
+const INSPECT_WHATS = ['documents', 'document', 'layers', 'channels', 'filter'];
 const inspectSchema = {
     type: 'object',
     properties: {
         what: {
             type: 'string',
-            enum: ['documents'],
+            enum: [...INSPECT_WHATS],
             description: "What to inspect. 'documents' lists every image currently open in this headless session " +
-                '(id only — the bridge has no per-image describe-by-id op yet, so no name/size/layer data ' +
-                "is available here; gimp_open_document's own return value is the place to get that, at " +
-                'open time).',
+                "(id only). 'document' describes ONE open image by id: dims, base_type, precision, " +
+                'resolution, its full layer tree, and its channels by id/name only (no coverage). ' +
+                "'layers' returns just that image's layer tree; 'channels' returns its named channels " +
+                "WITH coverage (selected_pixels/fraction) — the cost 'document' skips — reading each " +
+                "channel's full pixel buffer in turn; on a document with many named channels this can " +
+                'stop early, reporting `truncated: true` and `channels_skipped` (how many were never ' +
+                "read). 'filter' returns one filter by `filter_id`, in the same shape gimp_filter " +
+                '(op=list) reports it in. Layer tree nodes are addressed by `layer_id` (canonical — GIMP ' +
+                "allows duplicate layer names) and flag `is_text_layer`. 'document'/'layers' cap the tree " +
+                'at 2000 nodes total and report `truncated: true` if the cap was hit, alongside ' +
+                '`top_level_count` and `total_nodes`; if it times out the GIMP session restarts and ' +
+                'unsaved work is lost, so save (gimp_save_xcf) first.',
+        },
+        image: {
+            type: 'integer',
+            description: 'Image id, as returned by gimp_open_document. Required for every `what` except ' +
+                "'documents'.",
+        },
+        filter_id: {
+            type: 'integer',
+            description: "Required for what='filter'. The filter id, as returned by gimp_add_adjustment " +
+                'or listed by gimp_filter (op=list).',
         },
     },
     required: ['what'],
 };
+function describeSummary(what, args, result) {
+    const truncatedSuffix = result.truncated ? ' (truncated at the node cap)' : '';
+    if (what === 'filter') {
+        return `Filter ${result.filter_id} ("${result.name}"): ${result.operation}.`;
+    }
+    if (what === 'layers') {
+        const layers = result.layers ?? [];
+        const topLevelCount = result.top_level_count ?? layers.length;
+        return `${topLevelCount} top-level layer(s) on image ${args.image}${truncatedSuffix}.`;
+    }
+    if (what === 'channels') {
+        const channels = result.channels ?? [];
+        const skipped = result.channels_skipped;
+        const stoppedEarlySuffix = result.truncated && skipped ? ` (stopped early, ${skipped} channel(s) skipped)` : '';
+        return `${channels.length} channel(s) on image ${args.image}${stoppedEarlySuffix}.`;
+    }
+    const layers = result.layers ?? [];
+    const channels = result.channels ?? [];
+    const topLevelCount = result.top_level_count ?? layers.length;
+    return (`Document ${result.image}: ${result.width}x${result.height} ${result.base_type} ` +
+        `${result.precision}, ${topLevelCount} top-level layer(s)${truncatedSuffix}, ` +
+        `${channels.length} channel(s).`);
+}
 async function gimpInspect(gimp, rawArgs) {
     try {
         const args = validateArgs(inspectSchema, rawArgs);
         const what = args.what;
-        if (what !== 'documents') {
-            return unknownDiscriminator('what', what, ['documents']);
+        if (what === 'documents') {
+            const result = await gimp.call('ping', {});
+            const documents = (result.images ?? []).map((image) => ({ image }));
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `${documents.length} image(s) open: ${documents.map((d) => d.image).join(', ') || '(none)'}.`,
+                    },
+                ],
+                structuredContent: { what, documents },
+            };
         }
-        const result = await gimp.call('ping', {});
-        const documents = (result.images ?? []).map((image) => ({ image }));
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `${documents.length} image(s) open: ${documents.map((d) => d.image).join(', ') || '(none)'}.`,
-                },
-            ],
-            structuredContent: { what, documents },
-        };
+        if (what === 'document' || what === 'layers' || what === 'channels' || what === 'filter') {
+            const result = await gimp.call('describe', pickSchemaDeclaredKeys(inspectSchema, args));
+            return {
+                content: [{ type: 'text', text: describeSummary(what, args, result) }],
+                structuredContent: { what, ...result },
+            };
+        }
+        return unknownDiscriminator('what', what, INSPECT_WHATS);
     }
     catch (error) {
         return toolGimpErrorResult('Error inspecting GIMP state', error);
@@ -42,10 +93,18 @@ export function createGimpInspectTools(gimp) {
         {
             tool: {
                 name: 'gimp_inspect',
-                description: "Headless GIMP: read-only state reader. Today's only target: what='documents' lists every image " +
-                    'currently open in this headless GIMP session by id (no name/size — track those from ' +
-                    "gimp_open_document's own return value). Fewer targets than ps_inspect: the GIMP bridge " +
-                    'has no describe-by-id op for an already-open image yet.',
+                description: "Headless GIMP: read-only state reader. `what`: 'documents' lists every image " +
+                    "currently open in this headless GIMP session by id. 'document' describes ONE open " +
+                    'image (dims, base_type, precision, resolution, full layer tree, channels by id/name ' +
+                    "only — no coverage); 'layers' returns just the tree; 'channels' returns the channels " +
+                    "WITH coverage (selected_pixels/fraction), the cost 'document' skips, and can stop " +
+                    'early on a document with many named channels (`truncated: true`, `channels_skipped`). ' +
+                    "'filter' describes one filter by filter_id, in the same shape gimp_filter (op=list) " +
+                    'reports it in. Layer tree nodes are addressed by `layer_id` (canonical — GIMP allows ' +
+                    "duplicate layer names) and flag `is_text_layer`. 'document'/'layers' cap the tree at " +
+                    '2000 nodes total and report `truncated: true` if the cap was hit, alongside ' +
+                    '`top_level_count` and `total_nodes`; if it times out the GIMP session restarts and ' +
+                    'unsaved work is lost, so save (gimp_save_xcf) first.',
                 inputSchema: inspectSchema,
                 outputSchema: {
                     type: 'object',
@@ -55,6 +114,34 @@ export function createGimpInspectTools(gimp) {
                             type: 'array',
                             items: { type: 'object', properties: { image: { type: 'number' } } },
                         },
+                        image: { type: 'number' },
+                        width: { type: 'number' },
+                        height: { type: 'number' },
+                        base_type: { type: 'string' },
+                        precision: { type: 'string' },
+                        resolution: {
+                            type: 'object',
+                            properties: {
+                                x: { type: ['number', 'null'] },
+                                y: { type: ['number', 'null'] },
+                            },
+                        },
+                        layers: { type: 'array', items: { type: 'object' } },
+                        truncated: { type: 'boolean' },
+                        top_level_count: { type: 'number' },
+                        total_nodes: { type: 'number' },
+                        channels: { type: 'array', items: { type: 'object' } },
+                        channels_skipped: { type: 'number' },
+                        filter_id: { type: 'number' },
+                        layer: { type: 'string' },
+                        layer_id: { type: 'number' },
+                        name: { type: 'string' },
+                        operation: { type: 'string' },
+                        type: { type: ['string', 'null'] },
+                        visible: { type: 'boolean' },
+                        source: { type: 'string' },
+                        mask: { type: ['string', 'null'] },
+                        params: { type: 'object' },
                     },
                 },
                 annotations: {