@imgly/codesign-mcp 0.1.5 → 0.1.7

package/assets/docs/guide/user-interface/overview.md

@@ -1,167 +0,0 @@
-> 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) > [User Interface](./user-interface.md) > [Overview](./user-interface/overview.md)
-
----
-
-The CreativeEditor SDK (CE.SDK) includes a powerful, fully-integrated user interface that enables your users to create, edit, and export stunning designs—without requiring you to build a UI from scratch. Whether you're launching a full-featured editor or embedding design tools into a larger application, CE.SDK provides everything you need to get started quickly.
-
-Out of the box, the UI is professional, responsive, and production-ready. But it’s not a one-size-fits-all solution. You can fully **customize**, **extend**, or even **replace the UI entirely** with your own interface built on top of the CE.SDK engine. The SDK is designed to be as flexible as your product demands.
-
-[Launch Web Demo](https://img.ly/showcases/cesdk)
-
-[Get Started](./get-started/overview.md)
-
-## Architecture
-
-CE.SDK’s UI is modular, declaratively configured, and tightly integrated with the core engine. At a high level, it consists of:
-
-- **Core Engine APIs** — The underlying logic for manipulating scenes, blocks, assets, and rendering
-- **UI Components** — Panels, bars, buttons, and menus that interact with the engine through configuration and callbacks
-- **Event System** — A reactive layer that tracks user input, selections, and state transitions
-
-This separation of concerns allows you to extend, replace, or completely rebuild the UI without impacting the rendering and scene logic handled by the engine.
-
-## Default UI
-
-When you initialize CE.SDK in your project, it includes a preconfigured interface with all the essential components you need:
-
-![Locations of the web editor](https://img.ly/docs/cesdk/./assets/Editor_locations.png)
-
-### Canvas
-
-The canvas is the main area of the editor where the user interacts with design content. This part is completely controlled by the Creative Engine. It is basically the core of CE.SDK and the web editor is build around it. This is also the part you need to interact with if you want to create a complete custom UI and not use the web editor.
-
-### Dock
-
-The dock is the main entry point for user interactions not directly related to the currently selected block. It occupies a prominent place in the editor and is primarily, though not exclusively, used to open panels with asset libraries. Therefore, the default and recommended position of the asset library panel is on the side of the dock. However, depending on the use case, it might be beneficial to add other buttons and functionalities (even block-specific ones) to highlight them due to the prominence of the dock.
-
-![Dock](https://img.ly/docs/cesdk/./assets/dock.png)
-
-### Canvas Menu
-
-For every selected block on the canvas, the canvas menu appears either above or below the frame of the selected block. This menu provides the most important block-specific actions and settings, ensuring they are immediately visible to the user. It is recommended to add as few elements as possible to the canvas menu to keep it clean and focused.
-
-![Cavnas Menu](https://img.ly/docs/cesdk/./assets/canvas-menu.png)
-
-### Inspector Bar
-
-The main location for block-specific functionality is the inspector bar. Any action or setting available to the user for the currently selected block that does not appear in the canvas menu should be added here.
-
-![Inspector Bar](https://img.ly/docs/cesdk/./assets/inspector-bar.png)
-
-### Navigation Bar
-
-Actions that affect browser navigation (e.g. going back or closing the editor), have global effects on the scene (e.g. undo/redo and zoom), or process the scene in some way (e.g. saving and exporting) should be placed in the navigation bar.
-
-![Navigation Bar](https://img.ly/docs/cesdk/./assets/navigation-bar.png)
-
-### Canvas Bar
-
-The canvas bar is intended for actions that affect the canvas or scene as a whole. Undo/redo or zoom controls can be placed here as an alternative to the navigation bar.
-
-![Canvas Bar](https://img.ly/docs/cesdk/./assets/canvas-bar.png)
-
-Each of these elements can be customized, removed, rearranged, or extended using the SDK’s UI configuration and plugin APIs.
-
-### Panel
-
-Panels are flexible UI containers designed to support more advanced and interactive functionality within the editor. Unlike quick actions, which focus on single-click operations, panels give you the space and flexibility to build full user interfaces around complex workflows. You can use panels to:
-
-#### Walk Users Through Workflows
-
-Use panels to guide users step by step through a process—whether it’s customizing a template, setting up a product variation, or configuring export settings. Panels help ensure clarity and structure in more involved tasks.
-
-#### Connect with External APIs or AI Services
-
-While quick actions are great for simple integrations, some features—like AI-powered design generation or third-party content retrieval—require user input or multi-step interaction. Panels let you build richer interfaces that connect with external services and present results directly in the editor.
-
-#### Gather Detailed User Input
-
-Panels are ideal for collecting structured input, such as text, color choices, image uploads, or toggle options. You can use them to power advanced use cases like custom theming, batch updates, or conditional logic based on user selections.
-
-## Customizing the UI
-
-You can tailor the editor’s interface to match your brand and use case. CE.SDK provides flexible APIs and configuration options for customizing:
-
-### Appearance
-
-- Change the UI theme or colors
-- Use custom fonts and icons
-- Localize labels and messages
-
-### Layout
-
-- Show or hide components based on context
-- Reorder buttons or entire sections
-- Rearrange dock elements or panel positions
-
-### Behavior
-
-- Enable or disable specific features
-- Apply feature-based logic (e.g., show certain tools only for certain block types)
-
-## Extending the UI
-
-In addition to customizing what’s already there, you can **add entirely new functionality** to the UI:
-
-- **Quick Actions** — One-click tools that perform fast edits (e.g., remove background)
-- **Custom Buttons** — Add buttons to the dock, canvas menu, or canvas bar
-- **Custom Panels** — Create complex UIs to support advanced workflows like export wizards or AI tools
-- **Third-Party Integrations** — Connect with external APIs, such as QR generators or content management systems
-
-Use the **Plugin API** to encapsulate these enhancements into portable, declarative extensions. These plugins can be dynamically loaded, reused across projects, and even distributed.
-
-> Tip: You don’t need to use the Plugin API to modify the UI—but it’s the best approach when you want to encapsulate logic, reuse it, or offer it to others.
-
-## Building Your Own UI
-
-While CE.SDK includes a fully-featured UI by default, you're not locked into it. Many developers choose to **build a completely custom UI** on top of the CE.SDK engine. This approach gives you full control over layout, interaction patterns, and visual design.
-
-When building your own UI, you interact directly with:
-
-- **The CE.SDK Engine** — Use the core APIs to manage scenes, create or modify blocks, control playback, and export content
-- **Canvas Rendering** — Render and manipulate the canvas area within your application shell
-- **State and Events** — Observe selections, listen for changes, and update your UI reactively
-
-This approach is ideal when:
-
-- You need tight integration with a larger application or workflow
-- You want to match a highly specific design system
-- You're building for a unique form factor or device
-- You need to simplify the UI dramatically for a focused use case
-
-## Integrating with Custom Workflows
-
-The CE.SDK UI isn’t a closed system—it plays well with your broader application logic and workflows.
-
-You can:
-
-- **Sync programmatic state** — Reflect external data (e.g., product names or image URLs) directly in the editor
-- **Control headless rendering** — Run the engine without the UI for automation or server-side rendering
-- **Trigger external logic** — Connect UI actions (like export) to your own backend services
-
-The UI components can be programmatically configured, replaced, or completely bypassed depending on your needs. Whether you’re creating a collaborative editor, running batch jobs, or embedding CE.SDK in a no-code platform, you have full control over how the UI interacts with your app.
-
-## Small Viewports
-
-By default, CreativeEditor SDK is configured to use an optimized layout for small viewports.
-
-The UI of the CreativeEditor SDK seamlessly adjusts to the available space, much like any other modern web application, without sacrificing functionality. Moreover, it provides a certain degree of customizability, allowing you to tailor the behavior of the UI to your specific needs.
-
-This layout changes the UI to:
-
-- Render the dock on the bottom
-- Open all panels from the bottom, taking up the bottom half of the screen
-- Use the [large UI scaling](./user-interface/appearance/theming.md)
-
-All configuration options related to the panel layout are ignored in favor of the layout optimization for small viewports as described above.
-
----
-
-## 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/user-interface/ui-extensions/add-custom-feature.md

@@ -1,411 +0,0 @@
-> 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) > [User Interface](./user-interface.md) > [UI Extensions](./user-interface/ui-extensions.md) > [Add a Custom Feature](./user-interface/ui-extensions/add-custom-feature.md)
-
----
-
-Bundle custom functionality into reusable plugins for CE.SDK.
-
-![Add a Custom Feature example showing CE.SDK with a custom canvas menu button](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-user-interface-ui-extensions-add-custom-feature-browser)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-user-interface-ui-extensions-add-custom-feature-browser)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-user-interface-ui-extensions-add-custom-feature-browser/)
-
-Plugins provide a structured way to package UI components, event handlers, actions, and configuration into a single unit. While you can customize CE.SDK without plugins by calling APIs directly after initialization, plugins help organize code for sharing across projects or publishing for others to use.
-
-> **Tip:** **Do I Need to Create a Plugin to Customize the Editor?\*\***Short answer: No.\*\* Keep in mind that you neither have to create a plugin to customize the CE.SDK, nor do you have to publish it. Feel free to use all APIs directly after initializing the CE.SDK. This is completely fine. Even if you decide to bundle everything into a plugin, you can still keep it private and use it only for your own integration.
-
-```typescript file=@cesdk_web_examples/guides-user-interface-ui-extensions-add-custom-feature-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';
-
-interface CustomFeaturePluginConfig {
-  ui?: {
-    locations?: ('canvasMenu' | 'inspectorBar')[];
-  };
-}
-
-const DEFAULT_CONFIG: CustomFeaturePluginConfig = {
-  ui: {
-    locations: []
-  }
-};
-
-const CustomFeaturePlugin = (
-  userConfig: CustomFeaturePluginConfig = {}
-): EditorPlugin => {
-  // Merge user config with defaults
-  const config: CustomFeaturePluginConfig = {
-    ...DEFAULT_CONFIG,
-    ui: {
-      ...DEFAULT_CONFIG.ui,
-      ...userConfig.ui
-    }
-  };
-
-  return {
-    name: 'CustomFeaturePlugin',
-    version: '1.0.0',
-
-    async initialize({ cesdk, engine }: EditorPluginContext): Promise<void> {
-      if (!cesdk) {
-        console.log('Plugin initialized in engine-only mode');
-        return;
-      }
-
-      console.log('CustomFeaturePlugin initialized');
-
-      // Load default assets and create a design scene
-      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: 800, height: 600, unit: 'Pixel' }
-      });
-
-      const page = engine.block.findByType('page')[0];
-      if (page) {
-        // Create gradient background fill
-        const gradientFill = engine.block.createFill('gradient/linear');
-        engine.block.setGradientColorStops(
-          gradientFill,
-          'fill/gradient/colors',
-          [
-            { color: { r: 0.1, g: 0.1, b: 0.2, a: 1.0 }, stop: 0 },
-            { color: { r: 0.3, g: 0.2, b: 0.5, a: 1.0 }, stop: 0.5 },
-            { color: { r: 0.1, g: 0.3, b: 0.4, a: 1.0 }, stop: 1 }
-          ]
-        );
-        engine.block.setFloat(
-          gradientFill,
-          'fill/gradient/linear/startPointX',
-          0
-        );
-        engine.block.setFloat(
-          gradientFill,
-          'fill/gradient/linear/startPointY',
-          0
-        );
-        engine.block.setFloat(
-          gradientFill,
-          'fill/gradient/linear/endPointX',
-          1
-        );
-        engine.block.setFloat(
-          gradientFill,
-          'fill/gradient/linear/endPointY',
-          1
-        );
-        engine.block.setFill(page, gradientFill);
-
-        // Create centered "IMG.LY" text
-        const textBlock = engine.block.create('text');
-        engine.block.replaceText(textBlock, 'IMG.LY');
-        engine.block.setTextFontSize(textBlock, 80);
-        engine.block.setTextColor(textBlock, {
-          r: 1.0,
-          g: 1.0,
-          b: 1.0,
-          a: 1.0
-        });
-        engine.block.setWidthMode(textBlock, 'Auto');
-        engine.block.setHeightMode(textBlock, 'Auto');
-        engine.block.appendChild(page, textBlock);
-
-        // Center the text on the page
-        const pageWidth = engine.block.getWidth(page);
-        const pageHeight = engine.block.getHeight(page);
-        const textWidth = engine.block.getFrameWidth(textBlock);
-        const textHeight = engine.block.getFrameHeight(textBlock);
-        engine.block.setPositionX(textBlock, (pageWidth - textWidth) / 2);
-        engine.block.setPositionY(textBlock, (pageHeight - textHeight) / 2);
-
-        // Select the text block to show the canvas menu
-        engine.block.select(textBlock);
-
-        engine.block
-          .findAllSelected()
-          .forEach((b) => engine.block.setSelected(b, false));
-        const currentPage = engine.scene.getCurrentPage();
-        if (currentPage !== null) {
-          engine.block.setSelected(currentPage, true);
-        }
-      }
-
-      // Register a custom button component
-      cesdk.ui.registerComponent(
-        'customFeaturePlugin.action.canvasMenu',
-        (context) => {
-          context.builder.Button('custom-action', {
-            label: 'Custom Action',
-            icon: '@imgly/Apps',
-            onClick: () => {
-              cesdk.ui.showNotification({
-                message: 'Custom action triggered!',
-                type: 'success',
-                duration: 'short'
-              });
-              console.log('Custom action executed');
-            }
-          });
-        }
-      );
-
-      // Only add to canvas menu if configured
-      const locations = config.ui?.locations ?? [];
-      if (locations.includes('canvasMenu')) {
-        const currentOrder = cesdk.ui.getComponentOrder({
-          in: 'ly.img.canvas.menu'
-        });
-        cesdk.ui.setComponentOrder({ in: 'ly.img.canvas.menu' }, [
-          'customFeaturePlugin.action.canvasMenu',
-          ...currentOrder
-        ]);
-        console.log('Custom action added to canvas menu');
-      }
-
-      // Subscribe to block events for demonstration
-      const unsubscribe = engine.event.subscribe([], (events) => {
-        events.forEach((event) => {
-          if (event.type === 'Created') {
-            console.log(`Block created: ${event.block}`);
-          }
-        });
-      });
-
-      // Store unsubscribe for potential cleanup
-      (window as any).unsubscribeCustomFeature = unsubscribe;
-    }
-  };
-};
-
-export default CustomFeaturePlugin;
-```
-
-This guide covers creating plugins with the factory function pattern, registering custom components during initialization, and letting integrators control where your plugin's UI elements appear.
-
-## Plugin Types
-
-Two plugin interfaces exist: `EditorPlugin` for full editor integration and `EnginePlugin` for headless engine use. Editor plugins receive both `cesdk` and `engine` in their context; engine plugins receive only `engine`. Structure your plugins to handle both contexts for maximum flexibility.
-
-## Creating a Plugin
-
-### The Plugin Interface
-
-Plugins implement an interface with `name`, `version`, and `initialize` properties. The `initialize` method executes when you call `cesdk.addPlugin()` or `engine.addPlugin()`. Return a promise from `initialize` for async setup operations.
-
-```typescript highlight=highlight-factory-function
-const CustomFeaturePlugin = (
-  userConfig: CustomFeaturePluginConfig = {}
-): EditorPlugin => {
-  // Merge user config with defaults
-  const config: CustomFeaturePluginConfig = {
-    ...DEFAULT_CONFIG,
-    ui: {
-      ...DEFAULT_CONFIG.ui,
-      ...userConfig.ui
-    }
-  };
-
-  return {
-    name: 'CustomFeaturePlugin',
-    version: '1.0.0',
-
-    async initialize({ cesdk, engine }: EditorPluginContext): Promise<void> {
-```
-
-### Adding a Plugin to the Editor
-
-Call `cesdk.addPlugin()` after creating the editor instance. Pass a plugin object directly or call a factory function that returns one.
-
-```typescript
-// Add the plugin with configuration
-await cesdk.addPlugin(
-  CustomFeaturePlugin({
-    ui: {
-      locations: ['canvasMenu']
-    }
-  })
-);
-```
-
-## Making Plugins Configurable
-
-### The Factory Function Pattern
-
-Export a function that returns the plugin object rather than the object directly. This allows integrators to pass configuration options. Even without current configuration needs, this pattern prevents breaking changes when adding options later.
-
-```typescript highlight=highlight-plugin-config
-interface CustomFeaturePluginConfig {
-  ui?: {
-    locations?: ('canvasMenu' | 'inspectorBar')[];
-  };
-}
-
-const DEFAULT_CONFIG: CustomFeaturePluginConfig = {
-  ui: {
-    locations: []
-  }
-};
-```
-
-The factory function merges user-provided configuration with sensible defaults. Document available options so integrators understand how to customize behavior.
-
-## Plugin Initialization
-
-### Registering Components
-
-Use `cesdk.ui.registerComponent()` to add custom UI components. Components become available for placement in canvas menus, inspector bars, and other locations. The builder API creates buttons, inputs, and other controls.
-
-```typescript highlight=highlight-register-component
-// Register a custom button component
-cesdk.ui.registerComponent(
-  'customFeaturePlugin.action.canvasMenu',
-  (context) => {
-    context.builder.Button('custom-action', {
-      label: 'Custom Action',
-      icon: '@imgly/Apps',
-      onClick: () => {
-        cesdk.ui.showNotification({
-          message: 'Custom action triggered!',
-          type: 'success',
-          duration: 'short'
-        });
-        console.log('Custom action executed');
-      }
-    });
-  }
-);
-```
-
-### Subscribing to Events
-
-Use `engine.event.subscribe()` to react to block changes. Store the unsubscribe function for cleanup when needed. Event subscriptions set up reactive behavior without executing immediate actions.
-
-```typescript highlight=highlight-subscribe-events
-// Subscribe to block events for demonstration
-const unsubscribe = engine.event.subscribe([], (events) => {
-  events.forEach((event) => {
-    if (event.type === 'Created') {
-      console.log(`Block created: ${event.block}`);
-    }
-  });
-});
-
-// Store unsubscribe for potential cleanup
-(window as any).unsubscribeCustomFeature = unsubscribe;
-```
-
-## Controlling Component Placement
-
-Offer a configuration option for default locations. Check this option during initialization and only modify order when explicitly requested by the integrator.
-
-```typescript highlight=highlight-optional-placement
-// Only add to canvas menu if configured
-const locations = config.ui?.locations ?? [];
-if (locations.includes('canvasMenu')) {
-  const currentOrder = cesdk.ui.getComponentOrder({
-    in: 'ly.img.canvas.menu'
-  });
-  cesdk.ui.setComponentOrder({ in: 'ly.img.canvas.menu' }, [
-    'customFeaturePlugin.action.canvasMenu',
-    ...currentOrder
-  ]);
-  console.log('Custom action added to canvas menu');
-}
-```
-
-This approach lets integrators decide whether to use default placement or handle positioning themselves.
-
-## Troubleshooting
-
-### Plugin Not Initializing
-
-Verify `addPlugin()` is called after the editor or engine is created. Check for errors thrown during `initialize` - exceptions prevent plugin setup. Ensure async `initialize` functions return promises properly.
-
-### Components Not Appearing
-
-Confirm components are registered with unique IDs. Check that component IDs match exactly when setting order. Verify the location is configured in the plugin options if using optional placement.
-
-### Context Arguments Missing
-
-For editor plugins, `cesdk` is undefined when added via `engine.addPlugin()`. Always check if `cesdk` exists before calling editor-specific APIs. Structure code to work with engine-only contexts when needed.
-
-### Configuration Not Applied
-
-Verify the factory function pattern is used and called with parentheses: `MyPlugin()` not `MyPlugin`. Check that configuration is passed to the factory: `MyPlugin({ option: value })`.
-
-## API Reference
-
-| Method                                                            | Purpose                                   |
-| ----------------------------------------------------------------- | ----------------------------------------- |
-| `cesdk.addPlugin()`                                               | Add and initialize a plugin to the editor |
-| `engine.addPlugin()`                                              | Add and initialize a plugin to the engine |
-| `cesdk.ui.registerComponent()`                                    | Register a custom UI component            |
-| `cesdk.ui.setComponentOrder({ in: 'ly.img.canvas.menu' }, order)` | Set component order in canvas menu        |
-| `cesdk.ui.getComponentOrder({ in: 'ly.img.canvas.menu' })`        | Get current canvas menu component order   |
-| `engine.event.subscribe()`                                        | Subscribe to block lifecycle events       |
-
-## Next Steps
-
-- [Register New Component](./user-interface/ui-extensions/register-new-component.md) — Learn component registration in detail
-- [Customize UI Behavior](./user-interface/ui-extensions/customize-behaviour.md) — React to events and control UI programmatically
-- [Create Custom Panel](./user-interface/ui-extensions/create-custom-panel.md) — Build custom panels for your plugin
-- [Disable or Enable Features](./user-interface/customization/disable-or-enable.md) — Control feature availability
-
----
-
-## 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