@imgly/codesign-mcp 0.1.5 → 0.1.6

package/assets/docs/guide/colors/apply.md

@@ -1,103 +1,40 @@
-> 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) > [Colors](./colors.md) > [Apply Color](./colors/apply.md)
 
 ---
 
-Apply solid colors to design elements like shapes, text, and backgrounds using CE.SDK's color system with support for RGB, CMYK, and spot colors.
-
-![Apply Colors example showing a block with fill, stroke, and shadow colors applied](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
+Apply solid colors to design elements programmatically using CE.SDK's color system with support for RGB, CMYK, and spot colors in server-side Node.js applications.
 
 > **Reading time:** 8 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-colors-apply-browser)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-colors-apply-browser)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-colors-apply-browser/)
+>
+> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-colors-apply-server-js)
+>
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-colors-apply-server-js)
 
 Colors in CE.SDK are applied to block properties like fill, stroke, and shadow using `engine.block.setColor()`. The engine supports three color spaces: sRGB for screen display, CMYK for print production, and spot colors for specialized printing requirements.
 
-```typescript file=@cesdk_web_examples/guides-colors-apply-browser/browser.ts reference-only
-import type {
-  EditorPlugin,
-  EditorPluginContext,
-  RGBAColor
-} 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: Apply Colors Guide
- *
- * Demonstrates how to apply solid colors to design elements:
- * - Creating color objects in RGB, CMYK, and spot color spaces
- * - Applying colors to fill, stroke, and shadow properties
- * - Defining and managing spot colors
- * - Converting colors between color spaces
- */
-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];
+```typescript file=@cesdk_web_examples/guides-colors-apply-server-js/server-js.ts reference-only
+import CreativeEngine, { RGBAColor } from '@cesdk/node';
+import * as fs from 'fs';
+
+async function main() {
+  const engine = await CreativeEngine.init({
+    baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
+    // license: 'YOUR_CESDK_LICENSE_KEY'
+  });
+
+  try {
+    // Create a scene with a 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 graphic block to apply colors to
     const block = engine.block.create('graphic');
@@ -119,7 +56,7 @@ class Example implements EditorPlugin {
     const spotPink = {
       name: 'Pink-Flamingo',
       tint: 1.0,
-      externalReference: 'Pantone'
+      externalReference: 'Brand-Colors'
     };
 
     // Define spot colors with screen preview approximations
@@ -136,13 +73,13 @@ class Example implements EditorPlugin {
 
     // Enable and apply stroke color
     engine.block.setStrokeEnabled(block, true);
-    engine.block.setStrokeWidth(block, 4);
+    engine.block.setStrokeWidth(block, 8);
     engine.block.setColor(block, 'stroke/color', cmykRed);
 
     // Enable and apply drop shadow color
     engine.block.setDropShadowEnabled(block, true);
-    engine.block.setDropShadowOffsetX(block, 5);
-    engine.block.setDropShadowOffsetY(block, 5);
+    engine.block.setDropShadowOffsetX(block, 10);
+    engine.block.setDropShadowOffsetY(block, 10);
     engine.block.setColor(block, 'dropShadow/color', spotPink);
 
     // Convert colors between color spaces
@@ -167,35 +104,68 @@ class Example implements EditorPlugin {
     engine.editor.removeSpotColor('Corporate-Blue');
     console.log('Removed Corporate-Blue spot color');
 
-    // Select the block to show in the editor
-    engine.block.select(block);
-
-    console.log('Apply colors guide initialized.');
+    // Export the scene with applied colors
+    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 scene to output.png');
+  } finally {
+    engine.dispose();
   }
 }
 
-export default Example;
+main().catch(console.error);
 ```
 
 This guide covers how to create color objects in different color spaces, apply colors to fill, stroke, and shadow properties, work with spot colors including defining and managing them, and convert colors between color spaces.
 
+## Initialize the Engine
+
+We start by initializing the headless Creative Engine with a scene and page for our color application workflow.
+
+```typescript highlight=highlight-setup
+async function main() {
+  const engine = await CreativeEngine.init({
+    baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
+    // license: 'YOUR_CESDK_LICENSE_KEY'
+  });
+
+  try {
+    // Create a scene with a 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 graphic block to apply colors to
+    const block = engine.block.create('graphic');
+    engine.block.setShape(block, engine.block.createShape('rect'));
+    engine.block.setFill(block, engine.block.createFill('color'));
+    engine.block.setWidth(block, 200);
+    engine.block.setHeight(block, 150);
+    engine.block.setPositionX(block, 100);
+    engine.block.setPositionY(block, 100);
+    engine.block.appendChild(page, block);
+```
+
 ## Create Color Objects
 
 CE.SDK represents colors as JavaScript objects with properties specific to each color space. We create color objects that match our target output—RGB for screens, CMYK for print, or spot colors for precise color matching.
 
 ```typescript highlight=highlight-create-colors
-// Create RGB color (values 0.0-1.0)
-const rgbaBlue: RGBAColor = { r: 0.0, g: 0.0, b: 1.0, a: 1.0 };
-
-// Create CMYK color (cyan, magenta, yellow, black, tint)
-const cmykRed = { c: 0.0, m: 1.0, y: 1.0, k: 0.0, tint: 1.0 };
-
-// Create spot color reference
-const spotPink = {
-  name: 'Pink-Flamingo',
-  tint: 1.0,
-  externalReference: 'Pantone'
-};
+    // Create RGB color (values 0.0-1.0)
+    const rgbaBlue: RGBAColor = { r: 0.0, g: 0.0, b: 1.0, a: 1.0 };
+
+    // Create CMYK color (cyan, magenta, yellow, black, tint)
+    const cmykRed = { c: 0.0, m: 1.0, y: 1.0, k: 0.0, tint: 1.0 };
+
+    // Create spot color reference
+    const spotPink = {
+      name: 'Pink-Flamingo',
+      tint: 1.0,
+      externalReference: 'Brand-Colors'
+    };
 ```
 
 RGB colors use `{ r, g, b, a }` with values from 0.0 to 1.0 for each channel, where `a` is alpha (opacity). CMYK colors use `{ c, m, y, k, tint }` where tint controls the overall intensity. Spot colors use `{ name, tint, externalReference }` to reference a defined spot color by name.
@@ -217,13 +187,13 @@ Use `engine.editor.setSpotColorRGB()` to define the RGB approximation with red,
 To set a block's fill color, we first get the fill block using `engine.block.getFill()`, then apply the color using `engine.block.setColor()` with the `'fill/color/value'` property.
 
 ```typescript highlight=highlight-apply-fill
-// Apply RGB color to fill
-const fill = engine.block.getFill(block);
-engine.block.setColor(fill, 'fill/color/value', rgbaBlue);
+    // Apply RGB color to fill
+    const fill = engine.block.getFill(block);
+    engine.block.setColor(fill, 'fill/color/value', rgbaBlue);
 
-// Read the current fill color
-const currentFillColor = engine.block.getColor(fill, 'fill/color/value');
-console.log('Current fill color:', currentFillColor);
+    // Read the current fill color
+    const currentFillColor = engine.block.getColor(fill, 'fill/color/value');
+    console.log('Current fill color:', currentFillColor);
 ```
 
 The fill block is a separate entity from the design block. We can read the current color using `engine.block.getColor()` with the same property path.
@@ -235,7 +205,7 @@ Stroke colors are applied directly to the design block using the `'stroke/color'
 ```typescript highlight=highlight-apply-stroke
 // Enable and apply stroke color
 engine.block.setStrokeEnabled(block, true);
-engine.block.setStrokeWidth(block, 4);
+engine.block.setStrokeWidth(block, 8);
 engine.block.setColor(block, 'stroke/color', cmykRed);
 ```
 
@@ -248,8 +218,8 @@ Drop shadow colors use the `'dropShadow/color'` property on the design block. En
 ```typescript highlight=highlight-apply-shadow
 // Enable and apply drop shadow color
 engine.block.setDropShadowEnabled(block, true);
-engine.block.setDropShadowOffsetX(block, 5);
-engine.block.setDropShadowOffsetY(block, 5);
+engine.block.setDropShadowOffsetX(block, 10);
+engine.block.setDropShadowOffsetY(block, 10);
 engine.block.setColor(block, 'dropShadow/color', spotPink);
 ```
 
@@ -260,12 +230,15 @@ Control the shadow position using `setDropShadowOffsetX()` and `setDropShadowOff
 Use `engine.editor.convertColorToColorSpace()` to convert any color to a different color space. This is useful when you need to output designs in a specific color format.
 
 ```typescript highlight=highlight-convert-color
-// Convert colors between color spaces
-const cmykFromRgb = engine.editor.convertColorToColorSpace(rgbaBlue, 'CMYK');
-console.log('CMYK from RGB:', cmykFromRgb);
+    // Convert colors between color spaces
+    const cmykFromRgb = engine.editor.convertColorToColorSpace(
+      rgbaBlue,
+      'CMYK'
+    );
+    console.log('CMYK from RGB:', cmykFromRgb);
 
-const rgbFromCmyk = engine.editor.convertColorToColorSpace(cmykRed, 'sRGB');
-console.log('RGB from CMYK:', rgbFromCmyk);
+    const rgbFromCmyk = engine.editor.convertColorToColorSpace(cmykRed, 'sRGB');
+    console.log('RGB from CMYK:', rgbFromCmyk);
 ```
 
 Pass the source color object and target color space (`'sRGB'` or `'CMYK'`). Spot colors convert to their defined approximation in the target space. Note that color conversions are approximations—CMYK has a smaller color gamut than sRGB.
@@ -280,7 +253,7 @@ const allSpotColors = engine.editor.findAllSpotColors();
 console.log('Defined spot colors:', allSpotColors);
 ```
 
-This is useful for building color pickers or validating that required spot colors are defined before export.
+This is useful for batch processing workflows or validating that required spot colors are defined before export.
 
 ## Update Spot Color Definitions
 
@@ -292,7 +265,7 @@ engine.editor.setSpotColorRGB('Pink-Flamingo', 1.0, 0.6, 0.8);
 console.log('Updated Pink-Flamingo spot color');
 ```
 
-This allows you to adjust how spot colors appear on screen without modifying every block that uses them.
+This allows you to adjust how spot colors appear without modifying every block that uses them.
 
 ## Remove Spot Color Definitions
 
@@ -306,6 +279,20 @@ console.log('Removed Corporate-Blue spot color');
 
 This is useful when cleaning up unused spot colors or when you need to signal that a spot color is no longer valid.
 
+## Export and Cleanup
+
+After applying colors, we export the result to a file and dispose of the engine to free resources.
+
+```typescript highlight=highlight-export
+// Export the scene with applied colors
+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 scene to output.png');
+```
+
+Always dispose of the engine in a finally block to ensure resources are freed even if an error occurs.
+
 ## Troubleshooting
 
 ### Spot Color Appears Magenta
@@ -326,24 +313,26 @@ Apply colors to the fill block obtained from `getFill()`, not the parent design
 
 ## API Reference
 
-| Method                                               | Description                                 |
-| ---------------------------------------------------- | ------------------------------------------- |
-| `block.setColor(block, property, color)`             | Set a color property on a block             |
-| `block.getColor(block, property)`                    | Get a color property from a block           |
-| `block.getFill(block)`                               | Get the fill block of a design block        |
-| `block.setStrokeEnabled(block, enabled)`             | Enable or disable stroke on a block         |
-| `block.setDropShadowEnabled(block, enabled)`         | Enable or disable drop shadow on a block    |
-| `editor.setSpotColorRGB(name, r, g, b)`              | Define a spot color with RGB approximation  |
-| `editor.setSpotColorCMYK(name, c, m, y, k)`          | Define a spot color with CMYK approximation |
-| `editor.findAllSpotColors()`                         | List all defined spot colors                |
-| `editor.removeSpotColor(name)`                       | Remove a spot color definition              |
-| `editor.convertColorToColorSpace(color, colorSpace)` | Convert a color to a different color space  |
+| Method | Description |
+|--------|-------------|
+| `block.setColor(block, property, color)` | Set a color property on a block |
+| `block.getColor(block, property)` | Get a color property from a block |
+| `block.getFill(block)` | Get the fill block of a design block |
+| `block.setStrokeEnabled(block, enabled)` | Enable or disable stroke on a block |
+| `block.setDropShadowEnabled(block, enabled)` | Enable or disable drop shadow on a block |
+| `editor.setSpotColorRGB(name, r, g, b)` | Define a spot color with RGB approximation |
+| `editor.setSpotColorCMYK(name, c, m, y, k)` | Define a spot color with CMYK approximation |
+| `editor.findAllSpotColors()` | List all defined spot colors |
+| `editor.removeSpotColor(name)` | Remove a spot color definition |
+| `editor.convertColorToColorSpace(color, colorSpace)` | Convert a color to a different color space |
+
+
 
 ---
 
 ## 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