@cplace/mcp-server 1.9.1 → 1.10.5

package/dist/tools/layout.js

@@ -1,21 +1,23 @@
-import { z } from "zod";
-import { debugLogWithTag } from "../logger.js";
-import { checkResponseSize } from "../utils.js";
+import { z } from 'zod';
+import { debugLogWithTag } from '../logger.js';
+import { checkResponseSize } from '../utils.js';
 import { applyStrReplace } from '../str-replace-utils.js';
-import { determineApiEndpoint, buildRequestParams, findWidgetById } from './widget-tool-helpers.js';
+import { determineApiEndpoint, buildRequestParams, findWidgetById, extractWidgetIdSummary, buildStaleIdErrorResponse, } from './widget-tool-helpers.js';
 import { jsonStringToObject } from './common-schemas.js';
-export const LayoutContextSchema = jsonStringToObject(z.union([
+export const LayoutContextSchema = jsonStringToObject(z
+    .union([
     z.object({
-        type: z.literal("page"),
-        pageUID: z.string().describe("Page UID (e.g., 'page/abc123')")
+        type: z.literal('page'),
+        pageUID: z.string().describe("Page UID (e.g., 'page/abc123')"),
     }),
     z.object({
-        type: z.literal("type"),
+        type: z.literal('type'),
         workspaceId: z.string().describe("Workspace ID (e.g., 'workspace123')"),
         typeInternalName: z.string().describe("Type internal name (e.g., 'cf.example.myType')"),
-        alternativeLayoutName: z.string().optional().describe("Alternative layout name (optional)")
-    })
-]).describe("Layout target - specify whether operating on page or type layout"));
+        alternativeLayoutName: z.string().optional().describe('Alternative layout name (optional)'),
+    }),
+])
+    .describe('Layout target - specify whether operating on page or type layout'));
 const TOOL_EXECUTE_LAYOUT_SCRIPT = 'cplace_execute_layout_script';
 const TOOL_GET_LAYOUT_OVERVIEW = 'cplace_get_layout_overview';
 const TOOL_GET_LAYOUT_WIDGET_DETAILS = 'cplace_get_layout_widget_details';
@@ -100,11 +102,27 @@ Do NOT build the tag in a variable and pass it — the parser rejects tags outsi
   ✅ layout.updateWidget("id", { content: '<decoded-widget type="...">...</decoded-widget>' });
   ❌ var tag = '<decoded-widget ...>...</decoded-widget>'; layout.updateWidget("id", { content: tag });
 
+EMBEDDED WIDGET SCRIPT ATTRIBUTES — PLACEHOLDER WORKFLOW (REQUIRED):
+For script-typed attributes on embedded widgets (e.g. cf.cplace.lowCodeWidgets.lowCodeTextWidget.script),
+initialize the value to a minimal placeholder body inside the inline <decoded-widget> JSON, then fill the
+real script body afterward via cplace_richstring_set_widget_script (full replace) or
+cplace_richstring_edit_widget_script (str-replace diff). Authoring a non-trivial script body inline
+forces it through four nested encoding layers (HTML → JSON → JS string literal → MCP wire) and is a
+documented source of escape-bug churn — the dedicated tools take the script as a plain string in a
+structured argument and avoid all four layers.
+
+Safe placeholder for cf.cplace.lowCodeWidgets.lowCodeText: return '';
+Other script-bearing widget types: pick any runtime-valid placeholder for that widget.
+
+Non-script attributes (strings, numbers, references, lists) do NOT have this problem and are authored
+inline as normal JSON properties on the <decoded-widget> tag.
+
 For atomic single-embedded-widget edits without rewriting the full script,
-see cplace_layout_richstring_* tools.`,
+see cplace_layout_richstring_* and cplace_richstring_*_widget_script tools.`,
         inputSchema: {
             context: LayoutContextSchema,
-            script: z.string().describe(`JavaScript code that calls layout.define() exactly once OR one or more edit verbs.
+            script: z.string()
+                .describe(`JavaScript code that calls layout.define() exactly once OR one or more edit verbs.
 
 FULL REPLACE — layout.define() FORMAT:
 layout.define({
@@ -197,24 +215,31 @@ layout.updateWidget("myTable", { "height": 800 });
 EMBEDDED WIDGET CONSTRAINT:
 <decoded-widget> tags must appear directly inline in content: string literals — not in variables.
   ✅ layout.updateWidget("id", { content: '<decoded-widget ...>...</decoded-widget>' });
-  ❌ var tag = '<decoded-widget ...>'; layout.updateWidget("id", { content: tag });`)
+  ❌ var tag = '<decoded-widget ...>'; layout.updateWidget("id", { content: tag });
+
+EMBEDDED WIDGET SCRIPT ATTRIBUTES — placeholder workflow (REQUIRED):
+For script-typed attributes on embedded widgets, initialize the value inline to a minimal
+placeholder (e.g. return '';), then fill the real script body afterward via
+cplace_richstring_set_widget_script or cplace_richstring_edit_widget_script. Authoring a
+non-trivial script body inline forces it through four nested encoding layers and is a
+documented source of escape-bug churn.`),
         },
-        annotations: { title: "Execute Layout Script" }
+        annotations: { title: 'Execute Layout Script' },
     },
     [TOOL_GET_LAYOUT_OVERVIEW]: {
-        description: "Get layout structure for page or type. Provides an overview of the layout grid including rows, columns, and widget summaries for both page and type layouts.",
+        description: 'Get layout structure for page or type. Provides an overview of the layout grid including rows, columns, and widget summaries for both page and type layouts.',
         inputSchema: {
-            context: LayoutContextSchema
+            context: LayoutContextSchema,
         },
-        annotations: { title: "Get Layout Overview" }
+        annotations: { title: 'Get Layout Overview' },
     },
     [TOOL_GET_LAYOUT_WIDGET_DETAILS]: {
-        description: "Get detailed widget configuration from page or type layout. Extracts specific widget information from the layout structure.\n\nRichString widget content appears in decoded form: `<decoded-widget id=\"…\" type=\"…\">{\"properties\":{…}}</decoded-widget>` — no base64.",
+        description: 'Get detailed widget configuration from page or type layout. Extracts specific widget information from the layout structure.\n\nRichString widget content appears in decoded form: `<decoded-widget id="…" type="…">{"properties":{…}}</decoded-widget>` — no base64.',
         inputSchema: {
             context: LayoutContextSchema,
-            widgetId: z.string().describe("The unique widget identifier to get details for")
+            widgetId: z.string().describe('The unique widget identifier to get details for'),
         },
-        annotations: { title: "Get Layout Widget Details" }
+        annotations: { title: 'Get Layout Widget Details' },
     },
     [TOOL_GET_LAYOUT_SCRIPT]: {
         description: `Get the current layout as an executable script for a page or type layout.
@@ -236,20 +261,31 @@ RichString widget content is returned in decoded form:
 The output is directly executable — base64 tags are never emitted.`,
         inputSchema: {
             context: LayoutContextSchema,
-            widgetIds: z.array(z.string()).optional().describe("Optional list of widget IDs to read. When provided, returns layout.updateWidget() fragments for just those widgets instead of the full layout.define() script. Widget IDs can be found via cplace_get_layout_overview.")
+            widgetIds: z
+                .array(z.string())
+                .optional()
+                .describe('Optional list of widget IDs to read. When provided, returns layout.updateWidget() fragments for just those widgets instead of the full layout.define() script. Widget IDs can be found via cplace_get_layout_overview.'),
         },
-        annotations: { title: "Get Layout Script" }
+        annotations: { title: 'Get Layout Script' },
     },
     [TOOL_EDIT_LAYOUT]: {
-        description: "Edit a layout using str_replace — find an exact text match and replace it. Reads the current layout.define() definition, applies the replacement, and writes back. Use this instead of cplace_execute_layout_script when making small changes to large layouts to avoid reproducing the entire definition.\n\nRichString widget content is in decoded form. `old_str` must match the decoded form exactly as returned by cplace_get_layout_script. Raw base64 <embeddedwidget> tags are rejected in both `old_str` and `new_str`.",
+        description: 'Edit a layout using str_replace — find an exact text match and replace it. Reads the current layout.define() definition, applies the replacement, and writes back. Use this instead of cplace_execute_layout_script when making small changes to large layouts to avoid reproducing the entire definition.\n\nRichString widget content is in decoded form. `old_str` must match the decoded form exactly as returned by cplace_get_layout_script. Raw base64 <embeddedwidget> tags are rejected in both `old_str` and `new_str`.\n\nIMPORTANT: cplace normalizes HTML/CSS on every save (CSS properties are alphabetized, hex colors become rgb(), whitespace is regularized). After this tool completes, the stored content may differ from what was submitted. The response includes the current stored form — use it (not your original input) when constructing the next old_str.',
         inputSchema: {
             context: LayoutContextSchema,
-            old_str: z.string().describe("The exact text to find in the layout definition (must match exactly, including whitespace and line breaks)"),
-            new_str: z.string().describe("The replacement text. Use empty string to delete the matched text."),
-            replace_all: z.boolean().optional().default(false).describe("If true, replace all occurrences of old_str. If false (default), fails when old_str matches more than once.")
+            old_str: z
+                .string()
+                .describe('The exact text to find in the layout definition (must match exactly, including whitespace and line breaks)'),
+            new_str: z
+                .string()
+                .describe('The replacement text. Use empty string to delete the matched text.'),
+            replace_all: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('If true, replace all occurrences of old_str. If false (default), fails when old_str matches more than once.'),
         },
-        annotations: { title: "Edit Layout" }
-    }
+        annotations: { title: 'Edit Layout' },
+    },
 };
 async function getLayoutOverview(client, context) {
     const endpoint = determineApiEndpoint(context);
@@ -261,22 +297,22 @@ export function registerLayoutTools(server, client) {
     server.registerTool(TOOL_EXECUTE_LAYOUT_SCRIPT, LAYOUT_TOOL_DEFINITIONS[TOOL_EXECUTE_LAYOUT_SCRIPT], async ({ context, script }) => {
         debugLogWithTag('EXECUTE_LAYOUT_SCRIPT', `Executing ${context.type} layout script (${script.length} chars)`);
         try {
-            const endpoint = context.type === "page"
-                ? "json/page/layoutScript"
-                : "json/type/layoutScript";
+            const endpoint = context.type === 'page' ? 'json/page/layoutScript' : 'json/type/layoutScript';
             let requestBody;
-            if (context.type === "page") {
+            if (context.type === 'page') {
                 requestBody = {
                     pageUID: context.pageUID,
-                    script
+                    script,
                 };
             }
             else {
                 requestBody = {
                     workspaceId: context.workspaceId,
                     typeInternalName: context.typeInternalName,
-                    ...(context.alternativeLayoutName && { alternativeLayoutName: context.alternativeLayoutName }),
-                    script
+                    ...(context.alternativeLayoutName && {
+                        alternativeLayoutName: context.alternativeLayoutName,
+                    }),
+                    script,
                 };
             }
             const rawResponse = await client.makeRawApiRequest(endpoint, 'POST', undefined, requestBody);
@@ -284,75 +320,87 @@ export function registerLayoutTools(server, client) {
             let response;
             if (rawResponse.success === true) {
                 response = {
-                    operation: "EXECUTE_LAYOUT_SCRIPT",
+                    operation: 'EXECUTE_LAYOUT_SCRIPT',
                     success: true,
                     status: rawResponse.status,
                     context,
                     result: rawResponse.result,
-                    ...(rawResponse.validationWarnings && { validationWarnings: rawResponse.validationWarnings })
+                    ...(rawResponse.validationWarnings && {
+                        validationWarnings: rawResponse.validationWarnings,
+                    }),
                 };
+                if (rawResponse.result?.rows) {
+                    response.widgetIdSummary = extractWidgetIdSummary(rawResponse.result.rows);
+                }
             }
             else if (rawResponse.errors) {
                 response = {
-                    operation: "EXECUTE_LAYOUT_SCRIPT",
+                    operation: 'EXECUTE_LAYOUT_SCRIPT',
                     success: false,
-                    status: "VALIDATION_ERROR",
+                    status: 'VALIDATION_ERROR',
                     context,
                     errors: rawResponse.errors,
-                    hint: "If a widget type was not found, call cplace_list_widget_definitions to see available widget types."
+                    hint: 'If a widget type was not found, call cplace_list_widget_definitions to see available widget types.',
                 };
             }
             else {
                 response = {
-                    operation: "EXECUTE_LAYOUT_SCRIPT",
+                    operation: 'EXECUTE_LAYOUT_SCRIPT',
                     success: false,
-                    status: "ERROR",
+                    status: 'ERROR',
                     context,
-                    errorMessage: rawResponse.errorMessage || "Unknown error"
+                    errorMessage: rawResponse.errorMessage || 'Unknown error',
                 };
             }
             const sizeCheck = checkResponseSize(response);
             if (sizeCheck.tooLarge) {
                 if (response.result) {
                     delete response.result;
-                    response.resultNote = "Layout was persisted successfully. Result omitted due to size. Use cplace_get_layout_overview to inspect.";
+                    response.resultNote =
+                        'Layout was persisted successfully. Result omitted due to size — use widgetIdSummary for current widget IDs, or call cplace_get_layout_overview for the full layout.';
                     const sizeCheck2 = checkResponseSize(response);
                     if (sizeCheck2.tooLarge) {
                         debugLogWithTag('EXECUTE_LAYOUT_SCRIPT', `Response still too large after stripping result: ${sizeCheck2.actualSize} chars`);
                         return {
-                            content: [{
-                                    type: "text",
-                                    text: `Layout response too large (${sizeCheck2.actualSize} characters) even after stripping result. Use cplace_get_layout_overview to inspect the layout.`
-                                }],
-                            isError: true
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: `Layout response too large (${sizeCheck2.actualSize} characters) even after stripping result. Use cplace_get_layout_overview to inspect the layout.`,
+                                },
+                            ],
+                            isError: true,
                         };
                     }
                 }
                 else {
                     debugLogWithTag('EXECUTE_LAYOUT_SCRIPT', `Error response too large: ${sizeCheck.actualSize} chars`);
                     return {
-                        content: [{
-                                type: "text",
-                                text: `Layout response too large (${sizeCheck.actualSize} characters). Use cplace_get_layout_overview to inspect the layout.`
-                            }],
-                        isError: true
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Layout response too large (${sizeCheck.actualSize} characters). Use cplace_get_layout_overview to inspect the layout.`,
+                            },
+                        ],
+                        isError: true,
                     };
                 }
             }
             debugLogWithTag('EXECUTE_LAYOUT_SCRIPT', `Returning response with success=${response.success}, status=${response.status}`);
             return {
-                content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
-                ...(!response.success ? { isError: true } : {})
+                content: [{ type: 'text', text: JSON.stringify(response, null, 2) }],
+                ...(!response.success ? { isError: true } : {}),
             };
         }
         catch (error) {
             debugLogWithTag('EXECUTE_LAYOUT_SCRIPT', `Error: ${error instanceof Error ? error.message : String(error)}`);
             return {
-                content: [{
-                        type: "text",
-                        text: `Error executing layout script: ${error instanceof Error ? error.message : String(error)}`
-                    }],
-                isError: true
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error executing layout script: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
             };
         }
     });
@@ -371,24 +419,26 @@ export function registerLayoutTools(server, client) {
                             id: widget.id,
                             widgetType: widget.widgetType,
                             configurationCount: widget.configuration?.length || 0,
-                            validationStatus: widget.validationStatus || null
-                        })) || []
-                    })) || []
-                })) || []
+                            validationStatus: widget.validationStatus || null,
+                        })) || [],
+                    })) || [],
+                })) || [],
             };
             debugLogWithTag('LAYOUT', `Retrieved ${context.type} layout overview successfully`);
             return {
-                content: [{ type: "text", text: JSON.stringify(overview, null, 2) }]
+                content: [{ type: 'text', text: JSON.stringify(overview, null, 2) }],
             };
         }
         catch (error) {
             debugLogWithTag('LAYOUT', `Error getting layout overview: ${error instanceof Error ? error.message : String(error)}`);
             return {
-                content: [{
-                        type: "text",
-                        text: `Error getting ${context.type} layout overview: ${error instanceof Error ? error.message : String(error)}`
-                    }],
-                isError: true
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error getting ${context.type} layout overview: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
             };
         }
     });
@@ -398,145 +448,206 @@ export function registerLayoutTools(server, client) {
             const layoutResult = await getLayoutOverview(client, context);
             const foundWidget = findWidgetById(layoutResult.rows, widgetId);
             if (!foundWidget) {
-                return {
-                    content: [{ type: "text", text: `Widget with ID ${widgetId} not found in ${context.type} layout` }]
-                };
+                return buildStaleIdErrorResponse(widgetId, context.type);
             }
             debugLogWithTag('LAYOUT', `Retrieved widget details for: ${widgetId} from ${context.type} layout`);
             const response = {
                 context,
                 widgetId,
                 widget: foundWidget,
-                validationStatus: foundWidget.validationStatus || null
+                validationStatus: foundWidget.validationStatus || null,
             };
             return {
-                content: [{ type: "text", text: JSON.stringify(response, null, 2) }]
+                content: [{ type: 'text', text: JSON.stringify(response, null, 2) }],
             };
         }
         catch (error) {
             debugLogWithTag('LAYOUT', `Error getting widget details: ${error instanceof Error ? error.message : String(error)}`);
             return {
-                content: [{
-                        type: "text",
-                        text: `Error getting widget details from ${context.type} layout: ${error instanceof Error ? error.message : String(error)}`
-                    }],
-                isError: true
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error getting widget details from ${context.type} layout: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
             };
         }
     });
     server.registerTool(TOOL_GET_LAYOUT_SCRIPT, LAYOUT_TOOL_DEFINITIONS[TOOL_GET_LAYOUT_SCRIPT], async ({ context, widgetIds }) => {
         debugLogWithTag('GET_LAYOUT_SCRIPT', `Getting layout script for ${context.type} layout${widgetIds ? ` (widgets: ${widgetIds.join(', ')})` : ''}`);
         try {
-            const endpoint = context.type === "page"
-                ? "json/page/layoutScript"
-                : "json/type/layoutScript";
+            if (widgetIds && widgetIds.length > 0) {
+                const layoutResult = await getLayoutOverview(client, context);
+                const missingIds = widgetIds.filter((id) => !findWidgetById(layoutResult.rows, id));
+                if (missingIds.length > 0) {
+                    const missingList = missingIds.map((id) => `"${id}"`).join(', ');
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Widget ID(s) not found: ${missingList}. Widget IDs are regenerated after every layout save — call cplace_get_layout_overview to get current IDs.`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            }
+            const endpoint = context.type === 'page' ? 'json/page/layoutScript' : 'json/type/layoutScript';
             const params = {
                 ...buildRequestParams(context),
-                ...(widgetIds && widgetIds.length > 0 && { widgetIds })
+                ...(widgetIds && widgetIds.length > 0 && { widgetIds }),
             };
             const rawResponse = await client.makeRawApiRequest(endpoint, 'GET', params);
             if (rawResponse.success !== true) {
                 return {
-                    content: [{
-                            type: "text",
-                            text: `Error getting ${context.type} layout script: ${rawResponse.errorMessage || "Unknown error"}`
-                        }],
-                    isError: true
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error getting ${context.type} layout script: ${rawResponse.errorMessage || 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
                 };
             }
             const response = {
                 context,
                 ...(widgetIds && { widgetIds }),
-                script: rawResponse.script
+                script: rawResponse.script,
             };
             const sizeCheck = checkResponseSize(response);
             if (sizeCheck.tooLarge) {
                 return {
-                    content: [{
-                            type: "text",
-                            text: `Layout script response too large (${sizeCheck.actualSize} characters). ${widgetIds ? 'Try requesting fewer widgets.' : 'Use cplace_get_layout_overview to inspect the layout structure instead, or use widgetIds to request specific widgets.'}`
-                        }],
-                    isError: true
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Layout script response too large (${sizeCheck.actualSize} characters). ${widgetIds ? 'Try requesting fewer widgets.' : 'Use cplace_get_layout_overview to inspect the layout structure instead, or use widgetIds to request specific widgets.'}`,
+                        },
+                    ],
+                    isError: true,
                 };
             }
             return {
-                content: [{ type: "text", text: JSON.stringify(response, null, 2) }]
+                content: [{ type: 'text', text: JSON.stringify(response, null, 2) }],
             };
         }
         catch (error) {
             debugLogWithTag('GET_LAYOUT_SCRIPT', `Error: ${error instanceof Error ? error.message : String(error)}`);
             return {
-                content: [{
-                        type: "text",
-                        text: `Error getting ${context.type} layout script: ${error instanceof Error ? error.message : String(error)}`
-                    }],
-                isError: true
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error getting ${context.type} layout script: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
             };
         }
     });
     server.registerTool(TOOL_EDIT_LAYOUT, LAYOUT_TOOL_DEFINITIONS[TOOL_EDIT_LAYOUT], async ({ context, old_str, new_str, replace_all = false }) => {
         debugLogWithTag('EDIT_LAYOUT', `Editing ${context.type} layout`);
         try {
-            const readEndpoint = context.type === "page"
-                ? "json/page/layoutScript"
-                : "json/type/layoutScript";
+            const readEndpoint = context.type === 'page' ? 'json/page/layoutScript' : 'json/type/layoutScript';
             const readParams = buildRequestParams(context);
             const rawResponse = await client.makeRawApiRequest(readEndpoint, 'GET', readParams);
             if (rawResponse.success !== true) {
                 return {
-                    content: [{ type: "text", text: `Error reading layout definition: ${rawResponse.errorMessage || "Unknown error"}` }],
-                    isError: true
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error reading layout definition: ${rawResponse.errorMessage || 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
                 };
             }
             const currentScript = rawResponse.script;
             if (currentScript === undefined || currentScript === null || currentScript === '') {
                 return {
-                    content: [{ type: "text", text: `Error: No layout definition found for this ${context.type}. Use cplace_execute_layout_script to create a new layout.` }],
-                    isError: true
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error: No layout definition found for this ${context.type}. Use cplace_execute_layout_script to create a new layout.`,
+                        },
+                    ],
+                    isError: true,
                 };
             }
             const result = applyStrReplace(currentScript, old_str, new_str, replace_all);
             if (!result.success) {
                 return {
-                    content: [{ type: "text", text: `Error: ${result.error}` }],
-                    isError: true
+                    content: [{ type: 'text', text: `Error: ${result.error}` }],
+                    isError: true,
                 };
             }
             let writeBody;
-            if (context.type === "page") {
+            if (context.type === 'page') {
                 writeBody = { pageUID: context.pageUID, script: result.newContent };
             }
             else {
                 writeBody = {
                     workspaceId: context.workspaceId,
                     typeInternalName: context.typeInternalName,
-                    ...(context.alternativeLayoutName && { alternativeLayoutName: context.alternativeLayoutName }),
-                    script: result.newContent
+                    ...(context.alternativeLayoutName && {
+                        alternativeLayoutName: context.alternativeLayoutName,
+                    }),
+                    script: result.newContent,
                 };
             }
             const writeResponse = await client.makeRawApiRequest(readEndpoint, 'POST', undefined, writeBody);
             if (writeResponse.success !== true) {
                 const errorDetail = writeResponse.errors
                     ? JSON.stringify(writeResponse.errors, null, 2)
-                    : writeResponse.errorMessage || "Unknown error";
+                    : writeResponse.errorMessage || 'Unknown error';
                 return {
-                    content: [{ type: "text", text: `Error writing layout after edit: ${errorDetail}` }],
-                    isError: true
+                    content: [{ type: 'text', text: `Error writing layout after edit: ${errorDetail}` }],
+                    isError: true,
                 };
             }
+            const reReadResponse = await client.makeRawApiRequest(readEndpoint, 'GET', readParams);
+            const storedPreview = reReadResponse.success === true && reReadResponse.script
+                ? reReadResponse.script.length > 500
+                    ? reReadResponse.script.substring(0, 500) + '...'
+                    : reReadResponse.script
+                : null;
+            let widgetIdSummary = [];
+            try {
+                const overviewResult = await getLayoutOverview(client, context);
+                widgetIdSummary = extractWidgetIdSummary(overviewResult.rows);
+            }
+            catch (e) {
+                debugLogWithTag('EDIT_LAYOUT', `Warning: could not fetch widget ID summary: ${e instanceof Error ? e.message : String(e)}`);
+            }
             debugLogWithTag('EDIT_LAYOUT', `Successfully edited layout (${result.replacementCount} replacement(s)), status: ${writeResponse.status}`);
-            const responseText = writeResponse.status === 'VALID_COMPLETE'
-                ? `Successfully edited layout. Replaced ${result.replacementCount} occurrence(s). Layout is valid and complete.`
-                : `Successfully edited layout. Replaced ${result.replacementCount} occurrence(s). Status: ${writeResponse.status}.${writeResponse.validationWarnings ? ' Warnings: ' + JSON.stringify(writeResponse.validationWarnings) : ''}`;
+            const editResponse = {
+                operation: 'EDIT_LAYOUT',
+                success: true,
+                status: writeResponse.status,
+                replacementCount: result.replacementCount,
+                context,
+                ...(writeResponse.validationWarnings && {
+                    validationWarnings: writeResponse.validationWarnings,
+                }),
+                ...(storedPreview && {
+                    normalizationNote: 'Server-side CSS normalization may have changed the stored form (properties alphabetized, hex→rgb, whitespace regularized).',
+                    storedPreview,
+                }),
+                widgetIdSummary,
+            };
             return {
-                content: [{ type: "text", text: responseText }]
+                content: [{ type: 'text', text: JSON.stringify(editResponse, null, 2) }],
             };
         }
         catch (error) {
             debugLogWithTag('EDIT_LAYOUT', `Error: ${error instanceof Error ? error.message : String(error)}`);
             return {
-                content: [{ type: "text", text: `Error editing layout: ${error instanceof Error ? error.message : String(error)}` }],
-                isError: true
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error editing layout: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
             };
         }
     });