@imgly/codesign-mcp 0.1.5 → 0.1.6

package/assets/docs/guide/create-templates/import/from-scene-file.md

@@ -1,92 +1,52 @@
-> 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) > [Import Templates](./create-templates/import.md) > [From Scene File](./create-templates/import/from-scene-file.md)
 
 ---
 
-CE.SDK lets you load complete design templates from scene files to start projects from pre-designed templates, implement template galleries, and build template management systems.
-
-![Import Templates from Scene Files example showing CE.SDK interface with loaded template](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
+CE.SDK lets you load complete design templates from scene files programmatically in a headless environment for automation, batch processing, and server-side template management.
 
 > **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-create-templates-import-from-scene-file-browser)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-create-templates-import-from-scene-file-browser)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-create-templates-import-from-scene-file-browser/)
-
-Scene files are portable design templates that preserve the entire design structure including blocks, assets, styles, and layout.
-
-```typescript file=@cesdk_web_examples/guides-create-templates-import-from-scene-file-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';
+>
+> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-create-templates-import-from-scene-file-server-js)
+>
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-create-templates-import-from-scene-file-server-js)
 
+Scene files are portable design templates that preserve the entire design structure including blocks, assets, styles, and layout. In a headless environment, we can load and process these templates programmatically.
+
+```typescript file=@cesdk_web_examples/guides-create-templates-import-from-scene-file-server-js/server-js.ts reference-only
 /**
- * CE.SDK Plugin: Import Templates from Scene Files
+ * CE.SDK Node.js Example: Import Templates from Scene Files
  *
  * This example demonstrates:
  * - Loading scenes from .scene file URLs
  * - Loading scenes from .archive (ZIP) URLs
  * - Applying templates while preserving page dimensions
  * - Understanding the difference between loading and applying templates
+ * - Working with scene files programmatically in a headless environment
  */
-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');
-    }
+import CreativeEngine from '@cesdk/node';
+import { writeFileSync } from 'fs';
+import { config } from 'dotenv';
 
-    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());
+// Load environment variables from .env file
+config();
+
+const configuration = {
+  baseURL: process.env.IMGLY_LOCAL_ASSETS_URL,
+  userId: 'guides-user'
+};
 
-    const engine = cesdk.engine;
+async function main() {
+  // Initialize the headless creative engine
+  const engine = await CreativeEngine.init(configuration);
 
+  try {
     // ===== Example: Load Scene from Archive URL =====
     // This is the recommended approach for loading complete templates
     // with all their assets embedded in a ZIP file
@@ -97,56 +57,87 @@ class Example implements EditorPlugin {
       'https://cdn.img.ly/assets/templates/starterkits/16-9-fashion-ad.zip'
     );
 
+    // Get information about the loaded scene
+    const scene = engine.scene.get();
+    console.log(scene);
+    if (scene == null) {
+      throw new Error('Failed to get scene after loading');
+    }
+
+    console.log('Scene loaded successfully:', scene);
+
+    // Get all pages in the scene
+    const pages = engine.scene.getPages();
+    console.log(`Scene has ${pages.length} page(s)`);
+
+    // Get design unit (Pixel, Millimeter, Inch)
+    const designUnit = engine.scene.getDesignUnit();
+    console.log('Design unit:', designUnit);
+
+    // Export the scene to a PNG file
+    const blob = await engine.block.export(scene, { mimeType: 'image/png' });
+    const buffer = Buffer.from(await blob.arrayBuffer());
+    writeFileSync('output-from-archive.png', buffer);
+    console.log('Exported scene to output-from-archive.png');
+
     // Alternative: Load scene from URL (.scene file)
     // This loads only the scene structure - assets must be accessible via URLs
     // Uncomment to try:
     // await engine.scene.loadFromURL(
     //   'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_postcard_1.scene'
     // );
+    //
+    // // Export the loaded scene
+    // const sceneFromUrl = engine.scene.get();
+    // if (sceneFromUrl) {
+    //   const blob2 = await engine.block.export(sceneFromUrl, 'image/png');
+    //   const buffer2 = Buffer.from(await blob2.arrayBuffer());
+    //   writeFileSync('output-from-url.png', buffer2);
+    //   console.log('Exported scene to output-from-url.png');
+    // }
 
     // Alternative: Apply template while preserving current page dimensions
     // This is useful when you want to load template content into an existing scene
     // with specific dimensions
     // Uncomment to try:
     // // First create a scene with specific dimensions
-    // await cesdk.actions.run('scene.create', { page: { width: 1920, height: 1080, unit: 'Pixel' } });
+    // engine.scene.create();
     // const page = engine.block.findByType('page')[0];
+    // engine.block.setWidth(page, 1920);
+    // engine.block.setHeight(page, 1080);
     //
     // // Now apply template - content will be adjusted to fit
     // await engine.scene.applyTemplateFromURL(
     //   'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_instagram_photo_1.scene'
     // );
-
-    // Get the loaded scene
-    const scene = engine.scene.get();
-    if (scene) {
-      // eslint-disable-next-line no-console
-      console.log('Scene loaded successfully:', scene);
-
-      // Get information about the loaded scene
-      const pages = engine.scene.getPages();
-      // eslint-disable-next-line no-console
-      console.log(`Scene has ${pages.length} page(s)`);
-
-      // Get design unit
-      const designUnit = engine.scene.getDesignUnit();
-      // eslint-disable-next-line no-console
-      console.log('Design unit:', designUnit);
-    }
-
-    // Zoom to fit the loaded content
-    if (scene) {
-      await engine.scene.zoomToBlock(scene, {
-        padding: 40
-      });
-    }
+    //
+    // // Export the scene with applied template
+    // const appliedScene = engine.scene.get();
+    // if (appliedScene) {
+    //   const blob3 = await engine.block.export(appliedScene, 'image/png');
+    //   const buffer3 = Buffer.from(await blob3.arrayBuffer());
+    //   writeFileSync('output-applied-template.png', buffer3);
+    //   console.log('Exported scene to output-applied-template.png');
+    // }
+
+    console.log('Example completed successfully!');
+  } catch (error) {
+    console.error('Error:', error);
+    throw error;
+  } finally {
+    // Always dispose the engine when done
+    engine.dispose();
   }
 }
 
-export default Example;
+// Run the example
+main().catch((error) => {
+  console.error('Failed to run example:', error);
+  process.exit(1);
+});
 ```
 
-This guide covers loading scenes from archives, loading from URLs, applying templates while preserving dimensions, and understanding scene file formats.
+This guide covers loading scenes from archives, loading from URLs, applying templates while preserving dimensions, and exporting the results.
 
 ## Scene File Formats
 
@@ -177,133 +168,6 @@ Archive files are self-contained packages that bundle the scene structure with a
 
 The most common way to load templates is from archive URLs. This method loads both the scene structure and all embedded assets:
 
-```typescript file=@cesdk_web_examples/guides-create-templates-import-from-scene-file-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';
-
-/**
- * CE.SDK Plugin: Import Templates from Scene Files
- *
- * This example demonstrates:
- * - Loading scenes from .scene file URLs
- * - Loading scenes from .archive (ZIP) URLs
- * - Applying templates while preserving page dimensions
- * - Understanding the difference between loading and applying templates
- */
-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.*'
-        ]
-      })
-    );
-    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;
-
-    // ===== Example: Load Scene from Archive URL =====
-    // This is the recommended approach for loading complete templates
-    // with all their assets embedded in a ZIP file
-
-    // Load a complete template from an archive (ZIP) file
-    // This loads both the scene structure and all embedded assets
-    await engine.scene.loadFromArchiveURL(
-      'https://cdn.img.ly/assets/templates/starterkits/16-9-fashion-ad.zip'
-    );
-
-    // Alternative: Load scene from URL (.scene file)
-    // This loads only the scene structure - assets must be accessible via URLs
-    // Uncomment to try:
-    // await engine.scene.loadFromURL(
-    //   'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_postcard_1.scene'
-    // );
-
-    // Alternative: Apply template while preserving current page dimensions
-    // This is useful when you want to load template content into an existing scene
-    // with specific dimensions
-    // Uncomment to try:
-    // // First create a scene with specific dimensions
-    // await cesdk.actions.run('scene.create', { page: { width: 1920, height: 1080, unit: 'Pixel' } });
-    // const page = engine.block.findByType('page')[0];
-    //
-    // // Now apply template - content will be adjusted to fit
-    // await engine.scene.applyTemplateFromURL(
-    //   'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_instagram_photo_1.scene'
-    // );
-
-    // Get the loaded scene
-    const scene = engine.scene.get();
-    if (scene) {
-      // eslint-disable-next-line no-console
-      console.log('Scene loaded successfully:', scene);
-
-      // Get information about the loaded scene
-      const pages = engine.scene.getPages();
-      // eslint-disable-next-line no-console
-      console.log(`Scene has ${pages.length} page(s)`);
-
-      // Get design unit
-      const designUnit = engine.scene.getDesignUnit();
-      // eslint-disable-next-line no-console
-      console.log('Design unit:', designUnit);
-    }
-
-    // Zoom to fit the loaded content
-    if (scene) {
-      await engine.scene.zoomToBlock(scene, {
-        padding: 40
-      });
-    }
-  }
-}
-
-export default Example;
-```
-
 ```typescript highlight-load-from-archive
 // Load a complete template from an archive (ZIP) file
 // This loads both the scene structure and all embedded assets
@@ -327,6 +191,15 @@ You can also load scenes directly from .scene file URLs. This approach requires
 // await engine.scene.loadFromURL(
 //   'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_postcard_1.scene'
 // );
+//
+// // Export the loaded scene
+// const sceneFromUrl = engine.scene.get();
+// if (sceneFromUrl) {
+//   const blob2 = await engine.block.export(sceneFromUrl, 'image/png');
+//   const buffer2 = Buffer.from(await blob2.arrayBuffer());
+//   writeFileSync('output-from-url.png', buffer2);
+//   console.log('Exported scene to output-from-url.png');
+// }
 ```
 
 **Important:** With this method, if asset URLs become unavailable (404 errors, CORS issues, etc.), those assets won't load and your template may appear incomplete.
@@ -357,13 +230,59 @@ This is useful when you want to load template content into an existing scene wit
 
 ```typescript highlight-apply-template
 // // First create a scene with specific dimensions
-// await cesdk.actions.run('scene.create', { page: { width: 1920, height: 1080, unit: 'Pixel' } });
+// engine.scene.create();
 // const page = engine.block.findByType('page')[0];
+// engine.block.setWidth(page, 1920);
+// engine.block.setHeight(page, 1080);
 //
 // // Now apply template - content will be adjusted to fit
 // await engine.scene.applyTemplateFromURL(
 //   'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_instagram_photo_1.scene'
 // );
+//
+// // Export the scene with applied template
+// const appliedScene = engine.scene.get();
+// if (appliedScene) {
+//   const blob3 = await engine.block.export(appliedScene, 'image/png');
+//   const buffer3 = Buffer.from(await blob3.arrayBuffer());
+//   writeFileSync('output-applied-template.png', buffer3);
+//   console.log('Exported scene to output-applied-template.png');
+// }
+```
+
+## Get Scene Information
+
+After loading a template, we can retrieve information about the scene:
+
+```typescript highlight-get-scene-info
+    // Get information about the loaded scene
+    const scene = engine.scene.get();
+    console.log(scene);
+    if (scene == null) {
+      throw new Error('Failed to get scene after loading');
+    }
+
+    console.log('Scene loaded successfully:', scene);
+
+    // Get all pages in the scene
+    const pages = engine.scene.getPages();
+    console.log(`Scene has ${pages.length} page(s)`);
+
+    // Get design unit (Pixel, Millimeter, Inch)
+    const designUnit = engine.scene.getDesignUnit();
+    console.log('Design unit:', designUnit);
+```
+
+## Export Scene
+
+We can export the loaded scene to various formats:
+
+```typescript highlight-export-scene
+// Export the scene to a PNG file
+const blob = await engine.block.export(scene, { mimeType: 'image/png' });
+const buffer = Buffer.from(await blob.arrayBuffer());
+writeFileSync('output-from-archive.png', buffer);
+console.log('Exported scene to output-from-archive.png');
 ```
 
 ## Error Handling
@@ -379,8 +298,7 @@ try {
   await engine.scene.loadFromArchiveURL(templateUrl);
 } catch (error) {
   console.error('Failed to load template:', error);
-  // Show error message to user
-  // Fall back to default template or empty scene
+  // Fall back to default template or handle error
 }
 ```
 
@@ -412,29 +330,33 @@ Archive size directly impacts loading time:
 - Medium archives (1-5MB): 1-2 seconds
 - Large archives (> 5MB): Several seconds
 
-Show loading indicators for better user experience.
+For batch processing, consider parallel processing of independent templates.
 
 ## CORS Considerations
 
-When loading templates from external URLs, ensure proper CORS headers are set on the server hosting the files. Archives must be accessible with appropriate CORS policies.
+When loading templates from external URLs in Node.js, most CORS restrictions don't apply. However, ensure the URLs are accessible from your server environment and check for any firewall or network restrictions.
 
 ## API Reference
 
-| Method                                | Description                                         |
-| ------------------------------------- | --------------------------------------------------- |
-| `engine.scene.loadFromArchiveURL()`   | Loads a complete scene from an archive (ZIP) file   |
-| `engine.scene.loadFromURL()`          | Loads a scene from a .scene file URL                |
-| `engine.scene.applyTemplateFromURL()` | Applies a template while preserving page dimensions |
-| `engine.scene.get()`                  | Returns the current scene block ID                  |
-| `engine.scene.getPages()`             | Returns all page IDs in the scene                   |
-| `engine.scene.getDesignUnit()`        | Returns the measurement unit                        |
-| `engine.scene.zoomToBlock()`          | Zooms the viewport to fit a specific block          |
+| Method                                   | Description                                               |
+| ---------------------------------------- | --------------------------------------------------------- |
+| `engine.scene.loadFromArchiveURL()`      | Loads a complete scene from an archive (ZIP) file        |
+| `engine.scene.loadFromURL()`             | Loads a scene from a .scene file URL                      |
+| `engine.scene.applyTemplateFromURL()`    | Applies a template while preserving page dimensions      |
+| `engine.scene.get()`                     | Returns the current scene block ID                        |
+| `engine.scene.getPages()`                | Returns all page IDs in the scene                         |
+| `engine.scene.getDesignUnit()`           | Returns the measurement unit                              |
+| `engine.block.export()`                  | Exports a block to various formats                        |
+| `CreativeEngine.init()`                  | Initializes the headless engine                           |
+| `engine.dispose()`                       | Disposes the engine and frees resources                   |
+
+
 
 ---
 
 ## 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