@imgly/codesign-mcp 0.1.0

package/assets/docs/guide/to-v1-72.md

@@ -0,0 +1,193 @@
+> 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:** [Upgrading](./upgrade.md) > [To v1.72](./to-v1-72.md)
+
+---
+
+Version 1.72 deprecates scene mode. Previously, scenes were either `'Design'` or `'Video'`, and the mode restricted which engine features were available. Starting with this version, there is a single scene type that supports all features. Mode is legacy metadata that no longer affects engine behavior.
+
+This guide covers how to migrate to the new model and, if you cannot migrate yet, how to keep using legacy mode.
+
+> **Caution:** **Cross-platform users:** Mobile SDKs (iOS, Android) do not yet support scenes without a mode. If your application creates scenes on Web and loads them on mobile, you **must** set an explicit mode. See [How to Keep Using Legacy Mode](#how-to-keep-using-legacy-mode) below.
+
+## What Changed
+
+- **Scene mode is deprecated.** The following APIs still work but will be removed in a future version: `engine.scene.getMode()`, `engine.scene.setMode()`, `engine.scene.createVideo()`, `cesdk.createDesignScene()`, `cesdk.createVideoScene()`, and the `mode` option on the `scene.create` action.
+- **New scenes have no mode.** Both the `scene.create` action and `engine.scene.create()` now create scenes without a mode. `engine.scene.getMode()` returns `null` instead of `'Design'`.
+- **The engine no longer restricts features by mode.** Methods that previously threw errors on Design-mode scenes (e.g., `addVideo()`, `getBackgroundTrack()`) now work on every scene.
+- **Reading `scene/mode` via the property system errors on mode-less scenes.** Code that reads `scene/mode` through `engine.block.getEnum(scene, 'scene/mode')` will throw on scenes without a mode. Either remove mode checks entirely (see [Remove Scene Mode Checks](#remove-scene-mode-checks)) or set a mode explicitly (see [How to Keep Using Legacy Mode](#how-to-keep-using-legacy-mode)).
+- **Browser support checks are no longer automatic.** Config plugins that need video decode/encode checks must call `editor.checkBrowserSupport` explicitly.
+
+## How to Migrate
+
+Migrating means embracing the single scene type. You no longer need to think about mode at all.
+
+### Simplify Scene Creation
+
+The `scene.create` action no longer requires a `mode` option. Previously, video editors passed `{ mode: 'Video' }` to get video capabilities. Now every scene has all capabilities by default.
+
+**Before:**
+
+```typescript
+// Editor instance methods
+await cesdk.createDesignScene();
+await cesdk.createVideoScene();
+
+// Editor action with mode
+await cesdk.actions.run('scene.create', { mode: 'Video' });
+
+// Engine API
+const scene = engine.scene.createVideo();
+```
+
+**After:**
+
+```typescript
+// Editor action, no mode needed
+await cesdk.actions.run('scene.create');
+
+// Engine API
+const scene = engine.scene.create();
+```
+
+All of the following are deprecated:
+
+- `cesdk.createDesignScene()` and `cesdk.createVideoScene()`: use the `scene.create` action instead.
+- `engine.scene.createVideo()`: use `engine.scene.create()` instead.
+- The `mode` option on the `scene.create` action: omit it entirely.
+- `engine.scene.setMode()`: only needed if you must maintain legacy mode (see below).
+- `engine.scene.getMode()`: mode no longer determines available features.
+
+### Remove Scene Mode Checks
+
+Since mode no longer affects behavior, any code that branches on `getMode()` to decide which features to enable can be removed. All features are always available.
+
+**Before:**
+
+```typescript
+const mode = engine.scene.getMode();
+if (mode === 'Video') {
+  // enable video features
+}
+```
+
+**After:**
+
+```typescript
+// No check needed. Video features are always available.
+```
+
+### Update Browser Support Checks in Your Config
+
+Browser capability checks (video decode/encode support) no longer run automatically based on scene mode. They are now triggered explicitly via the `editor.checkBrowserSupport` action.
+
+**If you use a starter kit config** (e.g., video editor, advanced video editor): update to the latest version of the config. The v1.72 configs already include the `editor.checkBrowserSupport` call with the appropriate defaults. No changes needed on your end.
+
+**If you have a custom config plugin**, add the `editor.checkBrowserSupport` call to your plugin's `initialize()` method:
+
+```typescript
+async initialize({ cesdk }: EditorPluginContext) {
+  await cesdk.actions.run('editor.checkBrowserSupport', {
+    videoDecode: 'block',
+    videoEncode: 'warn'
+  });
+}
+```
+
+The action accepts an optional parameters object:
+
+| Parameter     | Values    | Description |
+| ------------- | --------- | ----------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `videoDecode` | `'block'` | `'warn'`    | `'ignore'` | How to handle missing video decode support. `'block'` shows an unclosable error dialog. `'warn'` shows a dismissible warning. `'ignore'` skips the check. |
+| `videoEncode` | `'block'` | `'warn'`    | `'ignore'` | How to handle missing video encode support. Same options as above.                                                                                        |
+
+When called without parameters, the action falls back to scene mode-based defaults for backward compatibility:
+
+- **Video mode scenes:** `videoDecode: 'block'`, `videoEncode: 'warn'`
+- **No-mode scenes (null):** all checks ignored
+- **Design mode scenes:** no checks run
+
+### Update TypeScript Types
+
+The return type of `engine.scene.getMode()` changed from `SceneMode` to `SceneMode | null`. If you still reference this API, update your type annotations.
+
+```typescript
+// Before
+const mode: SceneMode = engine.scene.getMode();
+
+// After
+const mode: SceneMode | null = engine.scene.getMode();
+```
+
+## How to Keep Using Legacy Mode
+
+If you cannot fully migrate yet, you can continue using scene mode. The deprecated APIs still work and will remain functional until removed in a future version.
+
+The key change is that scene creation no longer sets a mode automatically. To preserve the old behavior, you need to both set the mode explicitly **and** enable the `useLegacySceneModeChecks` feature flag.
+
+### Enable the Feature Flag
+
+By default, the editor UI treats all scenes as unified and ignores mode when deciding which features to show. To restore the old behavior where the UI gates features based on scene mode (e.g., hiding video export in Design mode or hiding page resize in Video mode), set `useLegacySceneModeChecks` to `true` in your configuration:
+
+```typescript
+CreativeEditorSDK.create(container, {
+  featureFlags: {
+    useLegacySceneModeChecks: true
+  }
+});
+```
+
+Without this flag, calling `setMode()` still stores the mode on the scene, but the editor UI will not restrict any features based on it.
+
+### Cross-Platform Compatibility (Web + Mobile)
+
+> **Caution:** Mobile SDKs (iOS, Android) do not yet support scenes without a mode. If you create scenes on Web and load them on mobile without an explicit mode, mobile SDKs will not be able to handle the scene correctly.
+
+Set the mode explicitly when creating scenes that will be shared with mobile:
+
+```typescript
+// Using the scene.create action
+await cesdk.actions.run('scene.create', { mode: 'Video' }); // or 'Design'
+
+// Using the engine API
+const scene = engine.scene.create();
+engine.scene.setMode('Design'); // or 'Video'
+```
+
+### Keeping Legacy Behavior on Web
+
+If your Web integration relies on the editor UI gating features by mode, enable the `useLegacySceneModeChecks` feature flag (see above) and call `setMode()` after `create()`. The engine itself no longer restricts features by mode, but the editor UI will respect mode when the flag is enabled. Your own code can also still read and branch on `getMode()`.
+
+## Scene File Compatibility
+
+### Loading Old Scenes in v1.72+
+
+Scenes saved with older SDK versions contain an explicit mode (`'Design'` or `'Video'`). When loaded in v1.72+, the mode is **preserved**. `engine.scene.getMode()` returns the original mode. All features work regardless of the loaded mode.
+
+### Loading New Scenes in Older SDKs
+
+Older SDK versions (pre-v1.72) cannot load mode-less scenes. If you need to support older SDK versions, set an explicit mode with `engine.scene.setMode()` before saving. See [How to Keep Using Legacy Mode](#how-to-keep-using-legacy-mode).
+
+### Cross-Platform Compatibility
+
+Mobile SDKs (iOS, Android) do not yet support scenes without a mode. If you share scenes between Web and mobile, always set an explicit mode before saving. See [How to Keep Using Legacy Mode](#how-to-keep-using-legacy-mode).
+
+## Summary
+
+| Change                                       | Impact                                            | Migration                                                                        | Legacy workaround                                                                 |
+| -------------------------------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| Scene mode deprecated                        | Mode no longer affects engine behavior            | Remove mode checks                                                               | Enable `useLegacySceneModeChecks` flag, call `setMode()` or pass `mode` to action |
+| New scenes have no mode                      | `getMode()` returns `null`                        | No action needed                                                                 | Pass `mode` to `scene.create` action                                              |
+| `createVideo()` and `mode` option deprecated | Still work                                        | Use `create()` without `mode`                                                    | Keep using them                                                                   |
+| All features work on every scene             | Methods that threw in Design mode no longer throw | No action needed                                                                 | No action needed                                                                  |
+| Browser support checks need explicit params  | No longer automatic                               | Update starter kit config, or add `editor.checkBrowserSupport` in custom plugins | Call without params for mode-based defaults                                       |
+| Cross-platform scenes                        | Mobile doesn't support mode-less scenes yet       | N/A                                                                              | Always `setMode()` before saving                                                  |
+
+---
+
+## 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/upgrade.md

@@ -0,0 +1,25 @@
+> 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:** [Upgrading](./upgrade.md)
+
+---
+
+---
+
+## Related Pages
+
+- [To v1.10](./to-v1-10.md) - Review breaking changes and migration steps required to upgrade your project to CE.SDK v1.10.
+- [To v1.13](./to-v1-13.md) - Follow version-specific upgrade instructions to migrate from earlier versions to CE.SDK v1.13.
+- [To v1.19](./to-v1-19.md) - Learn what changed in v1.19 and how to update your implementation to stay compatible.
+- [To v1.32](./to-v1-32.md) - Upgrade to CE.SDK v1.32 with guidance on feature changes, removals, and integration adjustments.
+- [To v1.69+](./to-v1-69.md) - Learn how to migrate to CE.SDK v1.69+ with Starter Kits, new asset source plugins, and updated naming conventions.
+- [To v1.72](./to-v1-72.md) - Learn how to migrate to CE.SDK v1.72, which deprecates scene mode in favor of a single scene type with all capabilities.
+
+---
+
+## 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/apply-template.md

@@ -0,0 +1,279 @@
+> 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) > [Apply a Template](./use-templates/apply-template.md)
+
+---
+
+Apply template content to an existing scene while preserving your canvas dimensions and design unit.
+
+> **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-use-templates-apply-template-browser)
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-use-templates-apply-template-browser)
+> - [Live demo](https://img.ly/docs/cesdk/examples/guides-use-templates-apply-template-browser/)
+
+![Apply a Template](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
+
+Unlike loading a scene which replaces everything, applying a template merges template content into your current scene. CE.SDK preserves the current page dimensions and design unit while automatically adjusting template content to fit. This approach is ideal for template switching workflows where users explore different layouts without changing canvas dimensions, or for automation pipelines that standardize output sizes across varying template sources.
+
+```typescript file=@cesdk_web_examples/guides-use-templates-apply-template-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: Apply a Template
+ *
+ * This example demonstrates how to apply template content to an existing scene:
+ * 1. Creating a scene with specific dimensions
+ * 2. Applying a template from a URL while preserving dimensions
+ * 3. Switching between 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());
+
+    await cesdk.actions.run('scene.create', {
+      page: { width: 1080, height: 1920, unit: 'Pixel' }
+    });
+
+    const engine = cesdk.engine;
+    const page = engine.block.findByType('page')[0];
+    if (!page) {
+      throw new Error('No page found');
+    }
+
+    // Set custom page dimensions - these will be preserved when applying templates
+
+    // Apply a template from URL - content adjusts to fit current page dimensions
+    const templateUrl =
+      'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_postcard_1.scene';
+
+    await engine.scene.applyTemplateFromURL(templateUrl);
+
+    // Auto-fit zoom to page
+    await cesdk.actions.run('zoom.toPage', { autoFit: true });
+
+    console.log('Template applied from URL');
+
+    // Verify that page dimensions are preserved after applying template
+    const width = engine.block.getWidth(page);
+    const height = engine.block.getHeight(page);
+    console.log(`Page dimensions preserved: ${width}x${height}`);
+
+    // Demonstrate template switching - apply a different template
+    // The page dimensions remain the same while content changes
+    const alternativeTemplateUrl =
+      'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_postcard_2.scene';
+
+    // Uncomment to switch templates:
+    // await engine.scene.applyTemplateFromURL(alternativeTemplateUrl);
+    // console.log('Switched to alternative template');
+
+    // Store for potential use
+    console.log('Alternative template URL:', alternativeTemplateUrl);
+
+    console.log('Apply template example completed');
+  }
+}
+
+export default Example;
+```
+
+This guide covers how to apply templates from URLs and strings while preserving page dimensions, and how to implement template switching functionality.
+
+## When to Use Apply vs Load
+
+Use `applyTemplateFromURL()` or `applyTemplateFromString()` when you want to:
+
+- **Switch templates**: Let users preview different templates while keeping a consistent canvas size
+- **Standardize output dimensions**: Generate content with fixed sizes (e.g., social media formats, print sizes)
+- **Batch process with templates**: Apply various templates to a pre-configured scene without dimension drift
+
+Use `loadFromString()` or `loadFromURL()` when you need the template's original dimensions.
+
+**Key distinction**: Loading replaces everything; applying preserves dimensions and merges content.
+
+## Apply a Template from URL
+
+We first create a scene with specific dimensions. These dimensions will be preserved when we apply the template.
+
+```typescript highlight=highlight-setup
+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: { width: 1080, height: 1920, unit: 'Pixel' }
+});
+
+const engine = cesdk.engine;
+const page = engine.block.findByType('page')[0];
+if (!page) {
+  throw new Error('No page found');
+}
+
+// Set custom page dimensions - these will be preserved when applying templates
+```
+
+To apply a template from a URL, call `engine.scene.applyTemplateFromURL()` with the template URL. The template content adjusts automatically to fit the current page dimensions.
+
+```typescript highlight=highlight-apply-from-url
+// Apply a template from URL - content adjusts to fit current page dimensions
+const templateUrl =
+  'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_postcard_1.scene';
+
+await engine.scene.applyTemplateFromURL(templateUrl);
+
+// Auto-fit zoom to page
+await cesdk.actions.run('zoom.toPage', { autoFit: true });
+
+console.log('Template applied from URL');
+```
+
+## Verify Preserved Dimensions
+
+After applying the template, the page dimensions remain unchanged. You can verify this by checking the width and height of the page.
+
+```typescript highlight=highlight-verify-dimensions
+// Verify that page dimensions are preserved after applying template
+const width = engine.block.getWidth(page);
+const height = engine.block.getHeight(page);
+console.log(`Page dimensions preserved: ${width}x${height}`);
+```
+
+## Template Switching
+
+You can apply multiple templates to the same scene. Each application replaces the content while preserving the page setup. This enables "preview" functionality where users explore different templates without affecting their canvas dimensions.
+
+```typescript highlight=highlight-template-switching
+// Demonstrate template switching - apply a different template
+// The page dimensions remain the same while content changes
+const alternativeTemplateUrl =
+  'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_postcard_2.scene';
+
+// Uncomment to switch templates:
+// await engine.scene.applyTemplateFromURL(alternativeTemplateUrl);
+// console.log('Switched to alternative template');
+
+// Store for potential use
+console.log('Alternative template URL:', alternativeTemplateUrl);
+```
+
+## Apply a Template from String
+
+For templates stored in databases or received from APIs, use `engine.scene.applyTemplateFromString()` with a base64-encoded scene string:
+
+```typescript
+// Scene string typically retrieved from storage or API
+const templateString = 'UBQ1ewoiZm9ybWF0Ij...';
+
+// Apply template content to current scene
+await engine.scene.applyTemplateFromString(templateString);
+```
+
+## Troubleshooting
+
+### No Scene Loaded
+
+`applyTemplateFromString()` and `applyTemplateFromURL()` require an existing scene. Create one first with `cesdk.actions.run('scene.create')` or `engine.scene.create()`.
+
+### Template URL Not Accessible
+
+Verify CORS configuration allows fetching from the template URL. Check network connectivity and URL validity.
+
+### Content Not Scaling as Expected
+
+Template content scales to fit the current page dimensions. Verify page dimensions are set before applying the template.
+
+## Related Guides
+
+- [Use Templates Programmatically](./use-templates/programmatic.md) — Comprehensive programmatic template workflows
+- [Templates Overview](./use-templates/overview.md) — Understanding templates in CE.SDK
+- [Headless Mode](./concepts/headless-mode/browser.md) — Server-side template processing
+
+---
+
+## 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