@imgly/codesign-mcp 0.1.5 → 0.1.7

package/assets/docs/guide/create-templates/add-to-template-library.md

@@ -1,201 +1,183 @@
-> 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) > [Add to Template Library](./create-templates/add-to-template-library.md)
 
 ---
 
-Create a template library where users can browse, preview, and apply templates from a custom asset source.
-
-![Add to Template Library](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
+Create a template library where templates can be stored, managed, and applied programmatically in a headless environment.
 
 > **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-add-to-template-library-browser)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-create-templates-add-to-template-library-browser)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-create-templates-add-to-template-library-browser/)
-
-Templates in CE.SDK are stored and accessed through the asset system. A template library is a local asset source configured to hold and serve template assets, allowing users to browse thumbnails and apply templates to their designs.
+>
+> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-create-templates-add-to-template-library-server-js)
+>
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-create-templates-add-to-template-library-server-js)
 
-```typescript file=@cesdk_web_examples/guides-create-templates-add-to-template-library-browser/browser.ts reference-only
-import type { EditorPlugin, EditorPluginContext } from '@cesdk/cesdk-js';
+Templates in CE.SDK are stored and accessed through the asset system. A template library is a local asset source configured to hold and serve template assets, enabling server-side workflows to manage templates programmatically.
 
-import { DesignEditorConfig } from './design-editor/plugin';
-import packageJson from './package.json';
+```typescript file=@cesdk_web_examples/guides-create-templates-add-to-template-library-server-js/server-js.ts reference-only
+import CreativeEngine from '@cesdk/node';
+import * as readline from 'readline';
+import { mkdirSync, writeFileSync } from 'fs';
 
 /**
- * CE.SDK Plugin: Add to Template Library
+ * CE.SDK Server Guide: Add to Template Library
  *
  * This example demonstrates how to create a template library by:
  * 1. Creating a local asset source for templates
  * 2. Adding templates with metadata (label, thumbnail, URI)
- * 3. Configuring the UI to display the template library
- * 4. Saving scenes as templates
+ * 3. Saving scenes as templates
+ * 4. Managing templates programmatically
  */
-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());
-    const engine = cesdk.engine;
-
-    // Create a local asset source for templates
-    engine.asset.addLocalSource('my-templates', undefined, async (asset) => {
-      // Apply the selected template to the current scene
-      await engine.scene.applyTemplateFromURL(asset.meta!.uri as string);
-      // Set zoom to auto-fit after applying template
-      await cesdk.actions.run('zoom.toPage', { autoFit: true });
-      return undefined;
-    });
 
-    // Add a template to the source with metadata
-    engine.asset.addAssetToSource('my-templates', {
-      id: 'template-postcard',
-      label: { en: 'Postcard' },
-      meta: {
-        uri: 'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_postcard_1.scene',
-        thumbUri:
-          'https://cdn.img.ly/assets/demo/v3/ly.img.template/thumbnails/cesdk_postcard_1.jpg'
-      }
+// Helper function to prompt user for input
+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());
     });
+  });
+}
 
-    // Add more templates
-    engine.asset.addAssetToSource('my-templates', {
-      id: 'template-business-card',
-      label: { en: 'Business Card' },
-      meta: {
-        uri: 'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_business_card_1.scene',
-        thumbUri:
-          'https://cdn.img.ly/assets/demo/v3/ly.img.template/thumbnails/cesdk_business_card_1.jpg'
-      }
-    });
+// Initialize CE.SDK engine in headless mode
+const engine = await CreativeEngine.init({
+  baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
+});
 
-    engine.asset.addAssetToSource('my-templates', {
-      id: 'template-social-media',
-      label: { en: 'Social Media Post' },
-      meta: {
-        uri: 'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_instagram_post_1.scene',
-        thumbUri:
-          'https://cdn.img.ly/assets/demo/v3/ly.img.template/thumbnails/cesdk_instagram_post_1.jpg'
-      }
-    });
+try {
+  // Create a local asset source for templates
+  engine.asset.addLocalSource('my-templates', undefined, async (asset) => {
+    // Apply the selected template to the current scene
+    await engine.scene.applyTemplateFromURL(asset.meta!.uri as string);
+    return undefined;
+  });
+
+  // Add a template to the source with metadata
+  engine.asset.addAssetToSource('my-templates', {
+    id: 'template-postcard',
+    label: { en: 'Postcard' },
+    meta: {
+      uri: 'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_postcard_1.scene',
+      thumbUri:
+        'https://cdn.img.ly/assets/demo/v3/ly.img.template/thumbnails/cesdk_postcard_1.jpg'
+    }
+  });
+
+  // Add more templates
+  engine.asset.addAssetToSource('my-templates', {
+    id: 'template-business-card',
+    label: { en: 'Business Card' },
+    meta: {
+      uri: 'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_business_card_1.scene',
+      thumbUri:
+        'https://cdn.img.ly/assets/demo/v3/ly.img.template/thumbnails/cesdk_business_card_1.jpg'
+    }
+  });
+
+  engine.asset.addAssetToSource('my-templates', {
+    id: 'template-social-media',
+    label: { en: 'Social Media Post' },
+    meta: {
+      uri: 'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_instagram_post_1.scene',
+      thumbUri:
+        'https://cdn.img.ly/assets/demo/v3/ly.img.template/thumbnails/cesdk_instagram_post_1.jpg'
+    }
+  });
 
-    // Add translation for the library entry
-    cesdk.i18n.setTranslations({
-      en: { 'libraries.my-templates-entry.label': 'My Templates' }
-    });
+  // Load the first template
+  await engine.scene.loadFromURL(
+    'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_postcard_1.scene'
+  );
 
-    // Add the template source to the asset library
-    cesdk.ui.addAssetLibraryEntry({
-      id: 'my-templates-entry',
-      sourceIds: ['my-templates'],
-      previewLength: 3,
-      previewBackgroundType: 'cover',
-      gridBackgroundType: 'cover',
-      gridColumns: 2,
-      cardLabelPosition: () => 'below'
-    });
+  // Ask user how to save the template
+  console.log('\nHow would you like to save the template?');
+  console.log('1. String format (lightweight, references remote assets)');
+  console.log('2. Archive format (self-contained with bundled assets)');
+  console.log('3. Cancel');
 
-    // Add template library to the dock
-    cesdk.ui.setComponentOrder({ in: 'ly.img.dock' }, [
-      ...cesdk.ui.getComponentOrder({ in: 'ly.img.dock' }),
-      'ly.img.spacer',
-      {
-        id: 'ly.img.assetLibrary.dock',
-        key: 'my-templates-dock',
-        label: 'My Templates',
-        icon: '@imgly/Template',
-        entries: ['my-templates-entry']
-      }
-    ]);
-
-    // Load the first template
-    await engine.scene.loadFromURL(
-      'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_postcard_1.scene'
-    );
-
-    // Set zoom to auto-fit
-    await cesdk.actions.run('zoom.toPage', { autoFit: true });
-
-    // Open the template library panel by default
-    cesdk.ui.openPanel('//ly.img.panel/assetLibrary', {
-      payload: { entries: ['my-templates-entry'] }
-    });
+  const choice = await prompt('\nEnter your choice (1-3): ');
 
-    // Save as string format (lightweight, references remote assets)
+  if (choice === '1') {
+    mkdirSync('output', { recursive: true });
     const templateString = await engine.scene.saveToString();
-    console.log('Template saved as string. Length:', templateString.length);
-
-    // Save as archive format (self-contained with bundled assets)
+    writeFileSync('output/saved-scene.scene', templateString);
+    console.log('Template saved to output/saved-scene.scene');
+  } else if (choice === '2') {
+    mkdirSync('output', { recursive: true });
     const templateBlob = await engine.scene.saveToArchive();
-    console.log('Template saved as archive. Size:', templateBlob.size, 'bytes');
+    const buffer = Buffer.from(await templateBlob.arrayBuffer());
+    writeFileSync('output/saved-scene.zip', buffer);
+    console.log('Template saved to output/saved-scene.zip');
+  } else {
+    console.log('Save operation cancelled.');
+  }
 
-    // List all registered asset sources
-    const sources = engine.asset.findAllSources();
-    console.log('Registered sources:', sources);
+  // List all registered asset sources
+  const sources = engine.asset.findAllSources();
+  console.log('Registered sources:', sources);
 
-    // Notify UI when source contents change
-    engine.asset.assetSourceContentsChanged('my-templates');
+  // Notify that source contents have changed (useful after dynamic updates)
+  engine.asset.assetSourceContentsChanged('my-templates');
 
-    // Query templates from the source
-    const queryResult = await engine.asset.findAssets('my-templates', {
-      page: 0,
-      perPage: 10
-    });
-    console.log('Templates in library:', queryResult.total);
-
-    // Remove a template from the source
-    engine.asset.removeAssetFromSource('my-templates', 'template-social-media');
-    console.log('Removed template-social-media from library');
-
-    cesdk.ui.insertOrderComponent(
-      { in: 'ly.img.navigation.bar', position: 'end' },
-      {
-        id: 'ly.img.actions.navigationBar',
-        children: [
-          'ly.img.saveScene.navigationBar',
-          'ly.img.exportArchive.navigationBar'
-        ]
-      }
-    );
-  }
-}
+  // Query templates from the source
+  const queryResult = await engine.asset.findAssets('my-templates', {
+    page: 0,
+    perPage: 10
+  });
+  console.log('Templates in library:', queryResult.total);
+
+  // Remove a template from the source
+  engine.asset.removeAssetFromSource('my-templates', 'template-social-media');
+  console.log('Removed template-social-media from library');
 
-export default Example;
+  console.log('Template library operations completed successfully');
+} finally {
+  // Always dispose the engine to free resources
+  engine.dispose();
+}
 ```
 
-This guide covers how to save scenes as templates, create a template asset source, and add templates with metadata.
+This guide covers how to save scenes as templates, create a template asset source, add templates with metadata, and manage templates in headless server environments.
 
 ## Saving Templates
 
-Scenes can be exported in two formats for use as templates.
+Scenes can be exported in two formats for use as templates:
 
-### String Format
+- **String format**: Use `engine.scene.saveToString()` to serialize the scene to a base64 string. This lightweight format references remote assets by URL and is ideal for templates where assets are hosted on a CDN.
 
-Use `engine.scene.saveToString()` to serialize the scene to a base64 string. This lightweight format references remote assets by URL and is ideal for templates where assets are hosted on a CDN.
-
-```typescript highlight=highlight-save-string
-// Save as string format (lightweight, references remote assets)
-const templateString = await engine.scene.saveToString();
-console.log('Template saved as string. Length:', templateString.length);
-```
+- **Archive format**: Use `engine.scene.saveToArchive()` to bundle all assets together. This returns a Blob containing a self-contained template, making it portable without external dependencies.
 
-### Archive Format
+```typescript highlight=highlight-save-template
+  // Ask user how to save the template
+  console.log('\nHow would you like to save the template?');
+  console.log('1. String format (lightweight, references remote assets)');
+  console.log('2. Archive format (self-contained with bundled assets)');
+  console.log('3. Cancel');
 
-For self-contained templates that bundle all assets, use `engine.scene.saveToArchive()`. This returns a Blob containing all assets bundled together, making templates portable without external dependencies.
+  const choice = await prompt('\nEnter your choice (1-3): ');
 
-```typescript highlight=highlight-save-archive
-// Save as archive format (self-contained with bundled assets)
-const templateBlob = await engine.scene.saveToArchive();
-console.log('Template saved as archive. Size:', templateBlob.size, 'bytes');
+  if (choice === '1') {
+    mkdirSync('output', { recursive: true });
+    const templateString = await engine.scene.saveToString();
+    writeFileSync('output/saved-scene.scene', templateString);
+    console.log('Template saved to output/saved-scene.scene');
+  } else if (choice === '2') {
+    mkdirSync('output', { recursive: true });
+    const templateBlob = await engine.scene.saveToArchive();
+    const buffer = Buffer.from(await templateBlob.arrayBuffer());
+    writeFileSync('output/saved-scene.zip', buffer);
+    console.log('Template saved to output/saved-scene.zip');
+  } else {
+    console.log('Save operation cancelled.');
+  }
 ```
 
 ## Creating a Template Asset Source
@@ -207,8 +189,6 @@ Register a local asset source using `engine.asset.addLocalSource()` with an ID a
 engine.asset.addLocalSource('my-templates', undefined, async (asset) => {
   // Apply the selected template to the current scene
   await engine.scene.applyTemplateFromURL(asset.meta!.uri as string);
-  // Set zoom to auto-fit after applying template
-  await cesdk.actions.run('zoom.toPage', { autoFit: true });
   return undefined;
 });
 ```
@@ -236,62 +216,72 @@ Each template asset requires:
 
 - `id` - Unique identifier for the template
 - `label` - Localized display name shown in the template library
-- `meta.uri` - URL to the `.scene` file that will be loaded when the template is selected
-- `meta.thumbUri` - URL to a preview image displayed in the template library grid
+- `meta.uri` - URL to the `.scene` file that will be loaded when the template is applied
+- `meta.thumbUri` - URL to a preview image for client-side display
 
 ## Managing Templates
 
 After the initial setup, you can manage templates programmatically.
 
 ```typescript highlight=highlight-manage-templates
-// List all registered asset sources
-const sources = engine.asset.findAllSources();
-console.log('Registered sources:', sources);
+  // List all registered asset sources
+  const sources = engine.asset.findAllSources();
+  console.log('Registered sources:', sources);
+
+  // Notify that source contents have changed (useful after dynamic updates)
+  engine.asset.assetSourceContentsChanged('my-templates');
+
+  // Query templates from the source
+  const queryResult = await engine.asset.findAssets('my-templates', {
+    page: 0,
+    perPage: 10
+  });
+  console.log('Templates in library:', queryResult.total);
+
+  // Remove a template from the source
+  engine.asset.removeAssetFromSource('my-templates', 'template-social-media');
+  console.log('Removed template-social-media from library');
+```
 
-// Notify UI when source contents change
-engine.asset.assetSourceContentsChanged('my-templates');
+Use `engine.asset.findAllSources()` to list registered sources. Query templates with `engine.asset.findAssets()` to retrieve template metadata. When you add or remove templates from a source, call `engine.asset.assetSourceContentsChanged()` to notify any connected clients. To remove a template, use `engine.asset.removeAssetFromSource()`.
 
-// Query templates from the source
-const queryResult = await engine.asset.findAssets('my-templates', {
-  page: 0,
-  perPage: 10
-});
-console.log('Templates in library:', queryResult.total);
+## Cleanup
 
-// Remove a template from the source
-engine.asset.removeAssetFromSource('my-templates', 'template-social-media');
-console.log('Removed template-social-media from library');
-```
+Always dispose the engine when finished to free system resources.
 
-Use `engine.asset.findAllSources()` to list registered sources. When you add or remove templates from a source, call `engine.asset.assetSourceContentsChanged()` to refresh the UI. To remove a template, use `engine.asset.removeAssetFromSource()`.
+```typescript highlight=highlight-cleanup
+// Always dispose the engine to free resources
+engine.dispose();
+```
 
 ## Troubleshooting
 
-| Issue                         | Cause                                        | Solution                                           |
-| ----------------------------- | -------------------------------------------- | -------------------------------------------------- |
-| Templates not appearing in UI | Asset source not added to library entry      | Ensure `sourceIds` includes the template source ID |
-| Template fails to load        | Incorrect URI in asset meta                  | Verify the `uri` points to a valid `.scene` file   |
-| Thumbnails not displaying     | Missing or incorrect `thumbUri`              | Check the thumbnail URL is accessible              |
-| Apply callback not triggered  | `applyAsset` not defined in `addLocalSource` | Provide the callback when creating the source      |
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Template fails to load | Incorrect URI in asset meta | Verify the `uri` points to a valid `.scene` file |
+| Apply callback not triggered | `applyAsset` not defined in `addLocalSource` | Provide the callback when creating the source |
+| Empty query results | Templates not added before querying | Ensure `addAssetToSource` is called before `findAssets` |
 
 ## API Reference
 
-| Method                                      | Description                                          |
-| ------------------------------------------- | ---------------------------------------------------- |
-| `engine.asset.addLocalSource()`             | Register a local asset source with an apply callback |
-| `engine.asset.addAssetToSource()`           | Add an asset to a registered source                  |
-| `engine.asset.removeAssetFromSource()`      | Remove an asset from a source by ID                  |
-| `engine.asset.assetSourceContentsChanged()` | Notify UI that source contents changed               |
-| `engine.scene.saveToString()`               | Serialize scene to base64 string format              |
-| `engine.scene.saveToArchive()`              | Save scene as self-contained archive blob            |
-| `engine.scene.applyTemplateFromURL()`       | Apply a template to the current scene                |
-| `cesdk.ui.addAssetLibraryEntry()`           | Add a library entry to the asset library             |
+| Method | Description |
+| --- | --- |
+| `engine.asset.addLocalSource()` | Register a local asset source with an apply callback |
+| `engine.asset.addAssetToSource()` | Add an asset to a registered source |
+| `engine.asset.removeAssetFromSource()` | Remove an asset from a source by ID |
+| `engine.asset.assetSourceContentsChanged()` | Notify that source contents changed |
+| `engine.scene.saveToString()` | Serialize scene to base64 string format |
+| `engine.scene.saveToArchive()` | Save scene as self-contained archive blob |
+| `engine.scene.applyTemplateFromURL()` | Apply a template to the current scene |
+| `engine.dispose()` | Release engine resources when finished |
+
+
 
 ---
 
 ## 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