@imgly/codesign-mcp 0.1.5 → 0.1.7

package/assets/docs/guide/colors/basics.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) > [Colors](./colors.md) > [Basics](./colors/basics.md)
 
@@ -6,85 +6,37 @@
 
 Understand the three color spaces in CE.SDK and when to use each for screen or print workflows.
 
-![Color Basics example showing three colored blocks representing sRGB, CMYK, and Spot color spaces](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-colors-basics-browser)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-colors-basics-browser)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-colors-basics-browser/)
+>
+> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-colors-basics-server-js)
+>
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-colors-basics-server-js)
 
 CE.SDK supports three color spaces: **sRGB** for screen display, **CMYK** for print workflows, and **Spot Color** for specialized printing. Each color space serves different output types and has its own object format for the `setColor()` API.
 
-```typescript file=@cesdk_web_examples/guides-colors-basics-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');
-    }
+```typescript file=@cesdk_web_examples/guides-colors-basics-server-js/server-js.ts reference-only
+import CreativeEngine from '@cesdk/node';
+import { writeFileSync, mkdirSync, existsSync } from 'fs';
+import { config } from 'dotenv';
 
-    // Enable spot color feature for the UI
-    cesdk.feature.enable('ly.img.spotColor');
-    await cesdk.addPlugin(new DesignEditorConfig());
+// Load environment variables
+config();
 
-    // 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' }
-    });
+async function main() {
+  const engine = await CreativeEngine.init({
+    baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
+    // license: process.env.CESDK_LICENSE
+  });
 
-    const engine = cesdk.engine;
+  try {
+    // Create a scene with a page
+    engine.scene.create('VerticalStack', {
+      page: { size: { width: 800, height: 600 } }
+    });
     const page = engine.block.findByType('page')[0];
 
     const pageWidth = engine.block.getWidth(page);
@@ -95,7 +47,7 @@ class Example implements EditorPlugin {
     const spacing = 30;
     const availableWidth = pageWidth - 2 * margin - 2 * spacing;
     const blockWidth = availableWidth / 3;
-    const blockHeight = pageHeight - 2 * margin - 80; // Leave space for labels
+    const blockHeight = pageHeight - 2 * margin;
 
     // Define a spot color with RGB approximation for screen preview
     engine.editor.setSpotColorRGB('MyBrand Red', 0.95, 0.25, 0.21);
@@ -187,33 +139,6 @@ class Example implements EditorPlugin {
       externalReference: ''
     });
 
-    // Create labels for each color space
-    const labelY = margin + blockHeight + 20;
-    const fontSize = 24;
-
-    const labels = [
-      { text: 'sRGB', x: margin + blockWidth / 2 },
-      { text: 'CMYK', x: margin + blockWidth + spacing + blockWidth / 2 },
-      {
-        text: 'Spot Color',
-        x: margin + 2 * (blockWidth + spacing) + blockWidth / 2
-      }
-    ];
-
-    for (const label of labels) {
-      const textBlock = engine.block.create('//ly.img.ubq/text');
-      engine.block.replaceText(textBlock, label.text);
-      engine.block.setTextFontSize(textBlock, fontSize);
-      engine.block.setWidthMode(textBlock, 'Auto');
-      engine.block.setHeightMode(textBlock, 'Auto');
-      engine.block.appendChild(page, textBlock);
-
-      // Center the label below each block
-      const textWidth = engine.block.getWidth(textBlock);
-      engine.block.setPositionX(textBlock, label.x - textWidth / 2);
-      engine.block.setPositionY(textBlock, labelY);
-    }
-
     // Position all color blocks
     engine.block.setPositionX(srgbBlock, margin);
     engine.block.setPositionY(srgbBlock, margin);
@@ -233,15 +158,39 @@ class Example implements EditorPlugin {
     console.log('CMYK Color:', cmykColor);
     console.log('Spot Color:', spotColor);
 
-    console.log('Color Basics example loaded successfully');
+    // Export the scene to a PNG file
+    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());
+    writeFileSync(`${outputDir}/color-basics.png`, buffer);
+    console.log('Exported to output/color-basics.png');
+
+    console.log('Color Basics example completed successfully');
+  } finally {
+    engine.dispose();
   }
 }
 
-export default Example;
+main().catch(console.error);
 ```
 
 This guide covers how to choose the correct color space, define and apply colors using the unified `setColor()` API, and configure spot colors with screen preview approximations.
 
+## Initialize the Engine
+
+Set up the headless Creative Engine for server-side color operations.
+
+```typescript highlight=highlight-setup
+const engine = await CreativeEngine.init({
+  baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
+  // license: process.env.CESDK_LICENSE
+});
+```
+
 ## Color Spaces Overview
 
 CE.SDK represents colors as objects with different properties depending on the color space. Use `engine.block.setColor()` to apply any color type to supported properties.
@@ -357,33 +306,33 @@ When rendered on screen, the spot color uses its RGB or CMYK approximation. Duri
 Strokes support all three color spaces. Enable the stroke, set its width, then apply a color using the `'stroke/color'` property.
 
 ```typescript highlight=highlight-stroke-color
-// Add strokes to demonstrate stroke color property
-engine.block.setStrokeEnabled(srgbBlock, true);
-engine.block.setStrokeWidth(srgbBlock, 4);
-engine.block.setColor(srgbBlock, 'stroke/color', {
-  r: 0.1,
-  g: 0.2,
-  b: 0.5,
-  a: 1.0
-});
+    // Add strokes to demonstrate stroke color property
+    engine.block.setStrokeEnabled(srgbBlock, true);
+    engine.block.setStrokeWidth(srgbBlock, 4);
+    engine.block.setColor(srgbBlock, 'stroke/color', {
+      r: 0.1,
+      g: 0.2,
+      b: 0.5,
+      a: 1.0
+    });
 
-engine.block.setStrokeEnabled(cmykBlock, true);
-engine.block.setStrokeWidth(cmykBlock, 4);
-engine.block.setColor(cmykBlock, 'stroke/color', {
-  c: 0.0,
-  m: 0.5,
-  y: 0.6,
-  k: 0.2,
-  tint: 1.0
-});
+    engine.block.setStrokeEnabled(cmykBlock, true);
+    engine.block.setStrokeWidth(cmykBlock, 4);
+    engine.block.setColor(cmykBlock, 'stroke/color', {
+      c: 0.0,
+      m: 0.5,
+      y: 0.6,
+      k: 0.2,
+      tint: 1.0
+    });
 
-engine.block.setStrokeEnabled(spotBlock, true);
-engine.block.setStrokeWidth(spotBlock, 4);
-engine.block.setColor(spotBlock, 'stroke/color', {
-  name: 'MyBrand Red',
-  tint: 0.7,
-  externalReference: ''
-});
+    engine.block.setStrokeEnabled(spotBlock, true);
+    engine.block.setStrokeWidth(spotBlock, 4);
+    engine.block.setColor(spotBlock, 'stroke/color', {
+      name: 'MyBrand Red',
+      tint: 0.7,
+      externalReference: ''
+    });
 ```
 
 ## Reading Color Values
@@ -391,38 +340,63 @@ engine.block.setColor(spotBlock, 'stroke/color', {
 Use `engine.block.getColor()` to retrieve the current color value from a property. The returned object's shape indicates the color space (RGBAColor, CMYKColor, or SpotColor).
 
 ```typescript highlight=highlight-get-color
-// Retrieve and log color values to demonstrate getColor()
-const srgbColor = engine.block.getColor(srgbFill, 'fill/color/value');
-const cmykColor = engine.block.getColor(cmykFill, 'fill/color/value');
-const spotColor = engine.block.getColor(spotFill, 'fill/color/value');
-
-console.log('sRGB Color:', srgbColor);
-console.log('CMYK Color:', cmykColor);
-console.log('Spot Color:', spotColor);
+    // Retrieve and log color values to demonstrate getColor()
+    const srgbColor = engine.block.getColor(srgbFill, 'fill/color/value');
+    const cmykColor = engine.block.getColor(cmykFill, 'fill/color/value');
+    const spotColor = engine.block.getColor(spotFill, 'fill/color/value');
+
+    console.log('sRGB Color:', srgbColor);
+    console.log('CMYK Color:', cmykColor);
+    console.log('Spot Color:', spotColor);
+```
+
+## Exporting with Colors
+
+After applying colors, export the scene to a file. The export respects the color space settings.
+
+```typescript highlight=highlight-export
+    // Export the scene to a PNG file
+    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());
+    writeFileSync(`${outputDir}/color-basics.png`, buffer);
+    console.log('Exported to output/color-basics.png');
+```
+
+## Cleanup
+
+Always dispose of the engine when done to release resources.
+
+```typescript highlight=highlight-cleanup
+engine.dispose();
 ```
 
 ## Choosing the Right Color Space
 
-| Color Space    | Use Case                           | Output                       |
-| -------------- | ---------------------------------- | ---------------------------- |
-| **sRGB**       | Web, digital, screen display       | PNG, JPEG, WebP              |
-| **CMYK**       | Print workflows (converts to RGB)  | PDF (converted)              |
+| Color Space | Use Case | Output |
+|-------------|----------|--------|
+| **sRGB** | Web, digital, screen display | PNG, JPEG, WebP |
+| **CMYK** | Print workflows (converts to RGB) | PDF (converted) |
 | **Spot Color** | Specialized printing, brand colors | PDF (Separation Color Space) |
 
 ## API Reference
 
-| Method                                             | Description                                                                                              |
-| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| `engine.block.setColor(id, property, value)`       | Set a color property on a block. Pass an `RGBAColor`, `CMYKColor`, or `SpotColor` object.                |
-| `engine.block.getColor(id, property)`              | Get the current color value from a property. Returns an `RGBAColor`, `CMYKColor`, or `SpotColor` object. |
-| `engine.editor.setSpotColorRGB(name, r, g, b)`     | Define a spot color with an RGB approximation for screen preview. Components range from 0.0 to 1.0.      |
-| `engine.editor.setSpotColorCMYK(name, c, m, y, k)` | Define a spot color with a CMYK approximation for screen preview. Components range from 0.0 to 1.0.      |
+| Method | Description |
+|--------|-------------|
+| `engine.block.setColor(id, property, value)` | Set a color property on a block. Pass an `RGBAColor`, `CMYKColor`, or `SpotColor` object. |
+| `engine.block.getColor(id, property)` | Get the current color value from a property. Returns an `RGBAColor`, `CMYKColor`, or `SpotColor` object. |
+| `engine.editor.setSpotColorRGB(name, r, g, b)` | Define a spot color with an RGB approximation for screen preview. Components range from 0.0 to 1.0. |
+| `engine.editor.setSpotColorCMYK(name, c, m, y, k)` | Define a spot color with a CMYK approximation for screen preview. Components range from 0.0 to 1.0. |
 
-| Type        | Properties                           | Description                                                 |
-| ----------- | ------------------------------------ | ----------------------------------------------------------- |
-| `RGBAColor` | `r`, `g`, `b`, `a` (0.0-1.0)         | sRGB color for screen display. Alpha controls transparency. |
-| `CMYKColor` | `c`, `m`, `y`, `k`, `tint` (0.0-1.0) | CMYK color for print. Tint controls opacity.                |
-| `SpotColor` | `name`, `tint`, `externalReference`  | Named color for specialized printing.                       |
+| Type | Properties | Description |
+|------|------------|-------------|
+| `RGBAColor` | `r`, `g`, `b`, `a` (0.0-1.0) | sRGB color for screen display. Alpha controls transparency. |
+| `CMYKColor` | `c`, `m`, `y`, `k`, `tint` (0.0-1.0) | CMYK color for print. Tint controls opacity. |
+| `SpotColor` | `name`, `tint`, `externalReference` | Named color for specialized printing. |
 
 ## Next Steps
 
@@ -430,11 +404,13 @@ console.log('Spot Color:', spotColor);
 - [CMYK Colors](./colors/for-print/cmyk.md) - Work with CMYK for print workflows
 - [Spot Colors](./colors/for-print/spot.md) - Define and manage spot colors for specialized printing
 
+
+
 ---
 
 ## 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