@imgly/codesign-mcp 0.1.5 → 0.1.7

package/assets/docs/guide/stickers-and-shapes/create-edit/create-stickers.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 Stickers](./stickers.md) > [Create Stickers](./stickers-and-shapes/create-edit/create-stickers.md)
 
@@ -6,231 +6,155 @@
 
 Create stickers from images for use in your designs, perfect for adding icons, logos, emoji, and detailed multi-color graphics that preserve their original appearance.
 
-![Create stickers from images with two different methods](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-stickers-and-shapes-create-stickers-browser)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-stickers-and-shapes-create-stickers-browser)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-stickers-and-shapes-create-stickers-browser/)
+>
+> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-stickers-and-shapes-create-stickers-server-js)
+>
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-stickers-and-shapes-create-stickers-server-js)
 
 Stickers are graphic blocks with image fills that cannot be recolored. They work well for icons, brand logos, emoji, and complex multi-color graphics. Unlike shapes (which use solid or gradient fills and can be recolored), stickers preserve the original colors and details of the source image.
 
-```typescript file=@cesdk_web_examples/guides-stickers-and-shapes-create-stickers-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';
-
-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: 450, height: 250, unit: 'Pixel' }
-    });
-
-    const engine = cesdk.engine;
-    const page = engine.block.findByType('page')[0];
-
-    // ===== Section 1: Using Convenience API =====
-    // Create sticker using the convenient addImage() method
-    const sticker = await engine.block.addImage(
-      'https://cdn.img.ly/assets/v4/ly.img.sticker/images/emoticons/imgly_sticker_emoticons_grin.svg'
-    );
-
-    // Set size and position (preserve aspect ratio)
-    const naturalWidth = engine.block.getWidth(sticker);
-    const naturalHeight = engine.block.getHeight(sticker);
-    const scale = 80 / Math.max(naturalWidth, naturalHeight);
-    engine.block.setWidth(sticker, naturalWidth * scale);
-    engine.block.setHeight(sticker, naturalHeight * scale);
-    engine.block.setPositionX(sticker, 95);
-    engine.block.setPositionY(sticker, 85);
-
-    // Prevent cropping and mark as sticker
-    if (engine.block.supportsContentFillMode(sticker)) {
-      engine.block.setContentFillMode(sticker, 'Contain');
-    }
-    engine.block.setKind(sticker, 'Sticker');
-
-    // Add to scene
-    engine.block.appendChild(page, sticker);
-
-    // ===== Section 2: Manual Construction =====
-    // Create sticker manually for fine-grained control
-    const manualSticker = engine.block.create('graphic');
-
-    // Set a shape (required for graphic blocks to be visible)
-    engine.block.setShape(manualSticker, engine.block.createShape('rect'));
-
-    // Create and apply image fill
-    const imageFill = engine.block.createFill('image');
-    engine.block.setString(
-      imageFill,
-      'fill/image/imageFileURI',
-      'https://cdn.img.ly/assets/v4/ly.img.sticker/images/emoticons/imgly_sticker_emoticons_blush.svg'
-    );
-    engine.block.setFill(manualSticker, imageFill);
-
-    // Set size and position (preserve aspect ratio)
-    const manualWidth = engine.block.getWidth(manualSticker) || 100;
-    const manualHeight = engine.block.getHeight(manualSticker) || 100;
-    const manualScale = 80 / Math.max(manualWidth, manualHeight);
-    engine.block.setWidth(manualSticker, manualWidth * manualScale);
-    engine.block.setHeight(manualSticker, manualHeight * manualScale);
-    engine.block.setPositionX(manualSticker, 275);
-    engine.block.setPositionY(manualSticker, 85);
-
-    // Prevent cropping and mark as sticker
-    if (engine.block.supportsContentFillMode(manualSticker)) {
-      engine.block.setContentFillMode(manualSticker, 'Contain');
-    }
-    engine.block.setKind(manualSticker, 'Sticker');
-
-    // Add to scene
-    engine.block.appendChild(page, manualSticker);
+```typescript file=@cesdk_web_examples/guides-stickers-and-shapes-create-stickers-server-js/server-js.ts reference-only
+import CreativeEngine from '@cesdk/node';
+import { config } from 'dotenv';
+import { writeFileSync, mkdirSync, existsSync } from 'fs';
+
+// Load environment variables
+config();
+
+/**
+ * CE.SDK Server Guide: Create Stickers
+ *
+ * Demonstrates creating stickers programmatically in Node.js:
+ * - Creating stickers with createFill (manual construction)
+ * - Setting sticker properties
+ * - Creating multiple stickers
+ * - Preserving aspect ratios
+ */
+
+// Initialize CE.SDK engine in headless mode
+const engine = await CreativeEngine.init({
+  baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
+  // license: process.env.CESDK_LICENSE, // Optional (trial mode available)
+});
+
+try {
+  // Create a design scene with specific page dimensions
+  engine.scene.create('VerticalStack', {
+    page: { size: { width: 450, height: 250 } }
+  });
+  const page = engine.block.findByType('page')[0];
+
+  // Create graphic block with image fill
+  const sticker = engine.block.create('graphic');
+
+  // Set a shape (required for graphic blocks to be visible)
+  engine.block.setShape(sticker, engine.block.createShape('rect'));
+
+  // Create and apply image fill
+  const imageFill = engine.block.createFill('image');
+  engine.block.setString(
+    imageFill,
+    'fill/image/imageFileURI',
+    'https://cdn.img.ly/assets/v4/ly.img.sticker/images/emoticons/imgly_sticker_emoticons_grin.svg'
+  );
+  engine.block.setFill(sticker, imageFill);
+
+  // Set size and position (preserve aspect ratio)
+  const naturalWidth = engine.block.getWidth(sticker) || 100;
+  const naturalHeight = engine.block.getHeight(sticker) || 100;
+  const scale = 80 / Math.max(naturalWidth, naturalHeight);
+  engine.block.setWidth(sticker, naturalWidth * scale);
+  engine.block.setHeight(sticker, naturalHeight * scale);
+  engine.block.setPositionX(sticker, 185);
+  engine.block.setPositionY(sticker, 85);
+
+  // Prevent cropping and mark as sticker
+  if (engine.block.supportsContentFillMode(sticker)) {
+    engine.block.setContentFillMode(sticker, 'Contain');
   }
-}
+  engine.block.setKind(sticker, 'Sticker');
 
-export default Example;
-```
+  // Add to scene
+  engine.block.appendChild(page, sticker);
 
-## Creating Stickers from Images
+  // Export the result to PNG
+  const outputDir = './output';
+  if (!existsSync(outputDir)) {
+    mkdirSync(outputDir, { recursive: true });
+  }
 
-We use `engine.block.addImage()` to create stickers quickly. This method creates the graphic block and image fill in one call. After creation, we read the natural dimensions, calculate a scale factor to preserve aspect ratio, and apply the scaled size. We also set the position, content fill mode, and mark it as 'Sticker' for proper editor behavior.
-
-```typescript highlight-convenience-api
-// Create sticker using the convenient addImage() method
-const sticker = await engine.block.addImage(
-  'https://cdn.img.ly/assets/v4/ly.img.sticker/images/emoticons/imgly_sticker_emoticons_grin.svg'
-);
-
-// Set size and position (preserve aspect ratio)
-const naturalWidth = engine.block.getWidth(sticker);
-const naturalHeight = engine.block.getHeight(sticker);
-const scale = 80 / Math.max(naturalWidth, naturalHeight);
-engine.block.setWidth(sticker, naturalWidth * scale);
-engine.block.setHeight(sticker, naturalHeight * scale);
-engine.block.setPositionX(sticker, 95);
-engine.block.setPositionY(sticker, 85);
-
-// Prevent cropping and mark as sticker
-if (engine.block.supportsContentFillMode(sticker)) {
-  engine.block.setContentFillMode(sticker, 'Contain');
-}
-engine.block.setKind(sticker, 'Sticker');
+  const blob = await engine.block.export(page, { mimeType: 'image/png' });
+  const buffer = Buffer.from(await blob.arrayBuffer());
+  writeFileSync(`${outputDir}/create-stickers-result.png`, buffer);
 
-// Add to scene
-engine.block.appendChild(page, sticker);
+  // eslint-disable-next-line no-console
+  console.log('✓ Exported result to output/create-stickers-result.png');
+} finally {
+  // Always dispose the engine to free resources
+  engine.dispose();
+}
 ```
 
-We preserve aspect ratio by scaling the natural dimensions proportionally. The 'Contain' fill mode ensures the entire image displays without cropping. Setting the kind to 'Sticker' prevents recoloring and provides appropriate editor controls.
-
-## Manual Construction
+This guide covers creating stickers from images and setting sticker properties programmatically in a headless Node.js environment.
 
-For fine-grained control, we build stickers step by step using separate API calls. We create the graphic block, set a shape (required for visibility), create an image fill, and apply it to the block. We preserve aspect ratio by reading natural dimensions and scaling proportionally.
-
-```typescript highlight-manual-construction
-// Create sticker manually for fine-grained control
-const manualSticker = engine.block.create('graphic');
-
-// Set a shape (required for graphic blocks to be visible)
-engine.block.setShape(manualSticker, engine.block.createShape('rect'));
-
-// Create and apply image fill
-const imageFill = engine.block.createFill('image');
-engine.block.setString(
-  imageFill,
-  'fill/image/imageFileURI',
-  'https://cdn.img.ly/assets/v4/ly.img.sticker/images/emoticons/imgly_sticker_emoticons_blush.svg'
-);
-engine.block.setFill(manualSticker, imageFill);
-
-// Set size and position (preserve aspect ratio)
-const manualWidth = engine.block.getWidth(manualSticker) || 100;
-const manualHeight = engine.block.getHeight(manualSticker) || 100;
-const manualScale = 80 / Math.max(manualWidth, manualHeight);
-engine.block.setWidth(manualSticker, manualWidth * manualScale);
-engine.block.setHeight(manualSticker, manualHeight * manualScale);
-engine.block.setPositionX(manualSticker, 275);
-engine.block.setPositionY(manualSticker, 85);
+## Creating Stickers from Images
 
-// Prevent cropping and mark as sticker
-if (engine.block.supportsContentFillMode(manualSticker)) {
-  engine.block.setContentFillMode(manualSticker, 'Contain');
-}
-engine.block.setKind(manualSticker, 'Sticker');
+In Node.js environments, we build stickers using manual construction with the block API. We create a graphic block, set a shape (required for visibility), create an image fill, and apply it to the block. We read the natural dimensions, calculate a scale factor to preserve aspect ratio, and apply the scaled size. Setting the kind to 'Sticker' prevents recoloring and provides appropriate editor controls.
+
+```typescript highlight-basic-sticker
+  // Create graphic block with image fill
+  const sticker = engine.block.create('graphic');
+
+  // Set a shape (required for graphic blocks to be visible)
+  engine.block.setShape(sticker, engine.block.createShape('rect'));
+
+  // Create and apply image fill
+  const imageFill = engine.block.createFill('image');
+  engine.block.setString(
+    imageFill,
+    'fill/image/imageFileURI',
+    'https://cdn.img.ly/assets/v4/ly.img.sticker/images/emoticons/imgly_sticker_emoticons_grin.svg'
+  );
+  engine.block.setFill(sticker, imageFill);
+
+  // Set size and position (preserve aspect ratio)
+  const naturalWidth = engine.block.getWidth(sticker) || 100;
+  const naturalHeight = engine.block.getHeight(sticker) || 100;
+  const scale = 80 / Math.max(naturalWidth, naturalHeight);
+  engine.block.setWidth(sticker, naturalWidth * scale);
+  engine.block.setHeight(sticker, naturalHeight * scale);
+  engine.block.setPositionX(sticker, 185);
+  engine.block.setPositionY(sticker, 85);
+
+  // Prevent cropping and mark as sticker
+  if (engine.block.supportsContentFillMode(sticker)) {
+    engine.block.setContentFillMode(sticker, 'Contain');
+  }
+  engine.block.setKind(sticker, 'Sticker');
 
-// Add to scene
-engine.block.appendChild(page, manualSticker);
+  // Add to scene
+  engine.block.appendChild(page, sticker);
 ```
 
-This approach works well when we need to configure multiple properties or reuse fills across blocks.
+We preserve aspect ratio by scaling the natural dimensions proportionally. The 'Contain' fill mode ensures the entire image displays without cropping. Setting a shape is required for graphic blocks to be visible.
 
 ## Sticker vs Shape Decision
 
 Choose between stickers and shapes based on your requirements:
 
-| Requirement               | Use Stickers | Use Shapes         |
-| ------------------------- | ------------ | ------------------ |
-| Multi-color graphics      | ✓ Yes        | ✗ No (single fill) |
-| Recolorable               | ✗ No         | ✓ Yes              |
-| Preserve original artwork | ✓ Yes        | ✗ N/A              |
-| Boolean operations        | ✗ No         | ✓ Yes              |
-| Complex paths/gradients   | ✓ Yes        | ✗ Limited          |
-| Icons, logos, emoji       | ✓ Preferred  | -                  |
+| Requirement | Use Stickers | Use Shapes |
+| --- | --- | --- |
+| Multi-color graphics | ✓ Yes | ✗ No (single fill) |
+| Recolorable | ✗ No | ✓ Yes |
+| Preserve original artwork | ✓ Yes | ✗ N/A |
+| Boolean operations | ✗ No | ✓ Yes |
+| Complex paths/gradients | ✓ Yes | ✗ Limited |
+| Icons, logos, emoji | ✓ Preferred | - |
 
 ## Troubleshooting
 
@@ -254,37 +178,34 @@ Stickers may appear cropped if the content fill mode defaults to 'Cover'. Set th
 
 This is expected behavior—stickers preserve original colors. For recolorable graphics, create shapes with vector paths instead. For simple single-color graphics, consider using a vector path shape.
 
-### Wrong Editor Behavior
+## API Reference
 
-Ensure `engine.block.setKind(id, 'Sticker')` was called. The 'Sticker' kind designation controls editor interactions and UI panels.
+Quick reference for sticker creation methods in Node.js:
+
+| Method | Category | Purpose |
+| --- | --- | --- |
+| `engine.block.create('graphic')` | Creation | Create graphic block manually |
+| `engine.block.createShape('rect')` | Shapes | Create shape (required for visibility) |
+| `engine.block.setShape(graphic, shape)` | Shapes | Apply shape to graphic block |
+| `engine.block.createFill('image')` | Fills | Create image fill |
+| `engine.block.setFill(graphic, fill)` | Fills | Apply fill to graphic block |
+| `engine.block.setString(fill, prop, uri)` | Fills | Set image URI on fill |
+| `engine.block.supportsContentFillMode(id)` | Content | Check if block supports fill mode |
+| `engine.block.setContentFillMode(id, mode)` | Content | Set fill mode ('Contain' or 'Cover') |
+| `engine.block.setKind(id, 'Sticker')` | Configuration | Mark block as sticker |
+| `engine.block.setPositionX/Y(id, val)` | Transform | Set position |
+| `engine.block.setWidth/Height(id, val)` | Transform | Set dimensions |
+| `engine.block.getWidth/Height(id)` | Transform | Get current dimensions |
+| `engine.block.appendChild(parent, child)` | Hierarchy | Add to scene |
+| `engine.block.findByType('page')` | Scene | Find page blocks |
 
-## API Reference
 
-Quick reference for sticker creation methods:
-
-| Method                                      | Category      | Purpose                                   |
-| ------------------------------------------- | ------------- | ----------------------------------------- |
-| `engine.block.addImage(url, options)`       | Creation      | Convenient sticker creation from URL      |
-| `engine.block.create('graphic')`            | Creation      | Create graphic block manually             |
-| `engine.block.createShape('rect')`          | Shapes        | Create shape (required for manual blocks) |
-| `engine.block.setShape(graphic, shape)`     | Shapes        | Apply shape to graphic block              |
-| `engine.block.createFill('image')`          | Fills         | Create image fill                         |
-| `engine.block.setFill(graphic, fill)`       | Fills         | Apply fill to graphic block               |
-| `engine.block.setString(fill, prop, uri)`   | Fills         | Set image URI on fill                     |
-| `engine.block.supportsContentFillMode(id)`  | Content       | Check if block supports fill mode         |
-| `engine.block.setContentFillMode(id, mode)` | Content       | Set fill mode ('Contain' or 'Cover')      |
-| `engine.block.setKind(id, 'Sticker')`       | Configuration | Mark block as sticker                     |
-| `engine.block.setPositionX/Y(id, val)`      | Transform     | Set position                              |
-| `engine.block.setWidth/Height(id, val)`     | Transform     | Set dimensions                            |
-| `engine.block.getWidth/Height(id)`          | Transform     | Get current dimensions                    |
-| `engine.block.appendChild(parent, child)`   | Hierarchy     | Add to scene                              |
-| `engine.scene.getCurrentPage()`             | Scene         | Get current page                          |
 
 ---
 
 ## 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