@imgly/codesign-mcp 0.1.5 → 0.1.7

package/assets/docs/guide/create-composition/layer-management.md

@@ -1,4 +1,4 @@
-> This is one page of the CE.SDK Vanilla JS/TS documentation. For a complete overview, see the [Vanilla JS/TS Documentation Index](https://img.ly/docs/cesdk/js.md). For all docs in one file, see [llms-full.txt](./llms-full.txt.md).
+> This is one page of the CE.SDK Node.js documentation. For a complete overview, see the [Node.js Documentation Index](https://img.ly/docs/cesdk/node.md). For all docs in one file, see [llms-full.txt](./llms-full.txt.md).
 
 **Navigation:** [Guides](./guides.md) > [Create and Edit Compositions](./create-composition.md) > [Layers](./create-composition/layer-management.md)
 
@@ -6,235 +6,199 @@
 
 Organize design elements in CE.SDK using a hierarchical layer stack to control stacking order, visibility, and element relationships.
 
-![Layer Management Hero](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
-
 > **Reading time:** 10 minutes
 >
 > **Resources:**
 >
 > - [Download examples](https://github.com/imgly/cesdk-web-examples/archive/refs/tags/release-$UBQ_VERSION$.zip)
-> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-create-composition-layer-management-browser)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-create-composition-layer-management-browser)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-create-composition-layer-management-browser/)
+>
+> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-create-composition-layer-management-server-js)
+>
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-create-composition-layer-management-server-js)
 
 Design elements in CE.SDK are organized in a hierarchical parent-child structure. Children of a block are rendered in order, with the last child appearing on top. This layer stack model gives you precise control over how elements overlap and interact visually.
 
-```typescript file=@cesdk_web_examples/guides-create-composition-layer-management-browser/browser.ts reference-only
-import type { EditorPlugin, EditorPluginContext } from '@cesdk/cesdk-js';
-
-import {
-  BlurAssetSource,
-  ColorPaletteAssetSource,
-  CropPresetsAssetSource,
-  DemoAssetSources,
-  EffectsAssetSource,
-  FiltersAssetSource,
-  PagePresetsAssetSource,
-  StickerAssetSource,
-  TextAssetSource,
-  TextComponentAssetSource,
-  TypefaceAssetSource,
-  UploadAssetSources,
-  VectorShapeAssetSource
-} from '@cesdk/cesdk-js/plugins';
-import { DesignEditorConfig } from './design-editor/plugin';
-import packageJson from './package.json';
+```typescript file=@cesdk_web_examples/guides-create-composition-layer-management-server-js/server-js.ts reference-only
+import CreativeEngine from '@cesdk/node';
+import { config } from 'dotenv';
+import { mkdirSync, writeFileSync } from 'fs';
+
+config();
 
 /**
- * CE.SDK Plugin: Layer Management Guide
+ * CE.SDK Server Guide: Layer Management
  *
- * This example demonstrates:
+ * Demonstrates programmatic layer management:
  * - Navigating parent-child hierarchy
  * - Adding and positioning blocks in the layer stack
  * - Changing z-order (bring to front, send to back)
  * - Controlling visibility
  * - Duplicating and removing blocks
+ * - Exporting the result
  */
-class Example implements EditorPlugin {
-  name = packageJson.name;
-
-  version = packageJson.version;
-
-  async initialize({ cesdk }: EditorPluginContext): Promise<void> {
-    if (!cesdk) {
-      throw new Error('CE.SDK instance is required for this plugin');
-    }
-    await cesdk.addPlugin(new DesignEditorConfig());
-
-    // Add asset source plugins
-    await cesdk.addPlugin(new BlurAssetSource());
-    await cesdk.addPlugin(new ColorPaletteAssetSource());
-    await cesdk.addPlugin(new CropPresetsAssetSource());
-    await cesdk.addPlugin(
-      new UploadAssetSources({ include: ['ly.img.image.upload'] })
-    );
-    await cesdk.addPlugin(
-      new DemoAssetSources({
-        include: [
-          'ly.img.templates.blank.*',
-          'ly.img.templates.presentation.*',
-          'ly.img.templates.print.*',
-          'ly.img.templates.social.*',
-          'ly.img.image.*'
-        ]
-      })
-    );
-    await cesdk.addPlugin(new EffectsAssetSource());
-    await cesdk.addPlugin(new FiltersAssetSource());
-    await cesdk.addPlugin(new PagePresetsAssetSource());
-    await cesdk.addPlugin(new StickerAssetSource());
-    await cesdk.addPlugin(new TextAssetSource());
-    await cesdk.addPlugin(new TextComponentAssetSource());
-    await cesdk.addPlugin(new TypefaceAssetSource());
-    await cesdk.addPlugin(new VectorShapeAssetSource());
-
-    await cesdk.actions.run('scene.create', {
-      page: { width: 800, height: 600, unit: 'Pixel' }
-    });
-
-    const engine = cesdk.engine;
-    const page = engine.block.findByType('page')[0]!;
-
-    // Create a colored rectangle
-    const redRect = engine.block.create('graphic');
-    engine.block.setShape(redRect, engine.block.createShape('rect'));
-    const redFill = engine.block.createFill('color');
-    engine.block.setFill(redRect, redFill);
-    engine.block.setColor(redFill, 'fill/color/value', {
-      r: 0.9,
-      g: 0.2,
-      b: 0.2,
-      a: 1
-    });
-    engine.block.setWidth(redRect, 180);
-    engine.block.setHeight(redRect, 180);
-    engine.block.setPositionX(redRect, 220);
-    engine.block.setPositionY(redRect, 120);
-
-    // Create additional rectangles to demonstrate layer ordering
-    const greenRect = engine.block.create('graphic');
-    engine.block.setShape(greenRect, engine.block.createShape('rect'));
-    const greenFill = engine.block.createFill('color');
-    engine.block.setFill(greenRect, greenFill);
-    engine.block.setColor(greenFill, 'fill/color/value', {
-      r: 0.2,
-      g: 0.8,
-      b: 0.2,
-      a: 1
-    });
-    engine.block.setWidth(greenRect, 180);
-    engine.block.setHeight(greenRect, 180);
-    engine.block.setPositionX(greenRect, 280);
-    engine.block.setPositionY(greenRect, 180);
-
-    const blueRect = engine.block.create('graphic');
-    engine.block.setShape(blueRect, engine.block.createShape('rect'));
-    const blueFill = engine.block.createFill('color');
-    engine.block.setFill(blueRect, blueFill);
-    engine.block.setColor(blueFill, 'fill/color/value', {
-      r: 0.2,
-      g: 0.4,
-      b: 0.9,
-      a: 1
-    });
-    engine.block.setWidth(blueRect, 180);
-    engine.block.setHeight(blueRect, 180);
-    engine.block.setPositionX(blueRect, 340);
-    engine.block.setPositionY(blueRect, 240);
-
-    // Add blocks to the page - last appended is on top
-    engine.block.appendChild(page, redRect);
-    engine.block.appendChild(page, greenRect);
-    engine.block.appendChild(page, blueRect);
-
-    // Get the parent of a block
-    const parent = engine.block.getParent(redRect);
-    console.log('Parent of red rectangle:', parent);
-
-    // Get all children of the page
-    const children = engine.block.getChildren(page);
-    console.log('Page children (in render order):', children);
-
-    // Insert a new block at a specific position (index 0 = back)
-    const yellowRect = engine.block.create('graphic');
-    engine.block.setShape(yellowRect, engine.block.createShape('rect'));
-    const yellowFill = engine.block.createFill('color');
-    engine.block.setFill(yellowRect, yellowFill);
-    engine.block.setColor(yellowFill, 'fill/color/value', {
-      r: 0.95,
-      g: 0.85,
-      b: 0.2,
-      a: 1
-    });
-    engine.block.setWidth(yellowRect, 180);
-    engine.block.setHeight(yellowRect, 180);
-    engine.block.setPositionX(yellowRect, 160);
-    engine.block.setPositionY(yellowRect, 60);
-    engine.block.insertChild(page, yellowRect, 0);
-
-    // Bring the red rectangle to the front
-    engine.block.bringToFront(redRect);
-    console.log('Red rectangle brought to front');
-
-    // Send the blue rectangle to the back
-    engine.block.sendToBack(blueRect);
-    console.log('Blue rectangle sent to back');
-
-    // Move the green rectangle forward one layer
-    engine.block.bringForward(greenRect);
-    console.log('Green rectangle moved forward');
-
-    // Move the yellow rectangle backward one layer
-    engine.block.sendBackward(yellowRect);
-    console.log('Yellow rectangle moved backward');
-
-    // Check and toggle visibility
-    const isVisible = engine.block.isVisible(blueRect);
-    console.log('Blue rectangle visible:', isVisible);
-
-    // Hide the blue rectangle temporarily
-    engine.block.setVisible(blueRect, false);
-    console.log('Blue rectangle hidden');
-
-    // Show it again for the final composition
-    engine.block.setVisible(blueRect, true);
-    console.log('Blue rectangle shown again');
-
-    // Duplicate a block
-    const duplicateGreen = engine.block.duplicate(greenRect);
-    engine.block.setPositionX(duplicateGreen, 400);
-    engine.block.setPositionY(duplicateGreen, 300);
-    // Change the duplicate's color to purple
-    const purpleFill = engine.block.createFill('color');
-    engine.block.setFill(duplicateGreen, purpleFill);
-    engine.block.setColor(purpleFill, 'fill/color/value', {
-      r: 0.6,
-      g: 0.2,
-      b: 0.8,
-      a: 1
-    });
-    console.log('Green rectangle duplicated');
-
-    // Check if a block is valid before operations
-    const isValidBefore = engine.block.isValid(yellowRect);
-    console.log('Yellow rectangle valid before destroy:', isValidBefore);
-
-    // Remove a block from the scene
-    engine.block.destroy(yellowRect);
-    console.log('Yellow rectangle destroyed');
-
-    // Check validity after destruction
-    const isValidAfter = engine.block.isValid(yellowRect);
-    console.log('Yellow rectangle valid after destroy:', isValidAfter);
-
-    await engine.scene.zoomToBlock(page, { padding: 40 });
-  }
-}
 
-export default Example;
+const engine = await CreativeEngine.init({
+  baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
+});
+
+try {
+  // Create a scene with a page
+  engine.scene.create('VerticalStack', {
+    page: { size: { width: 800, height: 600 } }
+  });
+  const page = engine.block.findByType('page')[0]!;
+
+  // Create a colored rectangle
+  const redRect = engine.block.create('graphic');
+  engine.block.setShape(redRect, engine.block.createShape('rect'));
+  const redFill = engine.block.createFill('color');
+  engine.block.setFill(redRect, redFill);
+  engine.block.setColor(redFill, 'fill/color/value', {
+    r: 0.9,
+    g: 0.2,
+    b: 0.2,
+    a: 1
+  });
+  engine.block.setWidth(redRect, 180);
+  engine.block.setHeight(redRect, 180);
+  engine.block.setPositionX(redRect, 220);
+  engine.block.setPositionY(redRect, 120);
+
+  // Create additional rectangles to demonstrate layer ordering
+  const greenRect = engine.block.create('graphic');
+  engine.block.setShape(greenRect, engine.block.createShape('rect'));
+  const greenFill = engine.block.createFill('color');
+  engine.block.setFill(greenRect, greenFill);
+  engine.block.setColor(greenFill, 'fill/color/value', {
+    r: 0.2,
+    g: 0.8,
+    b: 0.2,
+    a: 1
+  });
+  engine.block.setWidth(greenRect, 180);
+  engine.block.setHeight(greenRect, 180);
+  engine.block.setPositionX(greenRect, 280);
+  engine.block.setPositionY(greenRect, 180);
+
+  const blueRect = engine.block.create('graphic');
+  engine.block.setShape(blueRect, engine.block.createShape('rect'));
+  const blueFill = engine.block.createFill('color');
+  engine.block.setFill(blueRect, blueFill);
+  engine.block.setColor(blueFill, 'fill/color/value', {
+    r: 0.2,
+    g: 0.4,
+    b: 0.9,
+    a: 1
+  });
+  engine.block.setWidth(blueRect, 180);
+  engine.block.setHeight(blueRect, 180);
+  engine.block.setPositionX(blueRect, 340);
+  engine.block.setPositionY(blueRect, 240);
+
+  // Add blocks to the page - last appended is on top
+  engine.block.appendChild(page, redRect);
+  engine.block.appendChild(page, greenRect);
+  engine.block.appendChild(page, blueRect);
+
+  // Get the parent of a block
+  const parent = engine.block.getParent(redRect);
+  console.log('Parent of red rectangle:', parent);
+
+  // Get all children of the page
+  const children = engine.block.getChildren(page);
+  console.log('Page children (in render order):', children);
+
+  // Insert a new block at a specific position (index 0 = back)
+  const yellowRect = engine.block.create('graphic');
+  engine.block.setShape(yellowRect, engine.block.createShape('rect'));
+  const yellowFill = engine.block.createFill('color');
+  engine.block.setFill(yellowRect, yellowFill);
+  engine.block.setColor(yellowFill, 'fill/color/value', {
+    r: 0.95,
+    g: 0.85,
+    b: 0.2,
+    a: 1
+  });
+  engine.block.setWidth(yellowRect, 180);
+  engine.block.setHeight(yellowRect, 180);
+  engine.block.setPositionX(yellowRect, 160);
+  engine.block.setPositionY(yellowRect, 60);
+  engine.block.insertChild(page, yellowRect, 0);
+
+  // Bring the red rectangle to the front
+  engine.block.bringToFront(redRect);
+  console.log('Red rectangle brought to front');
+
+  // Send the blue rectangle to the back
+  engine.block.sendToBack(blueRect);
+  console.log('Blue rectangle sent to back');
+
+  // Move the green rectangle forward one layer
+  engine.block.bringForward(greenRect);
+  console.log('Green rectangle moved forward');
+
+  // Move the yellow rectangle backward one layer
+  engine.block.sendBackward(yellowRect);
+  console.log('Yellow rectangle moved backward');
+
+  // Check and toggle visibility
+  const isVisible = engine.block.isVisible(blueRect);
+  console.log('Blue rectangle visible:', isVisible);
+
+  // Hide the blue rectangle temporarily
+  engine.block.setVisible(blueRect, false);
+  console.log('Blue rectangle hidden');
+
+  // Show it again for the export
+  engine.block.setVisible(blueRect, true);
+  console.log('Blue rectangle shown again');
+
+  // Duplicate a block
+  const duplicateGreen = engine.block.duplicate(greenRect);
+  engine.block.setPositionX(duplicateGreen, 400);
+  engine.block.setPositionY(duplicateGreen, 300);
+  console.log('Green rectangle duplicated');
+
+  // Check if a block is valid before operations
+  const isValidBefore = engine.block.isValid(yellowRect);
+  console.log('Yellow rectangle valid before destroy:', isValidBefore);
+
+  // Remove a block from the scene
+  engine.block.destroy(yellowRect);
+  console.log('Yellow rectangle destroyed');
+
+  // Check validity after destruction
+  const isValidAfter = engine.block.isValid(yellowRect);
+  console.log('Yellow rectangle valid after destroy:', isValidAfter);
+
+  // Log final layer order
+  const finalChildren = engine.block.getChildren(page);
+  console.log('Final page children:', finalChildren);
+
+  // Export the page as an image
+  mkdirSync('output', { recursive: true });
+  const blob = await engine.block.export(page, { mimeType: 'image/png' });
+  const buffer = Buffer.from(await blob.arrayBuffer());
+  writeFileSync('output/layer-management-result.png', buffer);
+  console.log('Exported: output/layer-management-result.png');
+
+  console.log('\nLayer management example complete');
+} finally {
+  engine.dispose();
+}
 ```
 
-This guide covers how to navigate the block hierarchy, reorder elements in the layer stack, toggle visibility, and manage block lifecycles through duplication and deletion.
+This guide covers how to navigate the block hierarchy, reorder elements in the layer stack, toggle visibility, and manage block lifecycles through duplication and deletion in a server environment.
+
+## Setting Up the Engine
+
+We initialize the headless CE.SDK engine for server-side processing.
+
+```typescript highlight=highlight-setup
+const engine = await CreativeEngine.init({
+  baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
+});
+```
 
 ## Creating Visual Blocks
 
@@ -387,20 +351,20 @@ Visibility allows you to temporarily hide elements without removing them from th
 We query the current visibility state using `engine.block.isVisible()` and change it using `engine.block.setVisible()`.
 
 ```typescript highlight=highlight-visibility
-// Check and toggle visibility
-const isVisible = engine.block.isVisible(blueRect);
-console.log('Blue rectangle visible:', isVisible);
+  // Check and toggle visibility
+  const isVisible = engine.block.isVisible(blueRect);
+  console.log('Blue rectangle visible:', isVisible);
 
-// Hide the blue rectangle temporarily
-engine.block.setVisible(blueRect, false);
-console.log('Blue rectangle hidden');
+  // Hide the blue rectangle temporarily
+  engine.block.setVisible(blueRect, false);
+  console.log('Blue rectangle hidden');
 
-// Show it again for the final composition
-engine.block.setVisible(blueRect, true);
-console.log('Blue rectangle shown again');
+  // Show it again for the export
+  engine.block.setVisible(blueRect, true);
+  console.log('Blue rectangle shown again');
 ```
 
-Visibility is useful for creating before/after comparisons, hiding elements during editing, or implementing show/hide functionality in your application.
+Visibility is useful for creating before/after comparisons, hiding elements during processing, or implementing conditional rendering in your application.
 
 ## Managing Block Lifecycle
 
@@ -415,15 +379,6 @@ We create a copy of a block and all its children using `engine.block.duplicate()
 const duplicateGreen = engine.block.duplicate(greenRect);
 engine.block.setPositionX(duplicateGreen, 400);
 engine.block.setPositionY(duplicateGreen, 300);
-// Change the duplicate's color to purple
-const purpleFill = engine.block.createFill('color');
-engine.block.setFill(duplicateGreen, purpleFill);
-engine.block.setColor(purpleFill, 'fill/color/value', {
-  r: 0.6,
-  g: 0.2,
-  b: 0.8,
-  a: 1
-});
 console.log('Green rectangle duplicated');
 ```
 
@@ -444,23 +399,28 @@ console.log('Yellow rectangle valid before destroy:', isValidBefore);
 We permanently remove a block and all its children from the scene using `engine.block.destroy()`. This operation cannot be undone programmatically.
 
 ```typescript highlight=highlight-destroy
-// Remove a block from the scene
-engine.block.destroy(yellowRect);
-console.log('Yellow rectangle destroyed');
+  // Remove a block from the scene
+  engine.block.destroy(yellowRect);
+  console.log('Yellow rectangle destroyed');
 
-// Check validity after destruction
-const isValidAfter = engine.block.isValid(yellowRect);
-console.log('Yellow rectangle valid after destroy:', isValidAfter);
+  // Check validity after destruction
+  const isValidAfter = engine.block.isValid(yellowRect);
+  console.log('Yellow rectangle valid after destroy:', isValidAfter);
 ```
 
 After destruction, any references to the block become invalid. Attempting to use an invalid block ID will result in errors.
 
-## Framing the Result
+## Exporting the Result
 
-After making layer changes, we zoom to fit the page in the viewport so the composition is clearly visible.
+After making layer changes, we export the page as an image to verify the final composition.
 
-```typescript highlight=highlight-zoom
-await engine.scene.zoomToBlock(page, { padding: 40 });
+```typescript highlight=highlight-export
+// Export the page as an image
+mkdirSync('output', { recursive: true });
+const blob = await engine.block.export(page, { mimeType: 'image/png' });
+const buffer = Buffer.from(await blob.arrayBuffer());
+writeFileSync('output/layer-management-result.png', buffer);
+console.log('Exported: output/layer-management-result.png');
 ```
 
 ## Troubleshooting
@@ -477,27 +437,29 @@ await engine.scene.zoomToBlock(page, { padding: 40 });
 
 ## API Reference
 
-| Method                                           | Description                                |
-| ------------------------------------------------ | ------------------------------------------ |
-| `engine.block.getParent(id)`                     | Get the parent block of a given block      |
-| `engine.block.getChildren(id)`                   | Get all child blocks in rendering order    |
-| `engine.block.appendChild(parent, child)`        | Append a block as the last child           |
-| `engine.block.insertChild(parent, child, index)` | Insert a block at a specific position      |
-| `engine.block.bringToFront(id)`                  | Bring a block to the front of its siblings |
-| `engine.block.sendToBack(id)`                    | Send a block to the back of its siblings   |
-| `engine.block.bringForward(id)`                  | Move a block one position forward          |
-| `engine.block.sendBackward(id)`                  | Move a block one position backward         |
-| `engine.block.isVisible(id)`                     | Check if a block is visible                |
-| `engine.block.setVisible(id, visible)`           | Set the visibility of a block              |
-| `engine.block.duplicate(id, attachToParent?)`    | Duplicate a block and its children         |
-| `engine.block.destroy(id)`                       | Remove a block and its children            |
-| `engine.block.isValid(id)`                       | Check if a block handle is valid           |
+| Method | Description |
+| --- | --- |
+| `engine.block.getParent(id)` | Get the parent block of a given block |
+| `engine.block.getChildren(id)` | Get all child blocks in rendering order |
+| `engine.block.appendChild(parent, child)` | Append a block as the last child |
+| `engine.block.insertChild(parent, child, index)` | Insert a block at a specific position |
+| `engine.block.bringToFront(id)` | Bring a block to the front of its siblings |
+| `engine.block.sendToBack(id)` | Send a block to the back of its siblings |
+| `engine.block.bringForward(id)` | Move a block one position forward |
+| `engine.block.sendBackward(id)` | Move a block one position backward |
+| `engine.block.isVisible(id)` | Check if a block is visible |
+| `engine.block.setVisible(id, visible)` | Set the visibility of a block |
+| `engine.block.duplicate(id, attachToParent?)` | Duplicate a block and its children |
+| `engine.block.destroy(id)` | Remove a block and its children |
+| `engine.block.isValid(id)` | Check if a block handle is valid |
+
+
 
 ---
 
 ## More Resources
 
-- **[Vanilla JS/TS Documentation Index](https://img.ly/docs/cesdk/js.md)** - Browse all Vanilla JS/TS documentation
+- **[Node.js Documentation Index](https://img.ly/docs/cesdk/node.md)** - Browse all Node.js documentation
 - **[Complete Documentation](./llms-full.txt.md)** - Full documentation in one file (for LLMs)
-- **[Web Documentation](./js.md)** - Interactive documentation with examples
-- **[Support](mailto:support@img.ly)** - Contact IMG.LY support
+- **[Web Documentation](./node.md)** - Interactive documentation with examples
+- **[Support](mailto:support@img.ly)** - Contact IMG.LY support