@imgly/codesign-mcp 0.1.5 → 0.1.6

package/assets/docs/guide/create-composition/blend-modes.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) > [Blend Modes](./create-composition/blend-modes.md)
 
@@ -7,206 +7,107 @@
 Control how design blocks visually blend with underlying layers using CE.SDK's
 blend mode system for professional layered compositions.
 
-![Blend Modes example showing layered images with blend effects applied](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-blend-modes-browser)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-create-composition-blend-modes-browser)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-create-composition-blend-modes-browser/)
+>
+> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-create-composition-blend-modes-server-js)
+>
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-create-composition-blend-modes-server-js)
 
 Blend modes control how a block's colors combine with underlying layers, similar to blend modes in Photoshop or other design tools. CE.SDK provides 27 blend modes organized into categories: Normal, Darken, Lighten, Contrast, Inversion, and Component. Each category serves different compositing needs—darken modes make images darker, lighten modes make them brighter, and contrast modes increase midtone contrast.
 
-```typescript file=@cesdk_web_examples/guides-create-composition-blend-modes-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';
-
-/**
- * CE.SDK Plugin: Blend Modes Guide
- *
- * This example demonstrates:
- * - Checking if a block supports blend modes
- * - Setting blend modes on overlay layers
- * - Getting the current blend mode of a block
- * - Working with opacity values
- * - Available blend mode values
- */
-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');
-    }
-
-    const engine = cesdk.engine;
-    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'] })
+```typescript file=@cesdk_web_examples/guides-create-composition-blend-modes-server-js/server-js.ts reference-only
+import CreativeEngine from '@cesdk/node';
+import * as fs from 'fs';
+import * as dotenv from 'dotenv';
+
+dotenv.config();
+
+async function main() {
+  // Initialize the Creative Engine in headless mode
+  const engine = await CreativeEngine.init({
+    baseURL: process.env.IMGLY_LOCAL_ASSETS_URL,
+    license: process.env.CESDK_LICENSE || 'YOUR_CESDK_LICENSE_KEY'
+  });
+
+  try {
+    // Create a new scene with a design page
+    const scene = engine.scene.create();
+    const page = engine.block.create('page');
+    engine.block.setWidth(page, 800);
+    engine.block.setHeight(page, 600);
+    engine.block.appendChild(scene, page);
+
+    // Create a background image block as the base layer
+    const backgroundBlock = engine.block.create('graphic');
+    engine.block.setWidth(backgroundBlock, 800);
+    engine.block.setHeight(backgroundBlock, 600);
+    engine.block.setPositionX(backgroundBlock, 0);
+    engine.block.setPositionY(backgroundBlock, 0);
+
+    // Set the image fill for the background
+    const backgroundFill = engine.block.createFill('image');
+    engine.block.setString(
+      backgroundFill,
+      'fill/image/imageFileURI',
+      'https://img.ly/static/ubq_samples/sample_1.jpg'
     );
-    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.*'
-        ]
-      })
+    engine.block.setFill(backgroundBlock, backgroundFill);
+    engine.block.appendChild(page, backgroundBlock);
+
+    // Create a second image block on top for blending
+    const overlayBlock = engine.block.create('graphic');
+    engine.block.setWidth(overlayBlock, 800);
+    engine.block.setHeight(overlayBlock, 600);
+    engine.block.setPositionX(overlayBlock, 0);
+    engine.block.setPositionY(overlayBlock, 0);
+
+    // Set a different image fill for the overlay
+    const overlayFill = engine.block.createFill('image');
+    engine.block.setString(
+      overlayFill,
+      'fill/image/imageFileURI',
+      'https://img.ly/static/ubq_samples/sample_2.jpg'
     );
-    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: {
-        sourceId: 'ly.img.page.presets',
-        assetId: 'ly.img.page.presets.print.iso.a6.landscape'
-      }
-    });
-
-    const page = engine.block.findByType('page')[0];
-
-    // Grid configuration: 3 columns x 2 rows
-    const cols = 3;
-    const rows = 2;
-    const cellWidth = 280;
-    const cellHeight = 210;
-    const padding = 20;
-    const pageWidth = cols * cellWidth + (cols + 1) * padding;
-    const pageHeight = rows * cellHeight + (rows + 1) * padding;
-
-    // Set page dimensions
-    engine.block.setWidth(page, pageWidth);
-    engine.block.setHeight(page, pageHeight);
-
-    // Base and overlay image URLs
-    const baseImageUrl = 'https://img.ly/static/ubq_samples/sample_1.jpg';
-    const overlayImageUrl = 'https://img.ly/static/ubq_samples/sample_2.jpg';
-
-    // Six commonly used blend modes to demonstrate
-    const blendModes: Array<
-      'Multiply' | 'Screen' | 'Overlay' | 'Darken' | 'Lighten' | 'ColorBurn'
-    > = ['Multiply', 'Screen', 'Overlay', 'Darken', 'Lighten', 'ColorBurn'];
-
-    // Create 6 image pairs in a grid layout
-    for (let row = 0; row < rows; row++) {
-      for (let col = 0; col < cols; col++) {
-        const index = row * cols + col;
-        const x = padding + col * (cellWidth + padding);
-        const y = padding + row * (cellHeight + padding);
-
-        // Create a background image block as the base layer
-        const backgroundBlock = engine.block.create('graphic');
-        const backgroundShape = engine.block.createShape('rect');
-        engine.block.setShape(backgroundBlock, backgroundShape);
-        engine.block.setWidth(backgroundBlock, cellWidth);
-        engine.block.setHeight(backgroundBlock, cellHeight);
-        engine.block.setPositionX(backgroundBlock, x);
-        engine.block.setPositionY(backgroundBlock, y);
-
-        // Set the image fill for the background
-        const backgroundFill = engine.block.createFill('image');
-        engine.block.setString(
-          backgroundFill,
-          'fill/image/imageFileURI',
-          baseImageUrl
-        );
-        engine.block.setFill(backgroundBlock, backgroundFill);
-        engine.block.setContentFillMode(backgroundBlock, 'Cover');
-        engine.block.appendChild(page, backgroundBlock);
-
-        // Create a second image block on top for blending
-        const overlayBlock = engine.block.create('graphic');
-        const overlayShape = engine.block.createShape('rect');
-        engine.block.setShape(overlayBlock, overlayShape);
-        engine.block.setWidth(overlayBlock, cellWidth);
-        engine.block.setHeight(overlayBlock, cellHeight);
-        engine.block.setPositionX(overlayBlock, x);
-        engine.block.setPositionY(overlayBlock, y);
-
-        // Set a different image fill for the overlay
-        const overlayFill = engine.block.createFill('image');
-        engine.block.setString(
-          overlayFill,
-          'fill/image/imageFileURI',
-          overlayImageUrl
-        );
-        engine.block.setFill(overlayBlock, overlayFill);
-        engine.block.setContentFillMode(overlayBlock, 'Cover');
-        engine.block.appendChild(page, overlayBlock);
-
-        // Check if the block supports blend modes before applying
-        if (engine.block.supportsBlendMode(overlayBlock)) {
-          // Apply a different blend mode to each overlay
-          const blendMode = blendModes[index];
-          engine.block.setBlendMode(overlayBlock, blendMode);
-
-          // Retrieve and log the current blend mode
-          const currentMode = engine.block.getBlendMode(overlayBlock);
-          // eslint-disable-next-line no-console
-          console.log(`Cell ${index + 1} blend mode:`, currentMode);
-        }
-
-        // Check if the block supports opacity
-        if (engine.block.supportsOpacity(overlayBlock)) {
-          // Set the opacity to 80% for clear visibility
-          engine.block.setOpacity(overlayBlock, 0.8);
-        }
-
-        // Retrieve and log the opacity value
-        const opacity = engine.block.getOpacity(overlayBlock);
-        // eslint-disable-next-line no-console
-        console.log(`Cell ${index + 1} opacity:`, opacity);
-      }
+    engine.block.setFill(overlayBlock, overlayFill);
+    engine.block.appendChild(page, overlayBlock);
+
+    // Check if the block supports blend modes before applying
+    if (engine.block.supportsBlendMode(overlayBlock)) {
+
+      // Apply the Multiply blend mode to the overlay
+      engine.block.setBlendMode(overlayBlock, 'Multiply');
+
+      // Retrieve and log the current blend mode
+      const currentMode = engine.block.getBlendMode(overlayBlock);
+      console.log('Current blend mode:', currentMode);
+    }
+
+    // Check if the block supports opacity
+    if (engine.block.supportsOpacity(overlayBlock)) {
+      // Set the opacity to 70%
+      engine.block.setOpacity(overlayBlock, 0.7);
     }
 
-    // Zoom to fit the composition
-    await engine.scene.zoomToBlock(page, {
-      padding: {
-        left: 40,
-        top: 40,
-        right: 40,
-        bottom: 40
-      }
-    });
+    // Retrieve and log the opacity value
+    const opacity = engine.block.getOpacity(overlayBlock);
+    console.log('Current opacity:', opacity);
+
+    // Export the blended composition to a PNG file
+    const blob = await engine.block.export(page, { mimeType: 'image/png' });
+    const buffer = Buffer.from(await blob.arrayBuffer());
+    fs.writeFileSync('output.png', buffer);
+    console.log('Exported blended composition to output.png');
+  } finally {
+    // Always dispose of the engine when done
+    engine.dispose();
   }
 }
 
-export default Example;
+main().catch(console.error);
 ```
 
 This guide covers how to check blend mode support, apply blend modes programmatically, understand the available blend mode options, and combine blend modes with opacity for fine control over layer compositing.
@@ -227,9 +128,8 @@ Blend mode support is available for graphic blocks with image or video fills, sh
 Apply a blend mode with `setBlendMode()` and retrieve the current mode with `getBlendMode()`. The default blend mode is `'Normal'`, which displays the block without any blending effect.
 
 ```typescript highlight-set-blend-mode
-// Apply a different blend mode to each overlay
-const blendMode = blendModes[index];
-engine.block.setBlendMode(overlayBlock, blendMode);
+// Apply the Multiply blend mode to the overlay
+engine.block.setBlendMode(overlayBlock, 'Multiply');
 ```
 
 After setting a blend mode, you can confirm the change by retrieving the current value:
@@ -237,8 +137,7 @@ After setting a blend mode, you can confirm the change by retrieving the current
 ```typescript highlight-get-blend-mode
 // Retrieve and log the current blend mode
 const currentMode = engine.block.getBlendMode(overlayBlock);
-// eslint-disable-next-line no-console
-console.log(`Cell ${index + 1} blend mode:`, currentMode);
+console.log('Current blend mode:', currentMode);
 ```
 
 ## Available Blend Modes
@@ -307,8 +206,8 @@ For finer control over compositing, combine blend modes with opacity. Opacity re
 ```typescript highlight-set-opacity
 // Check if the block supports opacity
 if (engine.block.supportsOpacity(overlayBlock)) {
-  // Set the opacity to 80% for clear visibility
-  engine.block.setOpacity(overlayBlock, 0.8);
+  // Set the opacity to 70%
+  engine.block.setOpacity(overlayBlock, 0.7);
 }
 ```
 
@@ -317,13 +216,20 @@ You can retrieve the current opacity value to confirm changes or read existing s
 ```typescript highlight-get-opacity
 // Retrieve and log the opacity value
 const opacity = engine.block.getOpacity(overlayBlock);
-// eslint-disable-next-line no-console
-console.log(`Cell ${index + 1} opacity:`, opacity);
+console.log('Current opacity:', opacity);
 ```
 
-> **Tip:** Start with full opacity (1.0) when experimenting with blend modes, then reduce
-> opacity to soften the effect. Common values are 0.5-0.7 for subtle blending
-> effects.
+## Exporting the Result
+
+After applying blend modes and opacity, export the composed result to a file. The blended composition is rendered and saved as an image.
+
+```typescript highlight-export
+// Export the blended composition to a PNG file
+const blob = await engine.block.export(page, { mimeType: 'image/png' });
+const buffer = Buffer.from(await blob.arrayBuffer());
+fs.writeFileSync('output.png', buffer);
+console.log('Exported blended composition to output.png');
+```
 
 ## Troubleshooting
 
@@ -353,20 +259,23 @@ If the visual result doesn't match expectations:
 
 ## API Reference
 
-| Method                                 | Description                           |
-| -------------------------------------- | ------------------------------------- |
-| `engine.block.supportsBlendMode(id)`   | Check if a block supports blend modes |
-| `engine.block.setBlendMode(id, mode)`  | Set the blend mode for a block        |
-| `engine.block.getBlendMode(id)`        | Get the current blend mode of a block |
-| `engine.block.supportsOpacity(id)`     | Check if a block supports opacity     |
-| `engine.block.setOpacity(id, opacity)` | Set the opacity for a block (0-1)     |
-| `engine.block.getOpacity(id)`          | Get the current opacity of a block    |
+| Method                                   | Description                                       |
+| ---------------------------------------- | ------------------------------------------------- |
+| `engine.block.supportsBlendMode(id)`     | Check if a block supports blend modes             |
+| `engine.block.setBlendMode(id, mode)`    | Set the blend mode for a block                    |
+| `engine.block.getBlendMode(id)`          | Get the current blend mode of a block             |
+| `engine.block.supportsOpacity(id)`       | Check if a block supports opacity                 |
+| `engine.block.setOpacity(id, opacity)`   | Set the opacity for a block (0-1)                 |
+| `engine.block.getOpacity(id)`            | Get the current opacity of a block                |
+| `engine.block.export(id, mimeType)`      | Export block content to specified format          |
+
+
 
 ---
 
 ## 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