@imgly/codesign-mcp 0.1.5 → 0.1.6

package/assets/docs/guide/conversion/overview.md

@@ -1,9 +1,15 @@
-> 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) > [Conversion](./conversion.md) > [Overview](./conversion/overview.md)
 
 ---
 
+CreativeEditor SDK (CE.SDK) allows you to export designs into a variety of formats, making it easy to prepare assets for web publishing, printing, storage, and other workflows.
+
+[Launch Web Demo](https://img.ly/showcases/cesdk)
+
+[Get Started](./get-started/overview.md)
+
 ## Supported Input and Output Formats
 
 CE.SDK accepts a range of input formats when working with designs, including:
@@ -12,11 +18,34 @@ When it comes to exporting or converting designs, the SDK supports the following
 
 Each format serves different use cases, giving you the flexibility to adapt designs for your application’s needs.
 
+## Customization Options
+
+When exporting designs, CE.SDK offers several customization options to meet specific output requirements:
+
+- **Resolution and DPI Settings:**\
+  Adjust the resolution for raster exports like PNG to optimize for screen or print.
+
+- **Output Dimensions:**\
+  Define custom width and height settings for the exported file, independent of the original design size.
+
+- **File Quality:**\
+  For formats that support compression (such as PNG or PDF), you can control the quality level to balance file size and visual fidelity.
+
+- **Background Transparency:**\
+  Choose whether to preserve transparent backgrounds or export with a solid background color.
+
+- **Page Selection:**\
+  When exporting multi-page documents (e.g., PDFs), you can select specific pages or export all pages at once.
+
+These options help ensure that your exported content is optimized for its intended platform, whether it's a website, a mobile app, or a print-ready document.
+
+
+
 ---
 
 ## 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/conversion/to-base64.md

@@ -1,200 +1,159 @@
-> 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) > [Conversion](./conversion.md) > [To Base64](./conversion/to-base64.md)
 
 ---
 
-Convert CE.SDK exports to Base64-encoded strings for embedding in HTML, storing in databases, or transmitting via JSON APIs.
-
-![To Base64](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
+Convert CE.SDK exports to Base64-encoded strings for storing in databases, transmitting via APIs, or embedding in HTML templates.
 
 > **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-conversion-to-base64-browser)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-conversion-to-base64-browser)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-conversion-to-base64-browser/)
-
-Base64 encoding transforms binary image data into ASCII text, enabling you to embed images directly in HTML, store them in text-only databases, or transmit them through JSON APIs without binary handling.
-
-```typescript file=@cesdk_web_examples/guides-conversion-to-base64-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');
-
-    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());
-
-    const engine = cesdk.engine;
-
-    await engine.scene.loadFromURL(
-      'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_postcard_1.scene'
-    );
-    const page = engine.scene.getCurrentPage()!;
-
-    await engine.scene.zoomToBlock(page);
-
-    cesdk.ui.insertOrderComponent(
-      { in: 'ly.img.navigation.bar', position: 'end' },
-      {
-        id: 'ly.img.actions.navigationBar',
-        children: [
-          {
-            id: 'ly.img.action.navigationBar',
-            onClick: async () => {
-              const currentPage = engine.scene.getCurrentPage()!;
-              const blob = await engine.block.export(currentPage, {
-                mimeType: 'image/png'
-              });
-              const base64 = await this.blobToBase64(blob);
-              await cesdk.utils.downloadFile(blob, 'image/png');
-              cesdk.ui.showNotification({
-                message: `Base64: ${(base64.length / 1024).toFixed(0)} KB`,
-                type: 'success'
-              });
-            },
-            key: 'export-base64',
-            label: 'To Base64',
-            icon: '@imgly/Save'
-          }
-        ]
-      }
-    );
-
-    cesdk.actions.register('exportDesign', async () => {
-      const currentPage = engine.scene.getCurrentPage()!;
-      const blob = await engine.block.export(currentPage, {
-        mimeType: 'image/png'
-      });
-      const base64 = await this.blobToBase64(blob);
-      console.log(`Exported PNG as base64 (${base64.length} chars).`);
-      await cesdk.utils.downloadFile(blob, 'image/png');
-    });
-  }
+>
+> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-conversion-to-base64-server-js)
+>
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-conversion-to-base64-server-js)
+
+Base64 encoding transforms binary image data into ASCII text, enabling you to store images in text-only databases, transmit them through JSON APIs, or embed them in HTML email templates.
+
+```typescript file=@cesdk_web_examples/guides-conversion-to-base64-server-js/server-js.ts reference-only
+import CreativeEngine from '@cesdk/node';
+import { config } from 'dotenv';
+import { writeFileSync, mkdirSync, existsSync } from 'fs';
+import * as readline from 'readline';
+
+config();
+
+const OUTPUT_DIR = './output';
 
-  private blobToBase64(blob: Blob): Promise<string> {
-    return new Promise((resolve, reject) => {
-      const reader = new FileReader();
-      reader.onloadend = () => resolve(reader.result as string);
-      reader.onerror = () => reject(reader.error);
-      reader.readAsDataURL(blob);
+function prompt(question: string): Promise<string> {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase());
     });
-  }
+  });
+}
+
+function showProgress(msg: string): () => void {
+  const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  let i = 0;
+  process.stdout.write(`${frames[0]} ${msg}`);
+  const id = setInterval(() => {
+    i = (i + 1) % frames.length;
+    process.stdout.write(`\r${frames[i]} ${msg}`);
+  }, 80);
+  return () => {
+    clearInterval(id);
+    process.stdout.write(`\r✓ ${msg}\n`);
+  };
 }
 
-export default Example;
+const engine = await CreativeEngine.init({
+  baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
+});
+
+try {
+  let done = showProgress('Loading scene...');
+  await engine.scene.loadFromURL(
+    'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_postcard_1.scene'
+  );
+  done();
+
+  const page = engine.block.findByType('page')[0];
+  if (!page) throw new Error('No page found');
+
+  console.log('\n┌───────────────────────────────────┐');
+  console.log('│   Convert to Base64               │');
+  console.log('├───────────────────────────────────┤');
+  console.log('│   Scene loaded successfully.      │');
+  console.log('│   Ready to export as PNG Base64.  │');
+  console.log('└───────────────────────────────────┘\n');
+
+  const confirm = await prompt('Export to Base64? (y/n): ');
+  if (confirm !== 'y' && confirm !== 'yes') {
+    console.log('\nExport cancelled.\n');
+    process.exit(0);
+  }
+
+  if (!existsSync(OUTPUT_DIR)) mkdirSync(OUTPUT_DIR, { recursive: true });
+
+  done = showProgress('Exporting to Base64...');
+
+  const blob = await engine.block.export(page, {
+    mimeType: 'image/png'
+  });
+
+  done();
+
+  const buffer = Buffer.from(await blob.arrayBuffer());
+  const base64 = buffer.toString('base64');
+  const dataUri = `data:${blob.type};base64,${base64}`;
+
+  writeFileSync(`${OUTPUT_DIR}/export.png`, buffer);
+  writeFileSync(`${OUTPUT_DIR}/base64.txt`, dataUri);
+
+  console.log(`\n✓ Saved: ${OUTPUT_DIR}/export.png`);
+  console.log(`✓ Saved: ${OUTPUT_DIR}/base64.txt`);
+  console.log(`  Binary: ${(blob.size / 1024).toFixed(1)} KB`);
+  console.log(
+    `  Base64: ${(dataUri.length / 1024).toFixed(1)} KB (~33% overhead)\n`
+  );
+} finally {
+  engine.dispose();
+}
 ```
 
 ## Export a Block to Base64
 
-Use `engine.block.export()` to export a design block as a Blob, then convert it to a Base64 data URI.
+Use `engine.block.export()` to export a design block as a Blob, then convert it to a Base64 string.
 
 ```typescript
-const currentPage = engine.scene.getCurrentPage()!;
-const blob = await engine.block.export(currentPage, {
+const page = engine.block.findByType('page')[0];
+const blob = await engine.block.export(page, {
   mimeType: 'image/png'
 });
-const base64 = await blobToBase64(blob);
 ```
 
-The export returns a Blob containing the rendered image. You then convert this Blob to a Base64 data URI using the browser's `FileReader` API. The resulting string includes the MIME type prefix (`data:image/png;base64,...`), making it ready for immediate use as an image source.
+The export returns a Blob containing the rendered image. You then convert this Blob to a Base64 string using Node.js Buffer APIs.
 
 ## Convert Blob to Base64
 
-Convert the exported Blob into a Base64 data URI using the browser's `FileReader` API.
+Convert the exported Blob into a Base64 data URI using Node.js `Buffer` API.
 
 ```typescript highlight=highlight-convert-base64
-private blobToBase64(blob: Blob): Promise<string> {
-  return new Promise((resolve, reject) => {
-    const reader = new FileReader();
-    reader.onloadend = () => resolve(reader.result as string);
-    reader.onerror = () => reject(reader.error);
-    reader.readAsDataURL(blob);
-  });
-}
+const buffer = Buffer.from(await blob.arrayBuffer());
+const base64 = buffer.toString('base64');
+const dataUri = `data:${blob.type};base64,${base64}`;
 ```
 
-The `readAsDataURL()` method returns a complete data URI including the MIME type prefix (`data:image/png;base64,...`). This wrapper converts the callback-based FileReader into a Promise for cleaner async/await usage.
+The `toString('base64')` method encodes the buffer contents. Prepending the MIME type prefix (`data:image/png;base64,...`) creates a complete data URI ready for storage or transmission.
 
-## Customize the Built-in Export Action
+## Save to File System
 
-Override the default `exportDesign` action to integrate Base64 conversion into CE.SDK's built-in export flow.
+Write both the binary image and Base64 text to the output directory.
 
-```typescript highlight=highlight-custom-action
-cesdk.actions.register('exportDesign', async () => {
-  const currentPage = engine.scene.getCurrentPage()!;
-  const blob = await engine.block.export(currentPage, {
-    mimeType: 'image/png'
-  });
-  const base64 = await this.blobToBase64(blob);
-  console.log(`Exported PNG as base64 (${base64.length} chars).`);
-  await cesdk.utils.downloadFile(blob, 'image/png');
-});
+```typescript highlight=highlight-save-file
+writeFileSync(`${OUTPUT_DIR}/export.png`, buffer);
+writeFileSync(`${OUTPUT_DIR}/base64.txt`, dataUri);
 ```
 
-When registered, this action replaces the default export behavior. Any UI component or keyboard shortcut that triggers `exportDesign` will use your custom handler instead.
-
-## Download the Export
-
-Use `cesdk.utils.downloadFile()` to save the exported Blob to the user's device. The method accepts a Blob and MIME type, triggering a browser download with the appropriate file extension.
+Saving both formats lets you compare file sizes and verify the Base64 encoding. The binary file is useful for visual inspection.
 
 ## When to Use Base64
 
 Base64 encoding works well for:
 
-- Embedding images directly in HTML or CSS without additional HTTP requests
-- Storing images in text-only databases like Redis or localStorage
+- Storing images in text-only databases like Redis or document stores
 - Transmitting images through JSON APIs that don't support binary data
-- Generating data URIs for email templates
+- Embedding images in HTML email templates
+- Caching image data as strings in configuration files
 
 > **Note:** Base64 increases file size by approximately 33%. For images larger than 100KB, consider binary storage or direct URL references instead.
 
@@ -202,20 +161,19 @@ Base64 encoding works well for:
 
 **Base64 string too long** — Use JPEG or WebP formats with lower quality settings. Reduce dimensions with `targetWidth` and `targetHeight` export options.
 
-**Image not displaying** — Verify the data URI includes the correct MIME type prefix. Check that the string wasn't truncated during storage or transmission.
+**Memory issues with large images** — Process images sequentially rather than in parallel. For very large exports, consider streaming approaches.
 
-**Performance issues** — FileReader operations are asynchronous but encoding large images can still block the UI. Consider Web Workers for images over 1MB.
+**Corrupted output** — Ensure the Buffer is created from the complete ArrayBuffer before encoding. Verify the Blob is fully loaded before conversion.
 
 ## API Reference
 
-| Method                                     | Description                                                                                                            |
-| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
-| `engine.block.export(block, options)`      | Export a block to a Blob with format options (`mimeType`, `jpegQuality`, `webpQuality`, `targetWidth`, `targetHeight`) |
-| `engine.scene.getCurrentPage()`            | Get the currently active page block                                                                                    |
-| `FileReader.readAsDataURL(blob)`           | Convert Blob to Base64 data URI (Browser API)                                                                          |
-| `cesdk.utils.downloadFile(blob, mimeType)` | Download a Blob as a file                                                                                              |
-| `cesdk.actions.register(name, handler)`    | Register or override an action                                                                                         |
-| `cesdk.ui.showNotification(options)`       | Display a notification to the user                                                                                     |
+| Method | Description |
+|--------|-------------|
+| `engine.block.export(block, options)` | Export a block to a Blob with format options (`mimeType`, `jpegQuality`, `webpQuality`, `targetWidth`, `targetHeight`) |
+| `engine.block.findByType(type)` | Find all blocks of a specific type |
+| `engine.scene.loadFromURL(url)` | Load a scene from a remote URL |
+| `Buffer.from(arrayBuffer)` | Create a Buffer from ArrayBuffer (Node.js) |
+| `buffer.toString('base64')` | Encode Buffer as Base64 string (Node.js) |
 
 ## Next Steps
 
@@ -224,11 +182,13 @@ Base64 encoding works well for:
 - [Partial Export](./export-save-publish/export/partial-export.md) — Export specific regions or individual elements
 - [Size Limits](./export-save-publish/export/size-limits.md) — Handle large exports and memory constraints
 
+
+
 ---
 
 ## 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