@imgly/codesign-mcp 0.1.5 → 0.1.7

package/assets/docs/guide/insert-media/images.md

@@ -1,100 +1,78 @@
-> 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) > [Insert Media Assets](./insert-media.md) > [Insert Images](./insert-media/images.md)
 
 ---
 
-Insert images into your designs programmatically using CE.SDK's engine API.
-
-![Insert Images example showing multiple images placed on a canvas](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
+Insert images into your designs programmatically using CE.SDK's image APIs in a headless Node.js environment.
 
 > **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-insert-media-images-browser)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-insert-media-images-browser)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-insert-media-images-browser/)
+>
+> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-insert-media-images-server-js)
+>
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-insert-media-images-server-js)
 
 Images in CE.SDK are graphic blocks with image fills attached. The engine supports multiple image formats including PNG, JPEG, WebP, GIF, and SVG. You can insert images using either the convenience API for quick setup or manual construction for fine-grained control over the image block components.
 
-```typescript file=@cesdk_web_examples/guides-insert-media-images-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-insert-media-images-server-js/server-js.ts reference-only
+import CreativeEngine from '@cesdk/node';
+import { writeFileSync, mkdirSync, existsSync } from 'fs';
+import { createInterface } from 'readline';
+import { config } from 'dotenv';
+
+// Load environment variables
+config();
+
+// Prompt user to confirm export
+async function confirmExport(): Promise<boolean> {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  return new Promise((resolve) => {
+    rl.question('\nExport design to PNG? [Y/n]: ', (answer) => {
+      rl.close();
+      const normalized = answer.trim().toLowerCase();
+      resolve(normalized === '' || normalized === 'y' || normalized === 'yes');
+    });
+  });
+}
 
 /**
- * CE.SDK Plugin: Insert Images Guide
+ * CE.SDK Server Guide: Insert Images
  *
- * Demonstrates inserting images into a scene programmatically:
+ * Demonstrates inserting images into designs:
  * - Using the convenience API (addImage)
  * - Manual construction with graphic blocks and image fills
  * - Configuring image sizing, positioning, and content fill mode
  * - Applying corner radius for rounded images
- * - Working with multiple images
  */
-class Example implements EditorPlugin {
-  name = packageJson.name;
+async function main() {
+  console.log('\n⏳ Initializing CE.SDK engine...');
 
-  version = packageJson.version;
+  // Initialize the headless Creative Engine
+  const engine = await CreativeEngine.init({
+    baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
+    // license: process.env.CESDK_LICENSE
+  });
 
-  async initialize({ cesdk }: EditorPluginContext): Promise<void> {
-    if (!cesdk) {
-      throw new Error('CE.SDK instance is required for this plugin');
-    }
+  try {
+    console.log('⏳ Creating scene and adding images...');
 
-    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' }
+    // Create a scene with a page
+    engine.scene.create('VerticalStack', {
+      page: { size: { width: 800, height: 600 } }
     });
 
-    const engine = cesdk.engine;
     const page = engine.block.findByType('page')[0];
+    if (!engine.block.isValid(page)) {
+      throw new Error('No page found');
+    }
 
     // Sample image URL for demonstrations
     const imageUrl = 'https://img.ly/static/ubq_samples/sample_1.jpg';
@@ -171,66 +149,59 @@ class Example implements EditorPlugin {
     }
     console.log('✓ Added multiple images');
 
-    // Select the first image block to show it in the inspector
-    engine.block.setSelected(imageBlock, true);
-
-    // Zoom to show all content
-    cesdk.engine.scene.zoomToBlock(page, {
-      padding: {
-        top: 40,
-        bottom: 40,
-        left: 40,
-        right: 40
+    // Export the result to a file after user confirmation
+    const shouldExport = await confirmExport();
+    if (shouldExport) {
+      console.log('\n⏳ Exporting design...');
+      const outputDir = './output';
+      if (!existsSync(outputDir)) {
+        mkdirSync(outputDir, { recursive: true });
       }
-    });
+
+      const blob = await engine.block.export(page, { mimeType: 'image/png' });
+      const buffer = Buffer.from(await blob.arrayBuffer());
+      const outputPath = `${outputDir}/images.png`;
+      writeFileSync(outputPath, buffer);
+
+      console.log(`\n✅ Exported result to ${outputPath}`);
+    } else {
+      console.log('\n⏭️ Export skipped.');
+    }
+  } finally {
+    // Always dispose of the engine to free resources
+    engine.dispose();
+    console.log('🧹 Engine disposed');
   }
 }
 
-export default Example;
+main().catch(console.error);
 ```
 
 This guide covers how to add images using the convenience API, manually construct image blocks, configure content fill modes, apply corner radius, and work with multiple images.
 
 ## Initialize CE.SDK
 
-We start by initializing CE.SDK and creating a scene with a page to hold our images.
+We start by initializing the headless CE.SDK engine and creating a scene with a page to hold our images.
 
 ```typescript highlight=highlight-setup
-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' }
-});
+  // Initialize the headless Creative Engine
+  const engine = await CreativeEngine.init({
+    baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
+    // license: process.env.CESDK_LICENSE
+  });
+
+  try {
+    console.log('⏳ Creating scene and adding images...');
+
+    // Create a scene with a page
+    engine.scene.create('VerticalStack', {
+      page: { size: { width: 800, height: 600 } }
+    });
 
-const engine = cesdk.engine;
-const page = engine.block.findByType('page')[0];
+    const page = engine.block.findByType('page')[0];
+    if (!engine.block.isValid(page)) {
+      throw new Error('No page found');
+    }
 ```
 
 ## Using the Convenience API
@@ -256,25 +227,25 @@ For control over individual components, we can manually construct a graphic bloc
 We create a graphic block with `create('graphic')`, attach a rectangular shape with `createShape('rect')`, and create an image fill with `createFill('image')`. The image source is set using `setString()` with the `fill/image/imageFileURI` property.
 
 ```typescript highlight=highlight-manual-construction
-// Manually construct an image block for more control
-const manualBlock = engine.block.create('graphic');
-
-// Create and attach a rectangular shape
-const shape = engine.block.createShape('rect');
-engine.block.setShape(manualBlock, shape);
-
-// Create and configure the image fill
-const fill = engine.block.createFill('image');
-engine.block.setString(fill, 'fill/image/imageFileURI', imageUrl);
-engine.block.setFill(manualBlock, fill);
-
-// Set dimensions and position
-engine.block.setWidth(manualBlock, 200);
-engine.block.setHeight(manualBlock, 150);
-engine.block.setPositionX(manualBlock, 300);
-engine.block.setPositionY(manualBlock, 50);
-engine.block.appendChild(page, manualBlock);
-console.log('✓ Added image using manual construction');
+    // Manually construct an image block for more control
+    const manualBlock = engine.block.create('graphic');
+
+    // Create and attach a rectangular shape
+    const shape = engine.block.createShape('rect');
+    engine.block.setShape(manualBlock, shape);
+
+    // Create and configure the image fill
+    const fill = engine.block.createFill('image');
+    engine.block.setString(fill, 'fill/image/imageFileURI', imageUrl);
+    engine.block.setFill(manualBlock, fill);
+
+    // Set dimensions and position
+    engine.block.setWidth(manualBlock, 200);
+    engine.block.setHeight(manualBlock, 150);
+    engine.block.setPositionX(manualBlock, 300);
+    engine.block.setPositionY(manualBlock, 50);
+    engine.block.appendChild(page, manualBlock);
+    console.log('✓ Added image using manual construction');
 ```
 
 ## Set Content Fill Mode
@@ -288,20 +259,20 @@ The content fill mode controls how images scale within their bounds. Use `setCon
 Check `supportsContentFillMode()` before setting to ensure the block supports this feature.
 
 ```typescript highlight=highlight-content-fill-mode
-// Set content fill mode to control how images scale within bounds
-// 'Contain' preserves aspect ratio and fits within bounds
-// 'Cover' preserves aspect ratio and fills bounds
-const containBlock = await engine.block.addImage(imageUrl, {
-  size: { width: 200, height: 150 },
-  x: 550,
-  y: 50
-});
-engine.block.appendChild(page, containBlock);
+    // Set content fill mode to control how images scale within bounds
+    // 'Contain' preserves aspect ratio and fits within bounds
+    // 'Cover' preserves aspect ratio and fills bounds
+    const containBlock = await engine.block.addImage(imageUrl, {
+      size: { width: 200, height: 150 },
+      x: 550,
+      y: 50
+    });
+    engine.block.appendChild(page, containBlock);
 
-if (engine.block.supportsContentFillMode(containBlock)) {
-  engine.block.setContentFillMode(containBlock, 'Contain');
-  console.log('✓ Applied Contain fill mode');
-}
+    if (engine.block.supportsContentFillMode(containBlock)) {
+      engine.block.setContentFillMode(containBlock, 'Contain');
+      console.log('✓ Applied Contain fill mode');
+    }
 ```
 
 ## Apply Corner Radius
@@ -325,56 +296,87 @@ console.log('✓ Added image with rounded corners');
 Insert multiple images by iterating over an array of image URLs. Each image gets its own graphic block with calculated positioning to arrange them on the page.
 
 ```typescript highlight=highlight-multiple-images
-// Insert multiple images with calculated positioning
-const imageUrls = [
-  'https://img.ly/static/ubq_samples/sample_1.jpg',
-  'https://img.ly/static/ubq_samples/sample_2.jpg',
-  'https://img.ly/static/ubq_samples/sample_3.jpg'
-];
-
-for (let i = 0; i < imageUrls.length; i++) {
-  const block = await engine.block.addImage(imageUrls[i], {
-    size: { width: 150, height: 100 },
-    x: 300 + i * 160,
-    y: 250
-  });
-  engine.block.appendChild(page, block);
-}
-console.log('✓ Added multiple images');
+    // Insert multiple images with calculated positioning
+    const imageUrls = [
+      'https://img.ly/static/ubq_samples/sample_1.jpg',
+      'https://img.ly/static/ubq_samples/sample_2.jpg',
+      'https://img.ly/static/ubq_samples/sample_3.jpg'
+    ];
+
+    for (let i = 0; i < imageUrls.length; i++) {
+      const block = await engine.block.addImage(imageUrls[i], {
+        size: { width: 150, height: 100 },
+        x: 300 + i * 160,
+        y: 250
+      });
+      engine.block.appendChild(page, block);
+    }
+    console.log('✓ Added multiple images');
 ```
 
-## Next Steps
+## Export and Cleanup
+
+After adding images, we export the design to a PNG file and dispose of the engine to free resources.
+
+```typescript highlight=highlight-export
+    // Export the result to a file after user confirmation
+    const shouldExport = await confirmExport();
+    if (shouldExport) {
+      console.log('\n⏳ Exporting design...');
+      const outputDir = './output';
+      if (!existsSync(outputDir)) {
+        mkdirSync(outputDir, { recursive: true });
+      }
 
-After inserting an image, you can:
+      const blob = await engine.block.export(page, { mimeType: 'image/png' });
+      const buffer = Buffer.from(await blob.arrayBuffer());
+      const outputPath = `${outputDir}/images.png`;
+      writeFileSync(outputPath, buffer);
 
-- [Edit and transform](./edit-image.md) the image
-- [Apply filters and effects](./filters-and-effects.md)
-- [Export your design](./export-save-publish/export.md)
+      console.log(`\n✅ Exported result to ${outputPath}`);
+    } else {
+      console.log('\n⏭️ Export skipped.');
+    }
+```
+
+Always dispose of the engine when done to prevent memory leaks.
+
+```typescript highlight=highlight-cleanup
+// Always dispose of the engine to free resources
+engine.dispose();
+console.log('🧹 Engine disposed');
+```
 
 ## API Reference
 
-| Method                                          | Description                                                   |
-| ----------------------------------------------- | ------------------------------------------------------------- |
-| `engine.block.addImage(url, options?)`          | Convenience API to create an image block with automatic setup |
-| `engine.block.create('graphic')`                | Create a graphic block container for images                   |
-| `engine.block.createShape('rect')`              | Create a rectangular shape for the image                      |
-| `engine.block.setShape(block, shape)`           | Attach shape to graphic block                                 |
-| `engine.block.createFill('image')`              | Create an image fill                                          |
-| `engine.block.setFill(block, fill)`             | Apply fill to block                                           |
-| `engine.block.setString(fill, property, value)` | Set image source URI via `fill/image/imageFileURI`            |
-| `engine.block.setWidth(block, width)`           | Set block width                                               |
-| `engine.block.setHeight(block, height)`         | Set block height                                              |
-| `engine.block.setPositionX(block, x)`           | Set horizontal position                                       |
-| `engine.block.setPositionY(block, y)`           | Set vertical position                                         |
-| `engine.block.supportsContentFillMode(block)`   | Check if block supports content fill mode                     |
-| `engine.block.setContentFillMode(block, mode)`  | Set content fill mode (`Contain`, `Cover`, `Crop`)            |
-| `engine.block.appendChild(parent, child)`       | Add block to parent                                           |
+| Method | Description |
+|--------|-------------|
+| `engine.block.addImage(url, options?)` | Convenience API to create an image block with automatic setup |
+| `engine.block.create('graphic')` | Create a graphic block container for images |
+| `engine.block.createShape('rect')` | Create a rectangular shape for the image |
+| `engine.block.setShape(block, shape)` | Attach shape to graphic block |
+| `engine.block.createFill('image')` | Create an image fill |
+| `engine.block.setFill(block, fill)` | Apply fill to block |
+| `engine.block.setString(fill, property, value)` | Set image source URI via `fill/image/imageFileURI` |
+| `engine.block.setWidth(block, width)` | Set block width |
+| `engine.block.setHeight(block, height)` | Set block height |
+| `engine.block.setPositionX(block, x)` | Set horizontal position |
+| `engine.block.setPositionY(block, y)` | Set vertical position |
+| `engine.block.supportsContentFillMode(block)` | Check if block supports content fill mode |
+| `engine.block.setContentFillMode(block, mode)` | Set content fill mode (`Contain`, `Cover`, `Crop`) |
+| `engine.block.appendChild(parent, child)` | Add block to parent |
+| `engine.block.export(block, options)` | Export block to image blob |
+| `engine.scene.create(layout, options?)` | Create a new scene |
+| `engine.block.findByType(type)` | Find blocks by type |
+| `engine.dispose()` | Dispose engine and free resources |
+
+
 
 ---
 
 ## 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