@imgly/codesign-mcp 0.1.5 → 0.1.7

package/assets/docs/guide/engine-interface.md

@@ -1,32 +1,12 @@
-> 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) > [Engine](./engine-interface.md)
 
 ---
 
-Access CE.SDK's cross-platform C++ engine programmatically for client-side automation, background processing, and custom workflows in the browser.
+Access CE.SDK's cross-platform C++ engine programmatically for server-side automation, batch processing, and high-resolution exports in Node.js.
 
-CE.SDK is built on a layered architecture where a cross-platform C++ core engine powers all creative operations. The Editor UI and your programmatic code access identical capabilities through the same underlying engine.
-
-## Web SDK Packages
-
-CE.SDK offers three npm packages:
-
-**@cesdk/cesdk-js**: Full package with Editor UI and Engine. Initialize with `CreativeEditorSDK.create()` and access the Engine via `cesdk.engine`. Use this when users edit designs visually while your code handles background tasks.
-
-```javascript
-import CreativeEditorSDK from '@cesdk/cesdk-js';
-
-const cesdk = await CreativeEditorSDK.create('#container', {
-  // license: 'YOUR_CESDK_LICENSE_KEY',
-});
-
-const engine = cesdk.engine;
-```
-
-**@cesdk/engine**: Engine-only package without UI. Smaller bundle size. Initialize with `CreativeEngine.init()`. Use for browser automation, custom UIs, or hidden Engine instances.
-
-**@cesdk/node**: Node.js package for server-side processing. Same API, compiled for Node.js runtime.
+The `@cesdk/node` package provides the same Engine API compiled for Node.js. The API is identical to `@cesdk/engine` in the browser, so you can share code between client and server.
 
 ## Engine API Namespaces
 
@@ -39,70 +19,79 @@ The Engine organizes its functionality into six namespaces:
 - **engine.variable**: Define and update template variables for data merge
 - **engine.event**: Subscribe to engine events (selection changes, state updates)
 
-## Combining UI and Engine Access
-
-The Editor UI calls Engine APIs internally. When you use `cesdk.engine`, you're accessing the same APIs. Most applications combine both: users interact with the visual editor while your code automates background tasks.
-
-Common patterns:
-
-- **Template loading**: Load scenes when users select templates
-- **Validation**: Check for empty placeholders before export
-- **Auto-save**: Serialize scenes with `engine.scene.saveToString()`
-- **Thumbnails**: Generate previews with `engine.block.export()`
-
-## Hidden Engine Instances
-
-Run a second, invisible Engine alongside your main UI for background processing:
+## Basic Usage
 
 ```javascript
-import CreativeEngine from '@cesdk/engine';
-
-// Main editor with UI
-const cesdk = await CreativeEditorSDK.create('#container', config);
+const { CreativeEngine } = require('@cesdk/node');
 
-// Hidden engine for background work
-const backgroundEngine = await CreativeEngine.init({
-  // license: 'YOUR_CESDK_LICENSE_KEY',
+const engine = await CreativeEngine.init({
+  license: process.env.CESDK_LICENSE,
 });
 
-async function generateThumbnail(sceneData) {
-  await backgroundEngine.scene.loadFromString(sceneData);
-  const page = backgroundEngine.scene.getPages()[0];
-  return await backgroundEngine.block.export(page, 'image/jpeg', {
-    targetWidth: 200,
-    targetHeight: 200
+try {
+  await engine.scene.loadFromURL('https://example.com/template.scene');
+  const page = engine.scene.getPages()[0];
+  const blob = await engine.block.export(page, 'image/png', {
+    targetWidth: 3840,
+    targetHeight: 2160,
+    dpi: 300,
   });
+  // Save blob to file or storage
+} finally {
+  engine.dispose();
 }
 ```
 
-## Memory Management
+## Server-Side Benefits
+
+**Resources**: Access more CPU, memory, and storage than client devices for print-quality exports.
+
+**Secure Assets**: Process private templates and assets without exposing them to clients.
+
+**Background Operations**: Handle long-running tasks without blocking users.
 
-Each Engine instance consumes memory. Dispose instances when done:
+## Hybrid Workflows
+
+Users design on the client with instant feedback. Send the scene to your server for high-resolution export:
 
 ```javascript
-backgroundEngine.dispose();
+// Client: Save scene and send to server
+const sceneData = await cesdk.engine.scene.saveToString();
+
+// Server: Load and export at high resolution
+const engine = await CreativeEngine.init({ license: process.env.CESDK_LICENSE });
+try {
+  await engine.scene.loadFromString(sceneData);
+  const blob = await engine.block.export(engine.scene.getPages()[0], 'image/png', {
+    targetWidth: 3840,
+    targetHeight: 2160,
+    dpi: 300,
+  });
+} finally {
+  engine.dispose();
+}
 ```
 
-For resource-intensive tasks like high-resolution exports, consider server-side processing with `@cesdk/node`.
-
 ## Troubleshooting
 
-**Engine not initialized**: Ensure `CreativeEditorSDK.create()` or `CreativeEngine.init()` completes before accessing `engine`.
+**Engine not initialized**: Ensure `CreativeEngine.init()` completes before calling other methods.
 
-**Hidden instance blocking UI**: Heavy operations can impact browser performance. Move resource-intensive tasks to server-side.
+**Memory issues**: Dispose Engine instances after each use with `engine.dispose()`.
 
-**Memory issues**: Dispose unused instances with `engine.dispose()`.
+**License errors**: Verify `CESDK_LICENSE` environment variable is set correctly.
 
 ## Next Steps
 
-- [Node.js SDK](./what-is-cesdk.md) for server-side processing
 - [Automation Overview](./automation/overview.md) for workflow examples
+- [Data Merge](./automation/data-merge.md) for template personalization
+
+
 
 ---
 
 ## 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

package/assets/docs/guide/export-save-publish/create-thumbnail.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) > [Export Media Assets](./export-save-publish/export.md) > [Create Thumbnail](./export-save-publish/create-thumbnail.md)
 
@@ -6,189 +6,135 @@
 
 Generate thumbnail preview images from CE.SDK scenes by exporting with target dimensions for galleries and design management.
 
-![Create Thumbnail hero image](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
-
 > **Reading time:** 5 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-export-save-publish-create-thumbnail-browser)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-export-save-publish-create-thumbnail-browser)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-export-save-publish-create-thumbnail-browser/)
+>
+> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-export-save-publish-create-thumbnail-server-js)
+>
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-export-save-publish-create-thumbnail-server-js)
 
 Thumbnails provide visual previews of designs without loading the full editor. Use `engine.block.export()` with `targetWidth` and `targetHeight` options to scale content while maintaining aspect ratio. Supported formats include PNG, JPEG, and WebP.
 
-```typescript file=@cesdk_web_examples/guides-export-save-publish-create-thumbnail-browser/browser.ts reference-only
-import type CreativeEditorSDK from '@cesdk/cesdk-js';
-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.*'
-        ]
-      })
+```typescript file=@cesdk_web_examples/guides-export-save-publish-create-thumbnail-server-js/server-js.ts reference-only
+import CreativeEngine from '@cesdk/node';
+import { config } from 'dotenv';
+import { writeFileSync, mkdirSync, existsSync } from 'fs';
+import { createInterface } from 'readline';
+
+config();
+
+// Helper function to prompt for user input
+function prompt(question: string): Promise<string> {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer);
+    });
+  });
+}
+
+// Display thumbnail options menu
+console.log('=== Thumbnail Generation Options ===\n');
+console.log('1. Small thumbnail (150×150 JPEG)');
+console.log('2. Medium thumbnail (400×300 JPEG)');
+console.log('3. PNG thumbnail (400×300)');
+console.log('4. WebP thumbnail (400×300)');
+console.log('5. All formats\n');
+
+const choice = (await prompt('Select thumbnail option (1-5): ')) || '5';
+
+console.log('\n⏳ Initializing engine...');
+
+const engine = await CreativeEngine.init({
+  baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
+});
+
+try {
+  await engine.scene.loadFromURL(
+    'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_postcard_1.scene'
+  );
+
+  const page = engine.block.findByType('page')[0];
+  if (!page) throw new Error('No page found');
+
+  const outputDir = './output';
+  if (!existsSync(outputDir)) {
+    mkdirSync(outputDir, { recursive: true });
+  }
+
+  console.log('⏳ Generating thumbnails...\n');
+
+  if (choice === '1' || choice === '5') {
+    const blob = await engine.block.export(page, {
+      mimeType: 'image/jpeg',
+      targetWidth: 150,
+      targetHeight: 150,
+      jpegQuality: 0.8
+    });
+    const buffer = Buffer.from(await blob.arrayBuffer());
+    writeFileSync(`${outputDir}/thumbnail-small.jpg`, buffer);
+    console.log(
+      `✓ Small thumbnail: ${outputDir}/thumbnail-small.jpg (${(blob.size / 1024).toFixed(1)} KB)`
     );
-    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());
-
-    const engine = cesdk.engine;
-
-    await engine.scene.loadFromURL(
-      'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_postcard_1.scene'
+  }
+
+  if (choice === '2' || choice === '5') {
+    const blob = await engine.block.export(page, {
+      mimeType: 'image/jpeg',
+      targetWidth: 400,
+      targetHeight: 300,
+      jpegQuality: 0.85
+    });
+    const buffer = Buffer.from(await blob.arrayBuffer());
+    writeFileSync(`${outputDir}/thumbnail-medium.jpg`, buffer);
+    console.log(
+      `✓ Medium thumbnail: ${outputDir}/thumbnail-medium.jpg (${(blob.size / 1024).toFixed(1)} KB)`
     );
-    const page = engine.scene.getCurrentPage();
-    if (!page) throw new Error('No page found');
-    await engine.scene.zoomToBlock(page, { padding: 40 });
+  }
 
-    // Setup thumbnail export functionality
-    await this.setupThumbnailActions(cesdk, page);
+  if (choice === '3' || choice === '5') {
+    const blob = await engine.block.export(page, {
+      mimeType: 'image/png',
+      targetWidth: 400,
+      targetHeight: 300,
+      pngCompressionLevel: 6
+    });
+    const buffer = Buffer.from(await blob.arrayBuffer());
+    writeFileSync(`${outputDir}/thumbnail.png`, buffer);
+    console.log(
+      `✓ PNG thumbnail: ${outputDir}/thumbnail.png (${(blob.size / 1024).toFixed(1)} KB)`
+    );
   }
 
-  private async setupThumbnailActions(
-    cesdk: CreativeEditorSDK,
-    page: number
-  ): Promise<void> {
-    const engine = cesdk.engine;
-
-    // Add thumbnail export buttons to navigation bar
-    cesdk.ui.insertOrderComponent(
-      { in: 'ly.img.navigation.bar', position: 'end' },
-      {
-        id: 'ly.img.actions.navigationBar',
-        children: [
-          {
-            id: 'ly.img.action.navigationBar',
-            key: 'export-thumbnail-small',
-            label: 'Small Thumbnail',
-            icon: '@imgly/Save',
-            onClick: async () => {
-              const blob = await engine.block.export(page, {
-                mimeType: 'image/jpeg',
-                targetWidth: 150,
-                targetHeight: 150,
-                jpegQuality: 0.8
-              });
-
-              await cesdk.utils.downloadFile(blob, 'image/jpeg');
-              console.log(
-                `✓ Small thumbnail: ${(blob.size / 1024).toFixed(1)} KB`
-              );
-            }
-          },
-          {
-            id: 'ly.img.action.navigationBar',
-            key: 'export-thumbnail-medium',
-            label: 'Medium Thumbnail',
-            icon: '@imgly/Save',
-            onClick: async () => {
-              const blob = await engine.block.export(page, {
-                mimeType: 'image/jpeg',
-                targetWidth: 400,
-                targetHeight: 300,
-                jpegQuality: 0.85
-              });
-
-              await cesdk.utils.downloadFile(blob, 'image/jpeg');
-              console.log(
-                `✓ Medium thumbnail: ${(blob.size / 1024).toFixed(1)} KB`
-              );
-            }
-          },
-          {
-            id: 'ly.img.action.navigationBar',
-            key: 'export-thumbnail-png',
-            label: 'PNG Thumbnail',
-            icon: '@imgly/Save',
-            onClick: async () => {
-              const blob = await engine.block.export(page, {
-                mimeType: 'image/png',
-                targetWidth: 400,
-                targetHeight: 300,
-                pngCompressionLevel: 6
-              });
-
-              await cesdk.utils.downloadFile(blob, 'image/png');
-              console.log(
-                `✓ PNG thumbnail: ${(blob.size / 1024).toFixed(1)} KB`
-              );
-            }
-          },
-          {
-            id: 'ly.img.action.navigationBar',
-            key: 'export-thumbnail-webp',
-            label: 'WebP Thumbnail',
-            icon: '@imgly/Save',
-            onClick: async () => {
-              const blob = await engine.block.export(page, {
-                mimeType: 'image/webp',
-                targetWidth: 400,
-                targetHeight: 300,
-                webpQuality: 0.8
-              });
-
-              await cesdk.utils.downloadFile(blob, 'image/webp');
-              console.log(
-                `✓ WebP thumbnail: ${(blob.size / 1024).toFixed(1)} KB`
-              );
-            }
-          }
-        ]
-      }
+  if (choice === '4' || choice === '5') {
+    const blob = await engine.block.export(page, {
+      mimeType: 'image/webp',
+      targetWidth: 400,
+      targetHeight: 300,
+      webpQuality: 0.8
+    });
+    const buffer = Buffer.from(await blob.arrayBuffer());
+    writeFileSync(`${outputDir}/thumbnail.webp`, buffer);
+    console.log(
+      `✓ WebP thumbnail: ${outputDir}/thumbnail.webp (${(blob.size / 1024).toFixed(1)} KB)`
     );
   }
-}
 
-export default Example;
+  console.log('\n✓ Thumbnail generation completed');
+} finally {
+  engine.dispose();
+}
 ```
 
-This guide covers exporting thumbnails at specific dimensions, choosing formats, optimizing quality and file size, and generating multiple thumbnail sizes.
+This guide covers exporting thumbnails at specific dimensions, choosing formats, optimizing quality and file size, and saving thumbnails to the file system.
 
 ## Export a Thumbnail
 
@@ -256,37 +202,55 @@ const blob = await engine.block.export(page, {
 
 Standard sizes for different use cases:
 
-| Size   | Dimensions | Use Case                      |
-| ------ | ---------- | ----------------------------- |
-| Small  | 150×150    | Grid galleries, file browsers |
-| Medium | 400×300    | Preview panels, cards         |
-| Large  | 800×600    | Full previews, detail views   |
+| Size | Dimensions | Use Case |
+| ---- | ---------- | -------- |
+| Small | 150×150 | Grid galleries, file browsers |
+| Medium | 400×300 | Preview panels, cards |
+| Large | 800×600 | Full previews, detail views |
+
+## Save to File System
+
+After exporting, convert the Blob to a Buffer and write to the file system. Create the output directory if it doesn't exist.
+
+```typescript
+const blob = await engine.block.export(page, {
+  mimeType: 'image/jpeg',
+  targetWidth: 400,
+  targetHeight: 300,
+  jpegQuality: 0.8
+});
+
+const buffer = Buffer.from(await blob.arrayBuffer());
+writeFileSync('output/thumbnail.jpg', buffer);
+```
 
 ## Optimize Thumbnail Quality
 
 Balance quality with file size using format-specific options:
 
-| Format | Option                | Range | Default | Notes                                     |
-| ------ | --------------------- | ----- | ------- | ----------------------------------------- |
-| JPEG   | `jpegQuality`         | 0-1   | 0.9     | Lower = smaller files, visible artifacts  |
-| PNG    | `pngCompressionLevel` | 0-9   | 5       | Higher = smaller files, slower encoding   |
-| WebP   | `webpQuality`         | 0-1   | 1.0     | 1.0 = lossless, lower = lossy compression |
+| Format | Option | Range | Default | Notes |
+| ------ | ------ | ----- | ------- | ----- |
+| JPEG | `jpegQuality` | 0-1 | 0.9 | Lower = smaller files, visible artifacts |
+| PNG | `pngCompressionLevel` | 0-9 | 5 | Higher = smaller files, slower encoding |
+| WebP | `webpQuality` | 0-1 | 1.0 | 1.0 = lossless, lower = lossy compression |
 
 For thumbnails, JPEG quality of 0.8 or WebP quality of 0.75-0.85 typically provides good results with small file sizes.
 
 ## API Reference
 
-| Method                                     | Description                                               |
-| ------------------------------------------ | --------------------------------------------------------- |
-| `engine.block.export(blockId, options)`    | Export a block as image with format and dimension options |
-| `engine.scene.getCurrentPage()`            | Get the current page block ID                             |
-| `cesdk.utils.downloadFile(blob, mimeType)` | Download a blob to the user's device                      |
+| Method | Description |
+| ------ | ----------- |
+| `engine.block.export(blockId, options)` | Export a block as image with format and dimension options |
+| `engine.block.findByType('page')` | Find all pages in the current scene |
+| `engine.dispose()` | Clean up engine resources when done |
+
+
 
 ---
 
 ## 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