@imgly/codesign-mcp 0.1.0

package/assets/docs/guide/use-templates/library.md

@@ -0,0 +1,450 @@
+> 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).
+
+**Navigation:** [Guides](./guides.md) > [Create and Use Templates](./create-templates.md) > [Template Library](./use-templates/library.md)
+
+---
+
+Configure and populate the Template Library in CE.SDK so users can browse and select predefined design templates.
+
+![](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-library-browser)
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-use-templates-library-browser)
+> - [Live demo](https://img.ly/docs/cesdk/examples/guides-use-templates-library-browser/)
+
+Templates in CE.SDK are pre-designed scenes stored as assets within asset sources. They contain complete scene definitions that users can load and customize. The Template Library provides a centralized way to organize, browse, and access these templates through both the built-in UI and programmatic APIs.
+
+```typescript file=@cesdk_web_examples/guides-use-templates-library-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: Template Library
+ *
+ * This example demonstrates how to configure and populate the Template Library:
+ * 1. Creating custom template sources from JSON
+ * 2. Handling template application with addLocalSource callback
+ * 3. Querying and browsing templates programmatically
+ * 4. Managing template sources
+ */
+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');
+    }
+
+    const engine = cesdk.engine;
+
+    // Create a design scene to work with    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());
+
+    await cesdk.actions.run('scene.create', {
+      page: {
+        sourceId: 'ly.img.page.presets',
+        assetId: 'ly.img.page.presets.print.iso.a6.landscape'
+      }
+    });
+
+    // Create a custom template source with an apply callback
+    // The callback handles what happens when a user clicks a template
+    engine.asset.addLocalSource(
+      'my.custom.templates',
+      undefined,
+      async (asset) => {
+        const sceneUri = asset.meta?.uri;
+        const scene = engine.scene.get();
+        if (!sceneUri || scene == null) return undefined;
+
+        const sceneUrl = new URL(sceneUri, window.location.href);
+        await engine.scene.applyTemplateFromURL(sceneUrl.href);
+
+        return scene;
+      }
+    );
+
+    // Add template assets to the source
+    // Each asset needs meta.uri pointing to a .scene file
+    engine.asset.addAssetToSource('my.custom.templates', {
+      id: 'postcard-1',
+      label: { en: 'Postcard Design' },
+      tags: { en: ['postcard', 'card'] },
+      groups: ['cards'],
+      meta: {
+        thumbUri:
+          'https://cdn.img.ly/assets/demo/v3/ly.img.template/thumbnails/cesdk_postcard_1.jpg',
+        uri: 'https://cdn.img.ly/packages/imgly/cesdk-js/latest/assets/templates/cesdk_postcard_1.scene'
+      }
+    });
+
+    engine.asset.addAssetToSource('my.custom.templates', {
+      id: 'postcard-2',
+      label: { en: 'Business Card' },
+      tags: { en: ['business', 'card'] },
+      groups: ['business'],
+      meta: {
+        thumbUri:
+          'https://cdn.img.ly/assets/demo/v3/ly.img.template/thumbnails/cesdk_postcard_2.jpg',
+        uri: 'https://cdn.img.ly/packages/imgly/cesdk-js/latest/assets/templates/cesdk_postcard_2.scene'
+      }
+    });
+
+    // Create an asset library entry for the custom templates
+    cesdk.ui.addAssetLibraryEntry({
+      id: 'custom-templates-entry',
+      sourceIds: ['my.custom.templates'],
+      title: 'Custom Templates',
+      icon: '@imgly/Template',
+      gridColumns: 2,
+      gridItemHeight: 'square'
+    });
+
+    // Configure the dock to show ONLY the custom template library
+    cesdk.ui.setComponentOrder({ in: 'ly.img.dock' }, [
+      {
+        id: 'ly.img.assetLibrary.dock',
+        key: 'custom-templates',
+        icon: '@imgly/Template',
+        label: 'Custom Templates',
+        entries: ['custom-templates-entry']
+      }
+    ]);
+
+    // Open the custom templates panel on startup (same as clicking dock button)
+    cesdk.ui.openPanel('//ly.img.panel/assetLibrary', {
+      payload: {
+        entries: ['custom-templates-entry']
+      }
+    });
+
+    // Query templates with filtering options
+    const queryResult = await engine.asset.findAssets('my.custom.templates', {
+      page: 0,
+      perPage: 20,
+      groups: ['cards']
+    });
+    console.log(
+      'Templates in "cards" group:',
+      queryResult.assets.map((t) => t.id)
+    );
+
+    // Query all templates from custom source
+    const allCustomTemplates = await engine.asset.findAssets(
+      'my.custom.templates',
+      {
+        page: 0,
+        perPage: 100
+      }
+    );
+    console.log('Total custom templates:', allCustomTemplates.total);
+
+    // List all registered asset sources
+    const allSources = engine.asset.findAllSources();
+    const templateSources = allSources.filter(
+      (id) => id.includes('template') || id === 'my.custom.templates'
+    );
+    console.log('Template sources:', templateSources);
+
+    // Get available groups from a source
+    const groups = await engine.asset.getGroups('my.custom.templates');
+    console.log('Available groups:', groups);
+
+    // Subscribe to source changes
+    const unsubscribeAdd = engine.asset.onAssetSourceAdded((sourceId) => {
+      console.log('Asset source added:', sourceId);
+    });
+
+    const unsubscribeRemove = engine.asset.onAssetSourceRemoved((sourceId) => {
+      console.log('Asset source removed:', sourceId);
+    });
+
+    // Clean up subscriptions when done (for demonstration)
+    setTimeout(() => {
+      unsubscribeAdd();
+      unsubscribeRemove();
+    }, 10000);
+
+    console.log('Template Library example loaded successfully!');
+  }
+}
+
+export default Example;
+```
+
+This guide covers how to create custom template sources, handle template application, query templates programmatically, and manage template sources.
+
+## Setup
+
+Before creating custom template sources, load the default asset sources to ensure fonts and other base assets are available. Then create a design scene to work with.
+
+```typescript highlight=highlight-setup
+// Create a design scene to work with    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());
+
+await cesdk.actions.run('scene.create', {
+  page: {
+    sourceId: 'ly.img.page.presets',
+    assetId: 'ly.img.page.presets.print.iso.a6.landscape'
+  }
+});
+```
+
+## Using the Built-in Template UI
+
+The CE.SDK editor UI includes a template panel where users can browse and select templates. The panel displays thumbnails organized by groups, allowing users to filter templates by category.
+
+To access templates in the UI:
+
+1. Open the asset library panel
+2. Navigate to the Templates section
+3. Browse templates with thumbnail previews
+4. Click a template to apply it to the current design
+
+The template panel automatically displays templates from all registered template sources.
+
+## Creating Custom Template Sources
+
+You can create custom template sources to provide your own branded templates. We use `engine.asset.addLocalSource()` to create a source with an apply callback, then `engine.asset.addAssetToSource()` to add template assets.
+
+```typescript highlight=highlight-custom-source
+// Create a custom template source with an apply callback
+// The callback handles what happens when a user clicks a template
+engine.asset.addLocalSource('my.custom.templates', undefined, async (asset) => {
+  const sceneUri = asset.meta?.uri;
+  const scene = engine.scene.get();
+  if (!sceneUri || scene == null) return undefined;
+
+  const sceneUrl = new URL(sceneUri, window.location.href);
+  await engine.scene.applyTemplateFromURL(sceneUrl.href);
+
+  return scene;
+});
+
+// Add template assets to the source
+// Each asset needs meta.uri pointing to a .scene file
+engine.asset.addAssetToSource('my.custom.templates', {
+  id: 'postcard-1',
+  label: { en: 'Postcard Design' },
+  tags: { en: ['postcard', 'card'] },
+  groups: ['cards'],
+  meta: {
+    thumbUri:
+      'https://cdn.img.ly/assets/demo/v3/ly.img.template/thumbnails/cesdk_postcard_1.jpg',
+    uri: 'https://cdn.img.ly/packages/imgly/cesdk-js/latest/assets/templates/cesdk_postcard_1.scene'
+  }
+});
+
+engine.asset.addAssetToSource('my.custom.templates', {
+  id: 'postcard-2',
+  label: { en: 'Business Card' },
+  tags: { en: ['business', 'card'] },
+  groups: ['business'],
+  meta: {
+    thumbUri:
+      'https://cdn.img.ly/assets/demo/v3/ly.img.template/thumbnails/cesdk_postcard_2.jpg',
+    uri: 'https://cdn.img.ly/packages/imgly/cesdk-js/latest/assets/templates/cesdk_postcard_2.scene'
+  }
+});
+```
+
+The `addLocalSource()` method creates the source and registers a callback that handles template application when users click a template. The callback:
+
+1. Extracts the scene URI from `asset.meta.uri`
+2. Resolves the URI to an absolute URL
+3. Applies the template using `engine.scene.applyTemplateFromURL()`
+4. Returns the scene ID to indicate successful application
+
+Each template asset added with `addAssetToSource()` can include:
+
+- `id` - Unique identifier for the template
+- `label` - Localized display name (e.g., `{ en: 'Business Card' }`)
+- `tags` - Searchable keywords for filtering
+- `groups` - Categories for organization
+- `meta.uri` - URL to the `.scene` file (required for template application)
+- `meta.thumbUri` - Thumbnail image URL
+
+### From Remote URI
+
+For production use, you can load templates from a hosted JSON file using `engine.asset.addLocalAssetSourceFromJSONURI()`. The parent directory of the JSON URI becomes the base path for resolving relative URLs within the JSON.
+
+```typescript
+const sourceId = await engine.asset.addLocalAssetSourceFromJSONURI(
+  'https://cdn.example.com/templates/content.json'
+);
+```
+
+## Querying Templates Programmatically
+
+We use `engine.asset.findAssets()` to search and retrieve templates from a source. You can query by groups, tags, or search text to find specific templates.
+
+```typescript highlight=highlight-query-templates
+// Query templates with filtering options
+const queryResult = await engine.asset.findAssets('my.custom.templates', {
+  page: 0,
+  perPage: 20,
+  groups: ['cards']
+});
+console.log(
+  'Templates in "cards" group:',
+  queryResult.assets.map((t) => t.id)
+);
+
+// Query all templates from custom source
+const allCustomTemplates = await engine.asset.findAssets(
+  'my.custom.templates',
+  {
+    page: 0,
+    perPage: 100
+  }
+);
+console.log('Total custom templates:', allCustomTemplates.total);
+```
+
+The query options include:
+
+- `page` and `perPage` - Pagination controls
+- `groups` - Filter by group names (e.g., `['business', 'cards']`)
+- `tags` - Filter by tags
+- `query` - Text search across labels and tags
+
+The result object contains:
+
+- `assets` - Array of template assets matching the query
+- `total` - Total number of matching templates
+- `currentPage` - Current page index
+- `nextPage` - Next page index (if available)
+
+## Managing Template Sources
+
+CE.SDK provides APIs to manage the lifecycle of template sources, including listing, monitoring, and removing sources.
+
+```typescript highlight=highlight-manage-sources
+// List all registered asset sources
+const allSources = engine.asset.findAllSources();
+const templateSources = allSources.filter(
+  (id) => id.includes('template') || id === 'my.custom.templates'
+);
+console.log('Template sources:', templateSources);
+
+// Get available groups from a source
+const groups = await engine.asset.getGroups('my.custom.templates');
+console.log('Available groups:', groups);
+
+// Subscribe to source changes
+const unsubscribeAdd = engine.asset.onAssetSourceAdded((sourceId) => {
+  console.log('Asset source added:', sourceId);
+});
+
+const unsubscribeRemove = engine.asset.onAssetSourceRemoved((sourceId) => {
+  console.log('Asset source removed:', sourceId);
+});
+
+// Clean up subscriptions when done (for demonstration)
+setTimeout(() => {
+  unsubscribeAdd();
+  unsubscribeRemove();
+}, 10000);
+```
+
+Key management methods:
+
+- `engine.asset.findAllSources()` - Lists all registered asset source IDs
+- `engine.asset.getGroups(sourceId)` - Gets available groups from a source
+- `engine.asset.removeSource(sourceId)` - Removes an asset source
+- `engine.asset.onAssetSourceAdded(callback)` - Subscribe to source additions
+- `engine.asset.onAssetSourceRemoved(callback)` - Subscribe to source removals
+
+## Troubleshooting
+
+Common issues when working with the Template Library:
+
+- **Templates not appearing in UI**: Verify the source is registered by checking `engine.asset.findAllSources()`. Ensure the source ID matches what you expect.
+
+- **Thumbnails not loading**: Check that `thumbUri` values are accessible URLs with proper CORS headers enabled.
+
+- **Scene files not loading**: Ensure `meta.uri` values point to valid `.scene` files that are accessible from the browser.
+
+---
+
+## More Resources
+
+- **[Vanilla JS/TS Documentation Index](https://img.ly/docs/cesdk/js.md)** - Browse all Vanilla JS/TS 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

package/assets/docs/guide/use-templates/overview.md

@@ -0,0 +1,20 @@
+> 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).
+
+**Navigation:** [Guides](./guides.md) > [Create and Use Templates](./create-templates.md) > [Use Templates Overview](./use-templates/overview.md)
+
+---
+
+## 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
+- **[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