@imgly/codesign-mcp 0.1.5 → 0.1.7

package/assets/docs/guide/use-templates/generate.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) > [Create and Use Templates](./create-templates.md) > [Generate From Template](./use-templates/generate.md)
 
@@ -6,69 +6,61 @@
 
 Generate finished designs from templates by loading, populating variables, and exporting to images, PDFs, or videos programmatically.
 
-![Generate From Template example showing a personalized greeting card](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-use-templates-generate-browser)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-use-templates-generate-browser)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-use-templates-generate-browser/)
+>
+> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-use-templates-generate-server-js)
+>
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-use-templates-generate-server-js)
 
 Template generation transforms templates into finished designs by populating data and exporting to output formats. Load templates with `engine.scene.loadFromURL()`, set variables with `engine.variable.setString()`, and export with `engine.block.export()`. This enables batch processing, personalization systems, and automated design production.
 
-```typescript file=@cesdk_web_examples/guides-use-templates-generate-browser/browser.ts reference-only
-import type { EditorPlugin, EditorPluginContext } from '@cesdk/cesdk-js';
+```typescript file=@cesdk_web_examples/guides-use-templates-generate-server-js/server-js.ts reference-only
+import CreativeEngine from '@cesdk/node';
+import { writeFileSync, mkdirSync, existsSync } from 'fs';
+import { config } from 'dotenv';
 
-import { DesignEditorConfig } from './design-editor/plugin';
-import packageJson from './package.json';
+// Load environment variables
+config();
 
 /**
- * CE.SDK Plugin: Generate From Template Guide
+ * CE.SDK Server Guide: Generate From Template
  *
  * Demonstrates how to generate finished designs from templates:
  * - Loading templates from URLs
  * - Populating template variables
  * - Finding and updating placeholder content
- * - Exporting to images and creating downloadable files
+ * - Exporting to images and PDFs
  * - Batch generation workflows
  */
-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');
-    }
+async function main() {
+  // Initialize the headless Creative Engine
+  const engine = await CreativeEngine.init({
+    baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
+    // license: process.env.CESDK_LICENSE
+  });
 
-    await cesdk.addPlugin(new DesignEditorConfig());
-    const engine = cesdk.engine;
+  try {
 
     // Load a template from URL - this template has visible {{variable}} placeholders
     await engine.scene.loadFromURL(
       'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_postcard_2.scene'
     );
-    console.log(
-      'Template loaded - variable placeholders like {{first_name}}, {{city}} are now visible on the canvas'
-    );
+    console.log('Template loaded from URL');
 
     // Discover available variables in the template
     const allVariables = engine.variable.findAll();
     console.log('Available variables:', allVariables);
 
-    // Wait 3 seconds so users can see the variable placeholders before population
-    await new Promise((resolve) => setTimeout(resolve, 3000));
-
     // Set variable values to replace {{variableName}} placeholders
     engine.variable.setString('first_name', 'Alice');
     engine.variable.setString('last_name', 'Smith');
     engine.variable.setString('city', 'Paris');
     engine.variable.setString('address', '10 Rue de Rivoli');
-    console.log('Variables populated - placeholders replaced with values');
+    console.log('Variables populated');
 
     // Find all placeholder blocks in the template
     const placeholders = engine.block.findAllPlaceholders();
@@ -94,6 +86,11 @@ class Example implements EditorPlugin {
     }
 
     // Export the populated template to PNG
+    const outputDir = './output';
+    if (!existsSync(outputDir)) {
+      mkdirSync(outputDir, { recursive: true });
+    }
+
     const pages = engine.block.findByType('page');
     if (pages.length > 0) {
       const page = pages[0];
@@ -102,17 +99,9 @@ class Example implements EditorPlugin {
         targetWidth: 1920,
         targetHeight: 1080
       });
-      console.log('Exported to PNG:', blob.size, 'bytes');
-
-      // Create downloadable file
-      const url = URL.createObjectURL(blob);
-      console.log('Download URL created:', url);
-      // In a real application, you would trigger a download:
-      // const link = document.createElement('a');
-      // link.href = url;
-      // link.download = 'greeting-card.png';
-      // link.click();
-      // URL.revokeObjectURL(url);
+      const buffer = Buffer.from(await blob.arrayBuffer());
+      writeFileSync(`${outputDir}/greeting-card.png`, buffer);
+      console.log('Exported to output/greeting-card.png');
     }
 
     // Export to PDF format
@@ -121,7 +110,9 @@ class Example implements EditorPlugin {
       const pdfBlob = await engine.block.export(scene, {
         mimeType: 'application/pdf'
       });
-      console.log('Exported to PDF:', pdfBlob.size, 'bytes');
+      const pdfBuffer = Buffer.from(await pdfBlob.arrayBuffer());
+      writeFileSync(`${outputDir}/greeting-card.pdf`, pdfBuffer);
+      console.log('Exported to output/greeting-card.pdf');
     }
 
     // Demonstrate batch generation workflow
@@ -151,7 +142,9 @@ class Example implements EditorPlugin {
       }
     ];
 
-    for (const record of dataRecords) {
+    for (let i = 0; i < dataRecords.length; i++) {
+      const record = dataRecords[i];
+
       // Reload template for each record
       await engine.scene.loadFromString(templateString);
 
@@ -161,29 +154,32 @@ class Example implements EditorPlugin {
       engine.variable.setString('city', record.city);
       engine.variable.setString('address', record.address);
 
-      console.log(
-        `Processed record for: ${record.firstName} ${record.lastName}`
-      );
-      // In a real workflow, you would export here:
-      // const blob = await engine.block.export(page, { mimeType: 'image/png' });
+      // Export each personalized version
+      const batchPages = engine.block.findByType('page');
+      if (batchPages.length > 0) {
+        const batchPage = batchPages[0];
+        const batchBlob = await engine.block.export(batchPage, {
+          mimeType: 'image/png'
+        });
+        const batchBuffer = Buffer.from(await batchBlob.arrayBuffer());
+        writeFileSync(
+          `${outputDir}/batch-${record.firstName.toLowerCase()}.png`,
+          batchBuffer
+        );
+        console.log(
+          `Exported batch image for: ${record.firstName} ${record.lastName}`
+        );
+      }
     }
 
     console.log(`Batch processed ${dataRecords.length} records`);
-
-    // Reload the original template for display
-    await engine.scene.loadFromString(templateString);
-    engine.variable.setString('first_name', 'Alice');
-    engine.variable.setString('last_name', 'Smith');
-    engine.variable.setString('city', 'Paris');
-    engine.variable.setString('address', '10 Rue de Rivoli');
-
-    console.log(
-      'Generate from template guide initialized. The template demonstrates loading, variable population, and export workflows.'
-    );
+  } finally {
+    // Always dispose of the engine to free resources
+    engine.dispose();
   }
 }
 
-export default Example;
+main().catch(console.error);
 ```
 
 This guide covers how to load templates, populate variables, update placeholder content, and export to various formats including batch generation workflows.
@@ -197,9 +193,7 @@ Load templates from various sources before populating and exporting. Use `engine
 await engine.scene.loadFromURL(
   'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_postcard_2.scene'
 );
-console.log(
-  'Template loaded - variable placeholders like {{first_name}}, {{city}} are now visible on the canvas'
-);
+console.log('Template loaded from URL');
 ```
 
 ## Populating Variables
@@ -226,7 +220,7 @@ engine.variable.setString('first_name', 'Alice');
 engine.variable.setString('last_name', 'Smith');
 engine.variable.setString('city', 'Paris');
 engine.variable.setString('address', '10 Rue de Rivoli');
-console.log('Variables populated - placeholders replaced with values');
+console.log('Variables populated');
 ```
 
 ## Updating Placeholder Content
@@ -234,15 +228,15 @@ console.log('Variables populated - placeholders replaced with values');
 Beyond variables, templates often contain placeholder blocks for images and other content. Find these blocks using `engine.block.findByName()` or `engine.block.findAllPlaceholders()`.
 
 ```typescript highlight=highlight-find-placeholders
-// Find all placeholder blocks in the template
-const placeholders = engine.block.findAllPlaceholders();
-console.log('Found placeholders:', placeholders.length);
-
-// Find specific blocks by name
-const namedBlocks = engine.block.findByName('Image');
-if (namedBlocks.length > 0) {
-  console.log('Found image block by name:', namedBlocks[0]);
-}
+    // Find all placeholder blocks in the template
+    const placeholders = engine.block.findAllPlaceholders();
+    console.log('Found placeholders:', placeholders.length);
+
+    // Find specific blocks by name
+    const namedBlocks = engine.block.findByName('Image');
+    if (namedBlocks.length > 0) {
+      console.log('Found image block by name:', namedBlocks[0]);
+    }
 ```
 
 ### Update Image Placeholders
@@ -269,27 +263,24 @@ if (imageBlocks.length > 0) {
 Generate image outputs using `engine.block.export()` with options for format, resolution, and quality. Find the page to export with `engine.block.findByType('page')`.
 
 ```typescript highlight=highlight-export-image
-// Export the populated template to PNG
-const pages = engine.block.findByType('page');
-if (pages.length > 0) {
-  const page = pages[0];
-  const blob = await engine.block.export(page, {
-    mimeType: 'image/png',
-    targetWidth: 1920,
-    targetHeight: 1080
-  });
-  console.log('Exported to PNG:', blob.size, 'bytes');
-
-  // Create downloadable file
-  const url = URL.createObjectURL(blob);
-  console.log('Download URL created:', url);
-  // In a real application, you would trigger a download:
-  // const link = document.createElement('a');
-  // link.href = url;
-  // link.download = 'greeting-card.png';
-  // link.click();
-  // URL.revokeObjectURL(url);
-}
+    // Export the populated template to PNG
+    const outputDir = './output';
+    if (!existsSync(outputDir)) {
+      mkdirSync(outputDir, { recursive: true });
+    }
+
+    const pages = engine.block.findByType('page');
+    if (pages.length > 0) {
+      const page = pages[0];
+      const blob = await engine.block.export(page, {
+        mimeType: 'image/png',
+        targetWidth: 1920,
+        targetHeight: 1080
+      });
+      const buffer = Buffer.from(await blob.arrayBuffer());
+      writeFileSync(`${outputDir}/greeting-card.png`, buffer);
+      console.log('Exported to output/greeting-card.png');
+    }
 ```
 
 You can configure export options including `targetWidth` and `targetHeight` for output resolution, `pngCompressionLevel` for PNG files (0-9), and `jpegQuality` for JPEG files (0-1).
@@ -305,7 +296,9 @@ if (scene !== null) {
   const pdfBlob = await engine.block.export(scene, {
     mimeType: 'application/pdf'
   });
-  console.log('Exported to PDF:', pdfBlob.size, 'bytes');
+  const pdfBuffer = Buffer.from(await pdfBlob.arrayBuffer());
+  writeFileSync(`${outputDir}/greeting-card.pdf`, pdfBuffer);
+  console.log('Exported to output/greeting-card.pdf');
 }
 ```
 
@@ -314,49 +307,73 @@ if (scene !== null) {
 Process multiple data records through a single template. Save the template once with `engine.scene.saveToString()`, then loop through records—reloading the template with `engine.scene.loadFromString()`, populating variables, and exporting for each iteration.
 
 ```typescript highlight=highlight-batch-generation
-// Demonstrate batch generation workflow
-// Save template for reuse
-const templateString = await engine.scene.saveToString();
-console.log('Template saved for batch processing');
-
-// Process multiple data records
-const dataRecords = [
-  {
-    firstName: 'Alice',
-    lastName: 'Smith',
-    city: 'Paris',
-    address: '10 Rue de Rivoli'
-  },
-  {
-    firstName: 'Bob',
-    lastName: 'Johnson',
-    city: 'London',
-    address: '221B Baker Street'
-  },
-  {
-    firstName: 'Carol',
-    lastName: 'Williams',
-    city: 'Tokyo',
-    address: '1-1 Shibuya'
-  }
-];
+    // Demonstrate batch generation workflow
+    // Save template for reuse
+    const templateString = await engine.scene.saveToString();
+    console.log('Template saved for batch processing');
 
-for (const record of dataRecords) {
-  // Reload template for each record
-  await engine.scene.loadFromString(templateString);
+    // Process multiple data records
+    const dataRecords = [
+      {
+        firstName: 'Alice',
+        lastName: 'Smith',
+        city: 'Paris',
+        address: '10 Rue de Rivoli'
+      },
+      {
+        firstName: 'Bob',
+        lastName: 'Johnson',
+        city: 'London',
+        address: '221B Baker Street'
+      },
+      {
+        firstName: 'Carol',
+        lastName: 'Williams',
+        city: 'Tokyo',
+        address: '1-1 Shibuya'
+      }
+    ];
 
-  // Populate with record data
-  engine.variable.setString('first_name', record.firstName);
-  engine.variable.setString('last_name', record.lastName);
-  engine.variable.setString('city', record.city);
-  engine.variable.setString('address', record.address);
+    for (let i = 0; i < dataRecords.length; i++) {
+      const record = dataRecords[i];
 
-  console.log(`Processed record for: ${record.firstName} ${record.lastName}`);
-  // In a real workflow, you would export here:
-  // const blob = await engine.block.export(page, { mimeType: 'image/png' });
-}
+      // Reload template for each record
+      await engine.scene.loadFromString(templateString);
+
+      // Populate with record data
+      engine.variable.setString('first_name', record.firstName);
+      engine.variable.setString('last_name', record.lastName);
+      engine.variable.setString('city', record.city);
+      engine.variable.setString('address', record.address);
+
+      // Export each personalized version
+      const batchPages = engine.block.findByType('page');
+      if (batchPages.length > 0) {
+        const batchPage = batchPages[0];
+        const batchBlob = await engine.block.export(batchPage, {
+          mimeType: 'image/png'
+        });
+        const batchBuffer = Buffer.from(await batchBlob.arrayBuffer());
+        writeFileSync(
+          `${outputDir}/batch-${record.firstName.toLowerCase()}.png`,
+          batchBuffer
+        );
+        console.log(
+          `Exported batch image for: ${record.firstName} ${record.lastName}`
+        );
+      }
+    }
 
-console.log(`Batch processed ${dataRecords.length} records`);
+    console.log(`Batch processed ${dataRecords.length} records`);
+```
+
+## Cleanup
+
+Always dispose of the engine when finished to free resources. Use a try-finally block to ensure cleanup happens even if errors occur.
+
+```typescript highlight=highlight-cleanup
+// Always dispose of the engine to free resources
+engine.dispose();
 ```
 
 ## Troubleshooting
@@ -379,27 +396,29 @@ Verify the exact name string matches what's set in the template. Names are case-
 
 ## API Reference
 
-| Method                                    | Description                                 |
-| ----------------------------------------- | ------------------------------------------- |
-| `scene.loadFromURL(url)`                  | Load template from remote URL               |
-| `scene.loadFromString(data)`              | Load template from serialized string        |
-| `scene.loadFromArchiveURL(url)`           | Load archived template with embedded assets |
-| `scene.saveToString()`                    | Serialize scene for batch processing        |
-| `variable.setString(name, value)`         | Set text variable value                     |
-| `variable.getString(name)`                | Retrieve current variable value             |
-| `variable.findAll()`                      | List all variable names in scene            |
-| `block.findByName(name)`                  | Find blocks by name identifier              |
-| `block.findByType(type)`                  | Find blocks by type (e.g., 'page')          |
-| `block.findAllPlaceholders()`             | Discover all placeholder blocks             |
-| `block.getFill(block)`                    | Get fill block from graphic block           |
-| `block.setString(block, property, value)` | Set string properties like image URIs       |
-| `block.export(block, options)`            | Export block to image or PDF blob           |
+| Method | Description |
+|--------|-------------|
+| `scene.loadFromURL(url)` | Load template from remote URL |
+| `scene.loadFromString(data)` | Load template from serialized string |
+| `scene.loadFromArchiveURL(url)` | Load archived template with embedded assets |
+| `scene.saveToString()` | Serialize scene for batch processing |
+| `variable.setString(name, value)` | Set text variable value |
+| `variable.getString(name)` | Retrieve current variable value |
+| `variable.findAll()` | List all variable names in scene |
+| `block.findByName(name)` | Find blocks by name identifier |
+| `block.findByType(type)` | Find blocks by type (e.g., 'page') |
+| `block.findAllPlaceholders()` | Discover all placeholder blocks |
+| `block.getFill(block)` | Get fill block from graphic block |
+| `block.setString(block, property, value)` | Set string properties like image URIs |
+| `block.export(block, options)` | Export block to image or PDF blob |
+
+
 
 ---
 
 ## 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/use-templates/overview.md

@@ -1,20 +1,48 @@
-> 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) > [Create and Use Templates](./create-templates.md) > [Use Templates Overview](./use-templates/overview.md)
 
 ---
 
+Templates in CreativeEditor SDK (CE.SDK) are pre-designed layouts that serve as starting points for generating static designs, videos, or print-ready outputs. Templates can be used to produce a wide range of media, including images, PDFs, and videos.
+
+Instead of creating a design from scratch, you can use a template to quickly produce content by adapting pre-defined elements like text, images, and layout structures.
+
+Using templates offers significant advantages: faster content creation, consistent visual style, and scalable design workflows across many outputs.
+
+[Launch Web Demo](https://img.ly/showcases/cesdk)
+
+[Get Started](./get-started/overview.md)
+
+## Working with Dynamic Content
+
+CE.SDK templates support dynamic placeholders for content such as text, images, and custom elements. You can replace dynamic content programmatically. External data (e.g., from a database, CSV file, or API) can be merged automatically into placeholders without requiring user interaction.
+
+This flexibility supports both one-off customizations and large-scale content generation scenarios.
+
+## Exploring the Template Library
+
+Templates are stored, organized, and managed through the CE.SDK Template Library. This library acts as a centralized place where templates are categorized and retrieved.
+
+You can work with:
+
+- **Default Templates**: Templates that come bundled with the SDK to help you get started quickly.
+- **Custom Templates**: Templates you create based on your specific use case, offering full flexibility over design, dynamic fields, and editing constraints.
+- **Premium Templates**: Additional high-quality templates provided by IMG.LY, which can be integrated into your application if licensed.
+
 ## Output Formats When Using Templates
 
 When generating outputs from templates, CE.SDK supports:
 
 Templates are format-aware, allowing you to design once and export to multiple formats seamlessly. For example, a single marketing template could be used to produce a social media graphic, a printable flyer, and a promotional video, all using the same underlying design.
 
+
+
 ---
 
 ## 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