✨ Apply naturalChildOrdering, removing workarounds

Set the flag to true during code execution, resetting it to the
original value afterwards.

If the flag is unavailable, issue an error message, which is passed
on to the user via the LLM.

Remove instructions that served to work around the corresponding
issues:
 * https://github.com/penpot/penpot-mcp/issues/28
 * https://github.com/penpot/penpot-mcp/issues/32

mcp/packages/plugin/src/task-handlers/ExecuteCodeTaskHandler.ts

@@ -195,10 +195,39 @@ export class ExecuteCodeTaskHandler extends TaskHandler<ExecuteCodeTaskParams> {
         const context = this.context;
         const code = task.params.code;
 
-        let result: any = await (async (ctx) => {
-            const fn = new Function(...Object.keys(ctx), `return (async () => { ${code} })();`);
-            return fn(...Object.values(ctx));
-        })(context);
+        // set the penpot.flags.naturalChildOrdering to true during code execution.
+        // NOTE: This significantly simplifies API usage (see )
+        // TODO: Remove ts-ignore once Penpot types have been updated
+        let originalNaturalChildOrdering: any;
+        // @ts-ignore
+        if (penpot.flags) {
+            // @ts-ignore
+            originalNaturalChildOrdering = penpot.flags.naturalChildOrdering;
+            // @ts-ignore
+            penpot.flags.naturalChildOrdering = true;
+        } else {
+            // TODO: This can be removed once `flags` has been merged to PROD
+            throw new Error(
+                "You are using a version of the Penpot MCP server which is incompatible " +
+                    "with the connected Penpot version. " +
+                    "Read the documentation for instructions on which version to use: " +
+                    "https://github.com/penpot/penpot/tree/develop/mcp\n" +
+                    "If you are an LLM, tell the user about this!"
+            );
+        }
+
+        let result: any;
+        try {
+            // execute the code in an async function with the context variables as parameters
+            result = await (async (ctx) => {
+                const fn = new Function(...Object.keys(ctx), `return (async () => { ${code} })();`);
+                return fn(...Object.values(ctx));
+            })(context);
+        } finally {
+            // restore the original value of penpot.flags.naturalChildOrdering
+            // @ts-ignore
+            penpot.flags.naturalChildOrdering = originalNaturalChildOrdering;
+        }
 
         console.log("Code execution result:", result);
 

mcp/packages/server/data/initial_instructions.md

@@ -63,7 +63,6 @@ Actual low-level shape types are `Rectangle`, `Path`, `Text`, `Ellipse`, `Image`
   * The z-order of shapes is determined by the order in the `children` array of the parent shape.
     Therefore, when creating shapes that should be on top of each other, add them to the parent in the correct order
     (i.e. add background shapes first, then foreground shapes later).
-    CRITICAL: NEVER use the broken function `appendChild` to achieve this, ALWAYS use `parent.insertChild(parent.children.length, shape)`
   * To modify z-order after creation, use these methods: `bringToFront()`, `sendToBack()`, `bringForward()`, `sendBackward()`,
     and, for precise control, `setParentIndex(index)` (0-based).
 
@@ -76,9 +75,7 @@ Actual low-level shape types are `Rectangle`, `Path`, `Text`, `Ellipse`, `Image`
 **Hierarchical Structure**:
   * `parent` - The parent shape (null for root shapes)
     Note: Hierarchical nesting does not necessarily imply visual containment
-  * CRITICAL: To add children to a parent shape (e.g. a `Board`):
-    - ALWAYS use `parent.insertChild(index, shape)` to add a child, e.g. `parent.insertChild(parent.children.length, shape)` to append
-    - NEVER use `parent.appendChild(shape)` as it is BROKEN and will not insert in a predictable place (except in flex layout boards)
+  * To add children to a parent shape (e.g. a `Board`): `parent.appendChild(shape)` or `parent.insertChild(index, shape)` 
   * Reparenting: `newParent.appendChild(shape)` or `newParent.insertChild(index, shape)` will move a shape to new parent
     - Automatically removes the shape from its old parent
     - Absolute x/y positions are preserved (use `penpotUtils.setParentXY` to adjust relative position)
@@ -112,17 +109,11 @@ Boards can have layout systems that automatically control the positioning and sp
        - To modify spacing: adjust `rowGap` and `columnGap` properties, not individual child positions.
          Optionally, adjust individual child margins via `child.layoutChild`.
        - Sizing: `verticalSizing` and `horizontalSizing` are NOT functional. You need to size manually for the time being.
-    - When a board has flex layout,
-       - child positions are controlled by the layout system, not by individual x/y coordinates (unless `child.layoutChild.absolute` is true);
-         appending or inserting children automatically positions them according to the layout rules.
-       - CRITICAL: For dir="column" or dir="row", the order of the `children` array is reversed relative to the visual order!
-         Therefore, the element that appears first in the array, appears visually at the end (bottom/right) and vice versa.
-         ALWAYS BEAR IN MIND THAT THE CHILDREN ARRAY ORDER IS REVERSED FOR dir="column" OR dir="row"!
+    - When a board has flex layout, child positions are controlled by the layout system, not by individual x/y coordinates (unless `child.layoutChild.absolute` is true);
+      appending or inserting children automatically positions them according to the layout rules.
     - CRITICAL: The FlexLayout method `board.flex.appendChild` is BROKEN. To append children to a flex layout board such that
-      they appear visually at the end, ALWAYS use the Board's method `board.appendChild(shape)`; it will insert at the front
-      of the `children` array for dir="column" or dir="row", which is what you want. So call it in the order of visual appearance.
-      To insert at a specific index, use `board.insertChild(index, shape)`, bearing in mind the reversed order for dir="column"
-      or dir="row".
+      they appear visually at the end, ALWAYS use the Board's method `board.appendChild(shape)`. So call it in the order of visual appearance.
+      To insert at a specific index, use `board.insertChild(index, shape)`.
     - Add to a board with `board.addFlexLayout(): FlexLayout`; instance then accessible via `board.flex`.
       IMPORTANT: When adding a flex layout to a container that already has children,
       use `penpotUtils.addFlexLayout(container, dir)` instead! This preserves the existing visual order of children.