@imgly/codesign-mcp 0.1.5 → 0.1.7

package/assets/docs/guide/colors/create-color-palette.md

@@ -1,234 +1,194 @@
-> 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) > [Create a Color Palette](./colors/create-color-palette.md)
 
 ---
 
-Build custom color palettes that appear in the CE.SDK color picker using sRGB, CMYK, and Spot colors.
-
-![Create a Color Palette example showing custom color library in the color picker](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
+Build custom color palettes programmatically using CE.SDK's asset system with
+support for sRGB, 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-create-color-palette-browser)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-colors-create-color-palette-browser)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-colors-create-color-palette-browser/)
+>
+> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-colors-create-color-palette-server-js)
+>
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-colors-create-color-palette-server-js)
 
-Color libraries in CE.SDK are implemented as asset sources containing individual colors as assets. Each library has a unique source ID and can include sRGB colors for screen display, CMYK colors for print workflows, and Spot colors for specialized printing applications. You configure which libraries appear in the color picker through the `'ly.img.colors'` asset library entry.
+Color libraries in CE.SDK are implemented as local asset sources containing individual colors as assets. Each library has a unique source ID and can include sRGB colors for screen display, CMYK colors for print workflows, and Spot colors for specialized printing applications. You can create, populate, query, and manage these libraries programmatically using the engine's asset API.
 
-```typescript file=@cesdk_web_examples/guides-colors-create-color-palette-browser/browser.ts reference-only
-import type {
+```typescript file=@cesdk_web_examples/guides-colors-create-color-palette-server-js/server-js.ts reference-only
+import CreativeEngine, {
   AssetDefinition,
-  EditorPlugin,
-  EditorPluginContext
-} from '@cesdk/cesdk-js';
-import packageJson from './package.json';
-
-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';
-
-// Define color assets for each color space type
-const colors: AssetDefinition[] = [
-  {
-    id: 'brand-blue',
-    label: { en: 'Brand Blue' },
-    tags: { en: ['brand', 'blue', 'primary'] },
-    payload: {
-      color: {
-        colorSpace: 'sRGB',
-        r: 0.2,
-        g: 0.4,
-        b: 0.8
-      }
-    }
-  },
-  {
-    id: 'brand-coral',
-    label: { en: 'Brand Coral' },
-    tags: { en: ['brand', 'coral', 'secondary'] },
-    payload: {
-      color: {
-        colorSpace: 'sRGB',
-        r: 0.95,
-        g: 0.45,
-        b: 0.4
-      }
-    }
-  },
-  {
-    id: 'print-magenta',
-    label: { en: 'Print Magenta' },
-    tags: { en: ['print', 'magenta', 'cmyk'] },
-    payload: {
-      color: {
-        colorSpace: 'CMYK',
-        c: 0,
-        m: 0.9,
-        y: 0.2,
-        k: 0
-      }
-    }
-  },
-  {
-    id: 'metallic-gold',
-    label: { en: 'Metallic Gold' },
-    tags: { en: ['spot', 'metallic', 'gold'] },
-    payload: {
-      color: {
-        colorSpace: 'SpotColor',
-        name: 'Metallic Gold Ink',
-        externalReference: 'Custom Inks',
-        representation: {
-          colorSpace: 'sRGB',
-          r: 0.85,
-          g: 0.65,
-          b: 0.13
+  AssetRGBColor,
+  AssetCMYKColor,
+  AssetSpotColor
+} from '@cesdk/node';
+import * as fs from 'fs';
+
+async function main() {
+  let engine;
+  try {
+    engine = await CreativeEngine.init({
+      baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
+      // license: 'YOUR_CESDK_LICENSE_KEY'
+    });
+    // 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);
+
+    // Define color assets for each color space type
+    const colors: AssetDefinition[] = [
+      {
+        id: 'brand-blue',
+        label: { en: 'Brand Blue' },
+        tags: { en: ['brand', 'blue', 'primary'] },
+        payload: {
+          color: {
+            colorSpace: 'sRGB',
+            r: 0.2,
+            g: 0.4,
+            b: 0.8
+          } as AssetRGBColor
+        }
+      },
+      {
+        id: 'brand-coral',
+        label: { en: 'Brand Coral' },
+        tags: { en: ['brand', 'coral', 'secondary'] },
+        payload: {
+          color: {
+            colorSpace: 'sRGB',
+            r: 0.95,
+            g: 0.45,
+            b: 0.4
+          } as AssetRGBColor
+        }
+      },
+      {
+        id: 'print-magenta',
+        label: { en: 'Print Magenta' },
+        tags: { en: ['print', 'magenta', 'cmyk'] },
+        payload: {
+          color: {
+            colorSpace: 'CMYK',
+            c: 0,
+            m: 0.9,
+            y: 0.2,
+            k: 0
+          } as AssetCMYKColor
+        }
+      },
+      {
+        id: 'metallic-gold',
+        label: { en: 'Metallic Gold' },
+        tags: { en: ['spot', 'metallic', 'gold'] },
+        payload: {
+          color: {
+            colorSpace: 'SpotColor',
+            name: 'Metallic Gold Ink',
+            externalReference: 'Custom Inks',
+            representation: {
+              colorSpace: 'sRGB',
+              r: 0.85,
+              g: 0.65,
+              b: 0.13
+            }
+          } as AssetSpotColor
         }
       }
-    }
-  }
-];
+    ];
 
-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;
-
-    // Create a local asset source and add each color
-    const sourceId = 'my-brand-colors';
-    engine.asset.addLocalSource(sourceId);
+    // Create a local asset source for the color library
+    engine.asset.addLocalSource('my-brand-colors');
 
+    // Add all color assets to the source
     for (const color of colors) {
-      await engine.asset.addAssetToSource(sourceId, color);
+      engine.asset.addAssetToSource('my-brand-colors', color);
     }
 
-    // Set labels for the color library using i18n
-    cesdk.i18n.setTranslations({
-      en: {
-        'libraries.my-brand-colors.label': 'Brand Colors'
-      }
-    });
-
-    // Configure the color picker to show custom colors first, then defaults
-    cesdk.ui.updateAssetLibraryEntry('ly.img.color.palette', {
-      sourceIds: ['my-brand-colors', 'ly.img.color.palette']
+    // Query colors from the library
+    const queryResult = await engine.asset.findAssets('my-brand-colors', {
+      page: 0,
+      perPage: 100
     });
+    console.log('Colors in library:', queryResult.assets.length);
+    for (const asset of queryResult.assets) {
+      console.log(`  - ${asset.id}: ${asset.label ?? 'No label'}`);
+    }
 
-    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());
-
-    // Configure the color picker to show custom colors alongside the defaults
-    cesdk.ui.updateAssetLibraryEntry('ly.img.colors', {
-      sourceIds: ['my-brand-colors', 'ly.img.color.palette']
-    });
+    // Remove a color from the library
+    engine.asset.removeAssetFromSource('my-brand-colors', 'brand-coral');
+    console.log('Removed brand-coral from library');
 
-    await cesdk.actions.run('scene.create', {
-      page: { width: 800, height: 600, unit: 'Pixel' }
+    // Verify removal
+    const updatedResult = await engine.asset.findAssets('my-brand-colors', {
+      page: 0,
+      perPage: 100
     });
+    console.log('Colors after removal:', updatedResult.assets.length);
 
-    // Set up the page with dimensions
-    const page = engine.block.findByType('page')[0];
-
-    // Apply a soft cream background to the page fill
-    // This complements the Brand Blue rectangle
-    const pageFill = engine.block.getFill(page);
-    engine.block.setColor(pageFill, 'fill/color/value', {
-      r: 0.98,
-      g: 0.96,
-      b: 0.92,
-      a: 1.0
-    });
+    // Create a graphic block and apply a color from the palette
+    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, 300);
+    engine.block.setPositionY(block, 225);
+    engine.block.appendChild(page, block);
 
-    // Create a graphic block with Brand Blue from the custom palette
-    const block = engine.block.create('//ly.img.ubq/graphic');
-    engine.block.setShape(
-      block,
-      engine.block.createShape('//ly.img.ubq/shape/rect')
-    );
-    const fill = engine.block.createFill('//ly.img.ubq/fill/color');
-    // Use Brand Blue from our custom palette
+    // Apply Brand Blue from our palette
+    const fill = engine.block.getFill(block);
     engine.block.setColor(fill, 'fill/color/value', {
       r: 0.2,
       g: 0.4,
       b: 0.8,
       a: 1.0
     });
-    engine.block.setFill(block, fill);
-    engine.block.setWidth(block, 200);
-    engine.block.setHeight(block, 200);
 
-    // Center the block on the page
-    const pageWidth = engine.block.getWidth(page);
-    const pageHeight = engine.block.getHeight(page);
-    engine.block.setPositionX(block, (pageWidth - 200) / 2);
-    engine.block.setPositionY(block, (pageHeight - 200) / 2);
-    engine.block.appendChild(page, block);
-
-    // Select the block and open the fill inspector to show the color picker
-    engine.block.select(block);
-    cesdk.ui.openPanel('//ly.img.panel/inspector/fill');
-
-    console.log('Create Color Palette example loaded successfully');
+    // Export the scene
+    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 {
+    if (engine) {
+      engine.dispose();
+    }
   }
 }
 
-export default Example;
+main().catch(console.error);
 ```
 
-This guide covers how to define colors in different color spaces, create and configure color libraries, set custom labels, and control the display order in the color picker.
+This guide covers how to define colors in different color spaces, create and configure color libraries, query colors from libraries, and remove colors when needed.
+
+## Initialize the Engine
+
+We start by initializing the headless Creative Engine with a scene and page for demonstrating our color library workflow.
+
+```typescript highlight=highlight-setup
+engine = await CreativeEngine.init({
+  baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
+  // license: 'YOUR_CESDK_LICENSE_KEY'
+});
+// 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);
+```
 
 ## Defining Color Assets
 
-Colors are added to libraries as `AssetDefinition` objects. Each color asset has an `id`, optional `label` and `tags` for display and search, and a `payload.color` property containing the color data. The color type determines which color space is used.
+Colors are added to libraries as `AssetDefinition` objects. Each color asset has an `id`, optional `label` and `tags` for organization, and a `payload.color` property containing the color data. The color type determines which color space is used.
 
 ### sRGB Colors
 
@@ -247,7 +207,7 @@ const colors: AssetDefinition[] = [
         r: 0.2,
         g: 0.4,
         b: 0.8
-      }
+      } as AssetRGBColor
     }
   },
   {
@@ -260,7 +220,7 @@ const colors: AssetDefinition[] = [
         r: 0.95,
         g: 0.45,
         b: 0.4
-      }
+      } as AssetRGBColor
     }
   },
   {
@@ -274,7 +234,7 @@ const colors: AssetDefinition[] = [
         m: 0.9,
         y: 0.2,
         k: 0
-      }
+      } as AssetCMYKColor
     }
   },
   {
@@ -292,7 +252,7 @@ const colors: AssetDefinition[] = [
           g: 0.65,
           b: 0.13
         }
-      }
+      } as AssetSpotColor
     }
   }
 ];
@@ -317,87 +277,125 @@ The "Metallic Gold" color demonstrates the spot color format, using a custom ink
 We create a local asset source using `engine.asset.addLocalSource()` with a unique source ID. Then we add each color asset using `engine.asset.addAssetToSource()`.
 
 ```typescript highlight=highlight-add-library
-// Create a local asset source and add each color
-const sourceId = 'my-brand-colors';
-engine.asset.addLocalSource(sourceId);
+    // Create a local asset source for the color library
+    engine.asset.addLocalSource('my-brand-colors');
 
-for (const color of colors) {
-  await engine.asset.addAssetToSource(sourceId, color);
-}
+    // Add all color assets to the source
+    for (const color of colors) {
+      engine.asset.addAssetToSource('my-brand-colors', color);
+    }
 ```
 
 The source ID `'my-brand-colors'` identifies this library throughout the application. You can create multiple libraries with different source IDs to organize colors by purpose—for example, separate libraries for brand colors, print colors, and seasonal palettes.
 
-## Configuring Library Labels
+## Querying Colors from a Library
 
-We set display labels for color libraries using `cesdk.i18n.setTranslations()`. Labels use the pattern `libraries.<source-id>.label` where `<source-id>` matches the ID used when creating the source.
+Use `engine.asset.findAssets()` to retrieve colors from a library. This is useful for batch processing workflows, validating library contents, or building custom color selection interfaces.
 
-```typescript highlight=highlight-config-labels
-// Set labels for the color library using i18n
-cesdk.i18n.setTranslations({
-  en: {
-    'libraries.my-brand-colors.label': 'Brand Colors'
-  }
+```typescript highlight=highlight-query-colors
+// Query colors from the library
+const queryResult = await engine.asset.findAssets('my-brand-colors', {
+  page: 0,
+  perPage: 100
 });
+console.log('Colors in library:', queryResult.assets.length);
+for (const asset of queryResult.assets) {
+  console.log(`  - ${asset.id}: ${asset.label ?? 'No label'}`);
+}
 ```
 
-The label "Brand Colors" appears as the section header in the color picker. You can provide translations for multiple locales by adding additional language keys to the translations object.
+The query returns an `AssetsQueryResult` containing the matching assets. You can filter by tags, search terms, or pagination parameters to find specific colors.
 
-## Configuring the Color Picker
+## Removing Colors from a Library
 
-We control which libraries appear in the color picker and their display order using `cesdk.ui.updateAssetLibraryEntry()`. The `sourceIds` array determines both visibility and order—libraries appear in the picker in the same order as the array.
+Remove individual colors from a library using `engine.asset.removeAssetFromSource()` with the source ID and the color's asset ID.
 
-```typescript highlight=highlight-config-order
-// Configure the color picker to show custom colors first, then defaults
-cesdk.ui.updateAssetLibraryEntry('ly.img.color.palette', {
-  sourceIds: ['my-brand-colors', 'ly.img.color.palette']
-});
+```typescript highlight=highlight-remove-color
+// Remove a color from the library
+engine.asset.removeAssetFromSource('my-brand-colors', 'brand-coral');
 ```
 
-The special source ID `'ly.img.color.palette'` represents CE.SDK's built-in default color palette. Include it in the array to show the default colors alongside your custom library. Remove it from the array to hide the default palette entirely.
+This removes the color from the library immediately. Query the library again to verify the removal.
 
-## Removing Colors
+## Applying Colors from the Palette
 
-You can remove individual colors from a library using `engine.asset.removeAssetFromSource()` with the source ID and the color's asset ID.
+After creating a color library, you can apply colors to design elements. While the library stores color definitions as assets, you apply them to blocks using the standard color API.
 
-```typescript
-engine.asset.removeAssetFromSource('my-brand-colors', 'brand-blue');
+```typescript highlight=highlight-apply-color
+    // Create a graphic block and apply a color from the palette
+    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, 300);
+    engine.block.setPositionY(block, 225);
+    engine.block.appendChild(page, block);
+
+    // Apply Brand Blue from our palette
+    const fill = engine.block.getFill(block);
+    engine.block.setColor(fill, 'fill/color/value', {
+      r: 0.2,
+      g: 0.4,
+      b: 0.8,
+      a: 1.0
+    });
+```
+
+The library serves as a centralized source of truth for color values. In production workflows, you would query the library to get the exact color values before applying them to blocks.
+
+## Export and Cleanup
+
+After working with colors, we export the result and dispose of the engine to free resources.
+
+```typescript highlight=highlight-export
+  // Export the scene
+  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 {
+  if (engine) {
+    engine.dispose();
+  }
+}
 ```
 
-This removes the color from the library immediately. The color picker updates to reflect the change the next time it renders.
+Always dispose of the engine in a finally block to ensure resources are freed even if an error occurs.
 
 ## Troubleshooting
 
-### Colors Not Appearing in Picker
+### Colors Not Added to Library
 
-If your colors don't appear in the color picker:
+If colors aren't appearing in your library:
 
-- Verify the source ID is included in the `sourceIds` array passed to `updateAssetLibraryEntry()`
-- Check that colors were added using `addAssetToSource()` with the correct source ID
-- Ensure the asset source was created with `addLocalSource()` before adding colors
+- Verify the source ID passed to `addAssetToSource()` matches the ID used in `addLocalSource()`
+- Ensure `addLocalSource()` was called before adding colors
+- Check that each color asset has a unique `id` property
 
-### Label Not Showing
+### Query Returns Empty Results
 
-If the library label doesn't appear:
+If `findAssets()` returns no results:
 
-- Verify the translation key follows the `libraries.<source-id>.label` pattern exactly
-- Check that the source ID in the translation key matches the source ID used in `addLocalSource()`
-- Ensure `setTranslations()` was called before the color picker renders
+- Verify the source ID matches exactly (case-sensitive)
+- Check pagination parameters—`page` starts at 0
+- Ensure colors were added successfully before querying
 
-### Spot Color Appears Incorrect
+### Spot Color Representation Not Displaying
 
-If a spot color displays incorrectly:
+If a spot color appears incorrectly:
 
-- Check that the `representation` property contains a valid sRGB or CMYK color for screen preview
-- Verify the `name` property is defined and not empty
-- Ensure the `colorSpace` is set to `'SpotColor'`
+- Verify the `representation` property contains a valid sRGB or CMYK color
+- Check that `colorSpace` is set to `'SpotColor'`
+- Ensure the representation color values are in the 0.0-1.0 range
 
-### Wrong Library Order
+### Color Not Removed
 
-The order of libraries in the color picker matches the order in the `sourceIds` array. To change the order:
+If `removeAssetFromSource()` doesn't seem to work:
 
-- Reorder the source IDs in the array passed to `updateAssetLibraryEntry()`
-- The first source ID appears at the top of the color picker
+- Verify the asset ID matches the `id` property of the color exactly
+- Check that the source ID is correct
+- Query the library after removal to confirm the change
 
 ## API Reference
 
@@ -406,8 +404,7 @@ The order of libraries in the color picker matches the order in the `sourceIds`
 | `engine.asset.addLocalSource(sourceId)`                 | Create a local asset source for colors |
 | `engine.asset.addAssetToSource(sourceId, asset)`        | Add a color asset to a source          |
 | `engine.asset.removeAssetFromSource(sourceId, assetId)` | Remove a color asset from a source     |
-| `cesdk.ui.updateAssetLibraryEntry(entryId, config)`     | Configure color library display order  |
-| `cesdk.i18n.setTranslations(translations)`              | Set labels for color libraries         |
+| `engine.asset.findAssets(sourceId, query)`              | Query colors from a source             |
 
 | Type              | Properties                                                  | Description                               |
 | ----------------- | ----------------------------------------------------------- | ----------------------------------------- |
@@ -416,11 +413,13 @@ The order of libraries in the color picker matches the order in the `sourceIds`
 | `AssetSpotColor`  | `colorSpace`, `name`, `externalReference`, `representation` | Named spot color for specialized printing |
 | `AssetDefinition` | `id`, `label`, `tags`, `payload`                            | Color asset structure with metadata       |
 
+
+
 ---
 
 ## 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