@imgly/codesign-mcp 0.1.0

package/assets/docs/guide/user-interface/customization/dock.md

@@ -0,0 +1,399 @@
+> 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) > [Customization](./user-interface/customization.md) > [Dock](./user-interface/customization/dock.md)
+
+---
+
+The dock is a sidebar containing buttons that open asset library panels. You
+can position it on the left, right, or bottom of the editor. By default it
+appears on the left side. This guide covers dock positioning, appearance
+settings, edit mode contexts, and the asset source relationship.
+
+![Dock customization example showing large icons, hidden labels, and a custom settings 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)
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples)
+> - [Live demo](https://img.ly/docs/cesdk/examples/guides-user-interface-customization-dock-browser/)
+
+For adding and configuring dock buttons, see [Add Dock Buttons](./user-interface/customization/quick-start/add-dock-buttons.md). For general component manipulation (reordering, inserting, removing), see the [Component Order API Reference](./user-interface/customization/reference/component-order-api.md).
+
+```typescript file=@cesdk_web_examples/guides-user-interface-customization-dock-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';
+
+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: {
+        sourceId: 'ly.img.page.presets',
+        assetId: 'ly.img.page.presets.print.iso.a6.landscape'
+      }
+    });
+
+    const engine = cesdk.engine;
+    const page = engine.block.findByType('page')[0];
+    const pageWidth = engine.block.getWidth(page);
+    const pageHeight = engine.block.getHeight(page);
+
+    // Create gradient background
+    const gradientFill = engine.block.createFill('gradient/linear');
+    engine.block.setGradientColorStops(gradientFill, 'fill/gradient/colors', [
+      { color: { r: 0.18, g: 0.42, b: 0.71, a: 1 }, stop: 0 },
+      { color: { r: 0.31, g: 0.58, b: 0.8, a: 1 }, stop: 0.5 },
+      { color: { r: 0.13, g: 0.7, b: 0.67, a: 1 }, 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 text
+    const titleText = engine.block.create('text');
+    engine.block.appendChild(page, titleText);
+    engine.block.replaceText(titleText, 'Dock\n\nimg.ly');
+    engine.block.setWidth(titleText, pageWidth);
+    engine.block.setHeightMode(titleText, 'Auto');
+    engine.block.setPositionX(titleText, 0);
+    engine.block.setPositionY(titleText, pageHeight * 0.35);
+    engine.block.setEnum(titleText, 'text/horizontalAlignment', 'Center');
+    engine.block.setFloat(titleText, 'text/fontSize', 24);
+    engine.block.setTextColor(titleText, { r: 1, g: 1, b: 1, a: 1 });
+
+    // Deselect all blocks for clean hero image
+    engine.block
+      .findAllSelected()
+      .forEach((block) => engine.block.setSelected(block, false));
+    engine.block.select(page);
+
+    // Configure dock to use large icons and hide text labels
+    cesdk.engine.editor.setSetting('dock/iconSize', 'large');
+    cesdk.engine.editor.setSetting('dock/hideLabels', true);
+
+    // Set a simplified dock for Text edit mode
+    cesdk.ui.setComponentOrder(
+      { in: 'ly.img.dock', when: { editMode: 'Text' } },
+      [
+        {
+          id: 'ly.img.assetLibrary.dock',
+          key: 'ly.img.text',
+          icon: '@imgly/Text',
+          label: 'libraries.ly.img.text.label',
+          entries: ['ly.img.text']
+        }
+      ]
+    );
+
+    // Add a custom asset source, create an entry for it, and add a dock button
+    // Step 1: Create the asset source (stores/provides assets)
+    cesdk.engine.asset.addLocalSource('my.brand.assets');
+
+    // Step 2: Create an asset library entry (UI representation of the source)
+    cesdk.ui.addAssetLibraryEntry({
+      id: 'my.brand.entry',
+      sourceIds: ['my.brand.assets'],
+      previewLength: 3,
+      gridColumns: 3,
+      gridItemHeight: 'square'
+    });
+
+    // Step 3: Add a dock button that opens the entry
+    cesdk.ui.insertOrderComponent(
+      { in: 'ly.img.dock', position: 'end' },
+      {
+        id: 'ly.img.assetLibrary.dock',
+        key: 'brand',
+        entries: ['my.brand.entry'],
+        label: 'Brand',
+        icon: '@imgly/Favorite'
+      }
+    );
+
+    // Register a custom component and add it to the dock bottom
+    cesdk.ui.registerComponent('my.settings.button', ({ builder }) => {
+      builder.Button('settings', {
+        label: 'Settings',
+        icon: '@imgly/Settings',
+        onClick: () => {
+          cesdk.ui.showNotification({
+            message: 'Settings panel would open here',
+            type: 'info',
+            duration: 'short'
+          });
+        }
+      });
+    });
+
+    cesdk.ui.insertOrderComponent({ in: 'ly.img.dock', position: 'end' }, [
+      'ly.img.spacer',
+      'my.settings.button'
+    ]);
+
+    // Retrieve and log the current dock order for reference
+    const currentOrder = cesdk.ui.getComponentOrder({
+      in: 'ly.img.dock'
+    });
+    console.log('Current dock order:', currentOrder);
+  }
+}
+
+export default Example;
+```
+
+This guide covers dock positioning, configuring dock appearance settings, setting up edit mode-specific layouts, understanding the relationship between dock entries and asset sources, adding custom registered components, and viewing the default component order.
+
+## Dock Position
+
+Use the `at` option in `setComponentOrder` to place the dock on the left, right, or bottom of the editor. When `at` is omitted, `setComponentOrder` targets the `'left'` position.
+
+```typescript
+// Place dock on the right side
+cesdk.ui.setComponentOrder({ in: 'ly.img.dock', at: 'right' }, [
+  'ly.img.assetLibrary.dock'
+]);
+
+// Place dock at the bottom (renders horizontally)
+cesdk.ui.setComponentOrder({ in: 'ly.img.dock', at: 'bottom' }, [
+  'ly.img.assetLibrary.dock'
+]);
+```
+
+You can place dock components at multiple positions simultaneously. Each position renders independently:
+
+```typescript
+// Main dock on the left
+cesdk.ui.setComponentOrder({ in: 'ly.img.dock', at: 'left' }, [
+  'ly.img.assetLibrary.dock'
+]);
+
+// Secondary tools on the right
+cesdk.ui.setComponentOrder({ in: 'ly.img.dock', at: 'right' }, [
+  'my.custom.tool'
+]);
+```
+
+On small viewports, all dock positions automatically collapse into a single horizontal dock at the bottom.
+
+## Show or Hide the Dock
+
+Use the Feature API to control dock visibility:
+
+```typescript
+// Hide the dock
+cesdk.feature.disable('ly.img.dock');
+
+// Show the dock (default)
+cesdk.feature.enable('ly.img.dock');
+```
+
+For more on the Feature API, see [Show/Hide Components](./user-interface/customization/quick-start/show-hide-components.md).
+
+## Dock Appearance Settings
+
+Two editor settings control how dock buttons look. Set `dock/iconSize` to `'large'` for 24px icons or `'normal'` for the default 16px. Set `dock/hideLabels` to `true` to show icons only.. When hidden, labels appear as tooltips on hover.
+
+```typescript highlight=highlight-appearance-settings
+// Configure dock to use large icons and hide text labels
+cesdk.engine.editor.setSetting('dock/iconSize', 'large');
+cesdk.engine.editor.setSetting('dock/hideLabels', true);
+```
+
+| Setting           | Values     | Description                       |
+| ----------------- | ---------- | --------------------------------- | ------------------------------- |
+| `dock/iconSize`   | `'normal'` | `'large'`                         | Button icon size (16px or 24px) |
+| `dock/hideLabels` | `boolean`  | Hide text labels, show icons only |
+
+## Edit Mode Context
+
+The dock supports different component orders for different edit modes. Use the `when` option in `setComponentOrder` to define a layout that activates only in a specific mode. The following example sets a simplified dock that appears only when the user enters Text edit mode.
+
+```typescript highlight=highlight-edit-mode-context
+// Set a simplified dock for Text edit mode
+cesdk.ui.setComponentOrder({ in: 'ly.img.dock', when: { editMode: 'Text' } }, [
+  {
+    id: 'ly.img.assetLibrary.dock',
+    key: 'ly.img.text',
+    icon: '@imgly/Text',
+    label: 'libraries.ly.img.text.label',
+    entries: ['ly.img.text']
+  }
+]);
+```
+
+Available edit modes: `'Transform'` (default), `'Text'`, `'Crop'`, `'Trim'`, or any custom value. All Component Order API methods accept an optional `when` context. See the [Component Order API Reference](./user-interface/customization/reference/component-order-api.md) for details.
+
+## Relationship with Asset Sources
+
+Asset sources, asset library entries, and dock buttons work together in three steps:
+
+1. **Create an asset source** — Register a source with the engine that stores and provides assets
+2. **Create an asset library entry** — Define a UI entry that references the source via `sourceIds`
+3. **Add a dock button** — Insert a button that opens the entry via the `entries` array
+
+```typescript highlight=highlight-asset-source-relationship
+// Add a custom asset source, create an entry for it, and add a dock button
+// Step 1: Create the asset source (stores/provides assets)
+cesdk.engine.asset.addLocalSource('my.brand.assets');
+
+// Step 2: Create an asset library entry (UI representation of the source)
+cesdk.ui.addAssetLibraryEntry({
+  id: 'my.brand.entry',
+  sourceIds: ['my.brand.assets'],
+  previewLength: 3,
+  gridColumns: 3,
+  gridItemHeight: 'square'
+});
+
+// Step 3: Add a dock button that opens the entry
+cesdk.ui.insertOrderComponent(
+  { in: 'ly.img.dock', position: 'end' },
+  {
+    id: 'ly.img.assetLibrary.dock',
+    key: 'brand',
+    entries: ['my.brand.entry'],
+    label: 'Brand',
+    icon: '@imgly/Favorite'
+  }
+);
+```
+
+The `entries` array on the dock button takes **entry IDs**, not source IDs. If the entry ID doesn't exist, the button won't appear.
+
+## Adding Custom Registered Components
+
+Register fully custom components and add them to the dock. Use `cesdk.ui.registerComponent()` to define a component with the builder pattern, then insert it into the dock order. A spacer pushes the custom button to the bottom of the dock.
+
+```typescript highlight=highlight-custom-component
+// Register a custom component and add it to the dock bottom
+cesdk.ui.registerComponent('my.settings.button', ({ builder }) => {
+  builder.Button('settings', {
+    label: 'Settings',
+    icon: '@imgly/Settings',
+    onClick: () => {
+      cesdk.ui.showNotification({
+        message: 'Settings panel would open here',
+        type: 'info',
+        duration: 'short'
+      });
+    }
+  });
+});
+
+cesdk.ui.insertOrderComponent({ in: 'ly.img.dock', position: 'end' }, [
+  'ly.img.spacer',
+  'my.settings.button'
+]);
+```
+
+For the complete builder API documentation, see [Register a New Component](./user-interface/ui-extensions/register-new-component.md).
+
+## Default Component Order
+
+Retrieve the current dock order with `getComponentOrder` to inspect the default layout. For detailed descriptions of each component ID, see the [Component Reference](./user-interface/customization/reference/component-reference.md).
+
+```typescript highlight=highlight-default-order
+// Retrieve and log the current dock order for reference
+const currentOrder = cesdk.ui.getComponentOrder({
+  in: 'ly.img.dock'
+});
+console.log('Current dock order:', currentOrder);
+```
+
+### Asset Library Buttons
+
+| Component ID               | Description                                                                |
+| -------------------------- | -------------------------------------------------------------------------- |
+| `ly.img.assetLibrary.dock` | Asset library button (configurable with `key`, `label`, `icon`, `entries`) |
+
+### Layout
+
+| Key          | Type                         | Description                                                                                                                             |
+| ------------ | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `key`        | `string`                     | Unique identifier within the dock.                                                                                                      |
+| `label`      | `string`                     | Button label. If a matching I18N key is found, it is localized.                                                                         |
+| `icon`       | `CustomIcon`                 | A URL string pointing to an SVG, a built-in icon ID (see [Icons](./user-interface/appearance/icons.md)), or a callback returning a URL. |
+| `entries`    | `string[]`                   | Asset entries shown when the button is pressed. A single entry opens directly; multiple entries show a group overview.                  |
+| `onClick`    | `() => void`                 | Custom click handler. If provided, overrides the default asset library toggle behavior.                                                 |
+| `isSelected` | `boolean \| (() => boolean)` | Controls the selected state of the button.                                                                                              |
+| `isDisabled` | `boolean \| (() => boolean)` | Controls the disabled state of the button.                                                                                              |
+| `size`       | `'normal' \| 'large'`        | Size of the button. Defaults to `'normal'`.                                                                                             |
+| `variant`    | `'regular' \| 'plain'`       | Visual variant of the button. Defaults to `'regular'`.                                                                                  |
+| `color`      | `'accent' \| 'danger'`       | Color scheme of the button.                                                                                                             |
+
+## API Reference
+
+| Method                                                          | Purpose                                 |
+| --------------------------------------------------------------- | --------------------------------------- |
+| `cesdk.ui.getComponentOrder({ in: 'ly.img.dock', at? })`        | Get dock component order at a position  |
+| `cesdk.ui.setComponentOrder({ in: 'ly.img.dock', at? }, order)` | Set dock component order at a position  |
+| `cesdk.ui.insertOrderComponent({ in: 'ly.img.dock', at? }, c)`  | Insert components into the dock         |
+| `cesdk.ui.updateOrderComponent({ in: 'ly.img.dock', at? }, u)`  | Update dock components                  |
+| `cesdk.ui.removeOrderComponent({ in: 'ly.img.dock', at? })`     | Remove dock components                  |
+| `cesdk.ui.registerComponent()`                                  | Register custom components for dock use |
+| `cesdk.engine.editor.setSetting()`                              | Configure dock appearance settings      |
+
+---
+
+## 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/customization/force-crop.md

@@ -0,0 +1,289 @@
+> 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) > [Customization](./user-interface/customization.md) > [Force Crop](./user-interface/customization/force-crop.md)
+
+---
+
+Programmatically apply crop presets to enforce specific aspect ratios or dimensions on design blocks using the `applyForceCrop` API.
+
+![Force Crop example showing CE.SDK with crop mode active](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
+
+> **Reading time:** 8 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)
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples)
+> - [Live demo](https://img.ly/docs/cesdk/examples/guides-user-interface-customization-force-crop-browser/)
+
+The `applyForceCrop` API lets you enforce specific dimensions or aspect ratios on blocks that support cropping. This is useful when building integrations that require content to match specific formats, such as Instagram portrait posts, LinkedIn profile photos, or Facebook shared images. You can control whether the crop UI appears after applying a preset through three different modes.
+
+```typescript file=@cesdk_web_examples/guides-user-interface-customization-force-crop-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';
+
+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;
+    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];
+
+    // Add an image to demonstrate force crop
+    const imageUri = 'https://img.ly/static/ubq_samples/sample_1.jpg';
+    const imageBlock = await engine.block.addImage(imageUri);
+    engine.block.appendChild(page, imageBlock);
+
+    // Position and size the image to fill the page
+    engine.block.setWidth(imageBlock, 800);
+    engine.block.setHeight(imageBlock, 600);
+    engine.block.setPositionX(imageBlock, 0);
+    engine.block.setPositionY(imageBlock, 0);
+
+    // Create a custom crop preset with a fixed aspect ratio (4:5 for portrait)
+    engine.asset.addAssetToSource('ly.img.crop.presets', {
+      id: 'instagram-portrait',
+      label: { en: 'Portrait Post (4:5)' },
+      payload: {
+        transformPreset: {
+          type: 'FixedAspectRatio',
+          width: 4,
+          height: 5
+        }
+      }
+    });
+
+    // Create a custom crop preset with fixed dimensions
+    engine.asset.addAssetToSource('ly.img.crop.presets', {
+      id: 'profile-photo',
+      label: { en: 'Profile Photo (400x400)' },
+      payload: {
+        transformPreset: {
+          type: 'FixedSize',
+          width: 400,
+          height: 400,
+          designUnit: 'Pixel'
+        }
+      }
+    });
+
+    // Select the image block to demonstrate force crop
+    engine.block.select(imageBlock);
+
+    // Apply force crop with 'ifNeeded' mode
+    // This will only enter crop mode if dimensions differ from target
+    await cesdk.ui.applyForceCrop(imageBlock, {
+      sourceId: 'ly.img.crop.presets',
+      presetId: 'instagram-portrait',
+      mode: 'ifNeeded'
+    });
+
+    // If Needed mode - only enters crop mode when dimensions differ
+    // await cesdk.ui.applyForceCrop(imageBlock, {
+    //   sourceId: 'ly.img.crop.presets',
+    //   presetId: 'instagram-portrait',
+    //   mode: 'ifNeeded'
+    // });
+
+    // Example of silent mode - applies crop without showing UI
+    // await cesdk.ui.applyForceCrop(imageBlock, {
+    //   sourceId: 'ly.img.crop.presets',
+    //   presetId: 'profile-photo',
+    //   mode: 'silent'
+    // });
+
+    // Example of always mode - always enters crop mode
+    // await cesdk.ui.applyForceCrop(imageBlock, {
+    //   sourceId: 'ly.img.crop.presets',
+    //   presetId: 'instagram-portrait',
+    //   mode: 'always'
+    // });
+
+    console.log('Force crop example loaded successfully!');
+  }
+}
+
+export default Example;
+```
+
+This guide covers how to apply crop presets programmatically, create custom presets with fixed aspect ratios or dimensions, and control the crop mode behavior.
+
+## Applying a Crop Preset
+
+The `cesdk.ui.applyForceCrop()` method takes a block ID and an options object containing `sourceId`, `presetId`, and `mode`. The `sourceId` identifies the asset source containing crop presets, `presetId` specifies which preset to apply, and `mode` determines whether the crop UI appears.
+
+```typescript highlight=highlight-apply-force-crop
+// Apply force crop with 'ifNeeded' mode
+// This will only enter crop mode if dimensions differ from target
+await cesdk.ui.applyForceCrop(imageBlock, {
+  sourceId: 'ly.img.crop.presets',
+  presetId: 'instagram-portrait',
+  mode: 'ifNeeded'
+});
+```
+
+CE.SDK ships with default crop presets in the `ly.img.crop.presets` source. Common ratios like 1:1, 4:3, and 16:9 are available without additional configuration.
+
+## Creating Custom Crop Presets
+
+You can create custom crop presets by adding assets to the `ly.img.crop.presets` source using `engine.asset.addAssetToSource()`. Two preset types are available: fixed aspect ratio and fixed size.
+
+### Fixed Aspect Ratio Presets
+
+Fixed aspect ratio presets maintain a ratio but allow flexible dimensions. Set `type: 'FixedAspectRatio'` with width and height values representing the ratio.
+
+```typescript highlight=highlight-custom-preset
+// Create a custom crop preset with a fixed aspect ratio (4:5 for portrait)
+engine.asset.addAssetToSource('ly.img.crop.presets', {
+  id: 'instagram-portrait',
+  label: { en: 'Portrait Post (4:5)' },
+  payload: {
+    transformPreset: {
+      type: 'FixedAspectRatio',
+      width: 4,
+      height: 5
+    }
+  }
+});
+```
+
+### Fixed Size Presets
+
+Fixed size presets enforce exact pixel dimensions. Set `type: 'FixedSize'` with specific width and height values.
+
+```typescript highlight=highlight-fixed-size-preset
+// Create a custom crop preset with fixed dimensions
+engine.asset.addAssetToSource('ly.img.crop.presets', {
+  id: 'profile-photo',
+  label: { en: 'Profile Photo (400x400)' },
+  payload: {
+    transformPreset: {
+      type: 'FixedSize',
+      width: 400,
+      height: 400,
+      designUnit: 'Pixel'
+    }
+  }
+});
+```
+
+## Understanding Crop Modes
+
+The `mode` parameter controls how the editor responds after applying a crop preset.
+
+### Silent Mode
+
+Silent mode applies the crop without any UI feedback. The editor remains in its current mode. Use this for batch operations or when cropping should be invisible to the user.
+
+```typescript highlight=highlight-silent-mode
+// Example of silent mode - applies crop without showing UI
+// await cesdk.ui.applyForceCrop(imageBlock, {
+//   sourceId: 'ly.img.crop.presets',
+//   presetId: 'profile-photo',
+//   mode: 'silent'
+// });
+```
+
+### Always Mode
+
+Always mode applies the crop and opens crop mode for user adjustment. Dimension inputs are hidden to prevent changing the preset.
+
+```typescript highlight=highlight-always-mode
+// Example of always mode - always enters crop mode
+// await cesdk.ui.applyForceCrop(imageBlock, {
+//   sourceId: 'ly.img.crop.presets',
+//   presetId: 'instagram-portrait',
+//   mode: 'always'
+// });
+```
+
+### If Needed Mode
+
+If needed mode applies the crop only if dimensions differ from the target. The crop mode opens only when changes occur. This prevents unnecessary user interaction when content already fits the required dimensions.
+
+```typescript highlight=highlight-if-needed-mode
+// If Needed mode - only enters crop mode when dimensions differ
+// await cesdk.ui.applyForceCrop(imageBlock, {
+//   sourceId: 'ly.img.crop.presets',
+//   presetId: 'instagram-portrait',
+//   mode: 'ifNeeded'
+// });
+```
+
+## Applying Force Crop to Pages
+
+When applying force crop to page blocks, the API automatically enables page resize interaction during the operation. In `silent` mode, resize interaction is disabled after completion. In `always` and `ifNeeded` modes, it remains enabled while crop mode is open.
+
+## API Reference
+
+| Method                                           | Description                      |
+| ------------------------------------------------ | -------------------------------- |
+| `cesdk.ui.applyForceCrop(blockId, options)`      | Apply a crop preset to a block   |
+| `engine.asset.addAssetToSource(sourceId, asset)` | Add an asset to a source         |
+| `engine.asset.findAllSources()`                  | List available asset sources     |
+| `engine.block.supportsCrop(blockId)`             | Check if block supports cropping |
+
+---
+
+## 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