@imgly/codesign-mcp 0.1.0

package/assets/docs/guide/stickers-and-shapes/create-edit/create-stickers.md

@@ -0,0 +1,290 @@
+> 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 Edit Stickers](./stickers.md) > [Create Stickers](./stickers-and-shapes/create-edit/create-stickers.md)
+
+---
+
+Create stickers from images for use in your designs, perfect for adding icons, logos, emoji, and detailed multi-color graphics that preserve their original appearance.
+
+![Create stickers from images with two different methods](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-stickers-and-shapes-create-stickers-browser)
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-stickers-and-shapes-create-stickers-browser)
+> - [Live demo](https://img.ly/docs/cesdk/examples/guides-stickers-and-shapes-create-stickers-browser/)
+
+Stickers are graphic blocks with image fills that cannot be recolored. They work well for icons, brand logos, emoji, and complex multi-color graphics. Unlike shapes (which use solid or gradient fills and can be recolored), stickers preserve the original colors and details of the source image.
+
+```typescript file=@cesdk_web_examples/guides-stickers-and-shapes-create-stickers-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: { width: 450, height: 250, unit: 'Pixel' }
+    });
+
+    const engine = cesdk.engine;
+    const page = engine.block.findByType('page')[0];
+
+    // ===== Section 1: Using Convenience API =====
+    // Create sticker using the convenient addImage() method
+    const sticker = await engine.block.addImage(
+      'https://cdn.img.ly/assets/v4/ly.img.sticker/images/emoticons/imgly_sticker_emoticons_grin.svg'
+    );
+
+    // Set size and position (preserve aspect ratio)
+    const naturalWidth = engine.block.getWidth(sticker);
+    const naturalHeight = engine.block.getHeight(sticker);
+    const scale = 80 / Math.max(naturalWidth, naturalHeight);
+    engine.block.setWidth(sticker, naturalWidth * scale);
+    engine.block.setHeight(sticker, naturalHeight * scale);
+    engine.block.setPositionX(sticker, 95);
+    engine.block.setPositionY(sticker, 85);
+
+    // Prevent cropping and mark as sticker
+    if (engine.block.supportsContentFillMode(sticker)) {
+      engine.block.setContentFillMode(sticker, 'Contain');
+    }
+    engine.block.setKind(sticker, 'Sticker');
+
+    // Add to scene
+    engine.block.appendChild(page, sticker);
+
+    // ===== Section 2: Manual Construction =====
+    // Create sticker manually for fine-grained control
+    const manualSticker = engine.block.create('graphic');
+
+    // Set a shape (required for graphic blocks to be visible)
+    engine.block.setShape(manualSticker, engine.block.createShape('rect'));
+
+    // Create and apply image fill
+    const imageFill = engine.block.createFill('image');
+    engine.block.setString(
+      imageFill,
+      'fill/image/imageFileURI',
+      'https://cdn.img.ly/assets/v4/ly.img.sticker/images/emoticons/imgly_sticker_emoticons_blush.svg'
+    );
+    engine.block.setFill(manualSticker, imageFill);
+
+    // Set size and position (preserve aspect ratio)
+    const manualWidth = engine.block.getWidth(manualSticker) || 100;
+    const manualHeight = engine.block.getHeight(manualSticker) || 100;
+    const manualScale = 80 / Math.max(manualWidth, manualHeight);
+    engine.block.setWidth(manualSticker, manualWidth * manualScale);
+    engine.block.setHeight(manualSticker, manualHeight * manualScale);
+    engine.block.setPositionX(manualSticker, 275);
+    engine.block.setPositionY(manualSticker, 85);
+
+    // Prevent cropping and mark as sticker
+    if (engine.block.supportsContentFillMode(manualSticker)) {
+      engine.block.setContentFillMode(manualSticker, 'Contain');
+    }
+    engine.block.setKind(manualSticker, 'Sticker');
+
+    // Add to scene
+    engine.block.appendChild(page, manualSticker);
+  }
+}
+
+export default Example;
+```
+
+## Creating Stickers from Images
+
+We use `engine.block.addImage()` to create stickers quickly. This method creates the graphic block and image fill in one call. After creation, we read the natural dimensions, calculate a scale factor to preserve aspect ratio, and apply the scaled size. We also set the position, content fill mode, and mark it as 'Sticker' for proper editor behavior.
+
+```typescript highlight-convenience-api
+// Create sticker using the convenient addImage() method
+const sticker = await engine.block.addImage(
+  'https://cdn.img.ly/assets/v4/ly.img.sticker/images/emoticons/imgly_sticker_emoticons_grin.svg'
+);
+
+// Set size and position (preserve aspect ratio)
+const naturalWidth = engine.block.getWidth(sticker);
+const naturalHeight = engine.block.getHeight(sticker);
+const scale = 80 / Math.max(naturalWidth, naturalHeight);
+engine.block.setWidth(sticker, naturalWidth * scale);
+engine.block.setHeight(sticker, naturalHeight * scale);
+engine.block.setPositionX(sticker, 95);
+engine.block.setPositionY(sticker, 85);
+
+// Prevent cropping and mark as sticker
+if (engine.block.supportsContentFillMode(sticker)) {
+  engine.block.setContentFillMode(sticker, 'Contain');
+}
+engine.block.setKind(sticker, 'Sticker');
+
+// Add to scene
+engine.block.appendChild(page, sticker);
+```
+
+We preserve aspect ratio by scaling the natural dimensions proportionally. The 'Contain' fill mode ensures the entire image displays without cropping. Setting the kind to 'Sticker' prevents recoloring and provides appropriate editor controls.
+
+## Manual Construction
+
+For fine-grained control, we build stickers step by step using separate API calls. We create the graphic block, set a shape (required for visibility), create an image fill, and apply it to the block. We preserve aspect ratio by reading natural dimensions and scaling proportionally.
+
+```typescript highlight-manual-construction
+// Create sticker manually for fine-grained control
+const manualSticker = engine.block.create('graphic');
+
+// Set a shape (required for graphic blocks to be visible)
+engine.block.setShape(manualSticker, engine.block.createShape('rect'));
+
+// Create and apply image fill
+const imageFill = engine.block.createFill('image');
+engine.block.setString(
+  imageFill,
+  'fill/image/imageFileURI',
+  'https://cdn.img.ly/assets/v4/ly.img.sticker/images/emoticons/imgly_sticker_emoticons_blush.svg'
+);
+engine.block.setFill(manualSticker, imageFill);
+
+// Set size and position (preserve aspect ratio)
+const manualWidth = engine.block.getWidth(manualSticker) || 100;
+const manualHeight = engine.block.getHeight(manualSticker) || 100;
+const manualScale = 80 / Math.max(manualWidth, manualHeight);
+engine.block.setWidth(manualSticker, manualWidth * manualScale);
+engine.block.setHeight(manualSticker, manualHeight * manualScale);
+engine.block.setPositionX(manualSticker, 275);
+engine.block.setPositionY(manualSticker, 85);
+
+// Prevent cropping and mark as sticker
+if (engine.block.supportsContentFillMode(manualSticker)) {
+  engine.block.setContentFillMode(manualSticker, 'Contain');
+}
+engine.block.setKind(manualSticker, 'Sticker');
+
+// Add to scene
+engine.block.appendChild(page, manualSticker);
+```
+
+This approach works well when we need to configure multiple properties or reuse fills across blocks.
+
+## Sticker vs Shape Decision
+
+Choose between stickers and shapes based on your requirements:
+
+| Requirement               | Use Stickers | Use Shapes         |
+| ------------------------- | ------------ | ------------------ |
+| Multi-color graphics      | ✓ Yes        | ✗ No (single fill) |
+| Recolorable               | ✗ No         | ✓ Yes              |
+| Preserve original artwork | ✓ Yes        | ✗ N/A              |
+| Boolean operations        | ✗ No         | ✓ Yes              |
+| Complex paths/gradients   | ✓ Yes        | ✗ Limited          |
+| Icons, logos, emoji       | ✓ Preferred  | -                  |
+
+## Troubleshooting
+
+### Sticker Not Appearing
+
+Verify the image URL returns a valid image. Check that the sticker is added to the current page. Ensure dimensions are non-zero. Confirm the image format is supported (SVG, PNG, JPG).
+
+### Manually Created Sticker Is Blank
+
+When creating graphic blocks manually, you must set a shape before the fill becomes visible. Call `engine.block.setShape(graphic, engine.block.createShape('rect'))` after creating the block. The `addImage()` convenience API handles this automatically.
+
+### Sticker Appears Blurry
+
+For raster stickers, ensure source image resolution matches or exceeds display size. Use SVG stickers for scalable graphics that remain sharp at any size.
+
+### Sticker Appears Cropped
+
+Stickers may appear cropped if the content fill mode defaults to 'Cover'. Set the mode to 'Contain' to display the full image: `engine.block.setContentFillMode(sticker, 'Contain')`. Always check support first with `supportsContentFillMode()`.
+
+### Sticker Cannot Be Recolored
+
+This is expected behavior—stickers preserve original colors. For recolorable graphics, create shapes with vector paths instead. For simple single-color graphics, consider using a vector path shape.
+
+### Wrong Editor Behavior
+
+Ensure `engine.block.setKind(id, 'Sticker')` was called. The 'Sticker' kind designation controls editor interactions and UI panels.
+
+## API Reference
+
+Quick reference for sticker creation methods:
+
+| Method                                      | Category      | Purpose                                   |
+| ------------------------------------------- | ------------- | ----------------------------------------- |
+| `engine.block.addImage(url, options)`       | Creation      | Convenient sticker creation from URL      |
+| `engine.block.create('graphic')`            | Creation      | Create graphic block manually             |
+| `engine.block.createShape('rect')`          | Shapes        | Create shape (required for manual blocks) |
+| `engine.block.setShape(graphic, shape)`     | Shapes        | Apply shape to graphic block              |
+| `engine.block.createFill('image')`          | Fills         | Create image fill                         |
+| `engine.block.setFill(graphic, fill)`       | Fills         | Apply fill to graphic block               |
+| `engine.block.setString(fill, prop, uri)`   | Fills         | Set image URI on fill                     |
+| `engine.block.supportsContentFillMode(id)`  | Content       | Check if block supports fill mode         |
+| `engine.block.setContentFillMode(id, mode)` | Content       | Set fill mode ('Contain' or 'Cover')      |
+| `engine.block.setKind(id, 'Sticker')`       | Configuration | Mark block as sticker                     |
+| `engine.block.setPositionX/Y(id, val)`      | Transform     | Set position                              |
+| `engine.block.setWidth/Height(id, val)`     | Transform     | Set dimensions                            |
+| `engine.block.getWidth/Height(id)`          | Transform     | Get current dimensions                    |
+| `engine.block.appendChild(parent, child)`   | Hierarchy     | Add to scene                              |
+| `engine.scene.getCurrentPage()`             | Scene         | Get current page                          |
+
+---
+
+## 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/stickers-and-shapes/create-edit/edit-shapes.md

@@ -0,0 +1,211 @@
+> 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 Edit Shapes](./shapes.md) > [Edit Shapes](./stickers-and-shapes/create-edit/edit-shapes.md)
+
+---
+
+This guide shows how to programmatically edit shapes using the Block API, covering geometry modifications, fill changes, stroke configuration, transforms, and boolean combinations.
+
+![Edit shapes demonstration showing various shape modifications](https://img.ly/docs/cesdk/./assets/browser.hero.png)
+
+> **Reading time:** 15 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-stickers-and-shapes-edit-shapes-browser)
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-stickers-and-shapes-edit-shapes-browser)
+> - [Live demo](https://img.ly/docs/cesdk/examples/guides-stickers-and-shapes-edit-shapes-browser/)
+
+The `graphic` block in CE.SDK allows you to modify and replace its shape. CE.SDK supports many different types of shapes, such as rectangles, lines, ellipses, polygons, stars, and custom vector paths.
+
+```typescript file=@cesdk_web_examples/guides-stickers-and-shapes-edit-shapes-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: { width: 100, height: 100, unit: 'Pixel' }
+    });
+
+    const engine = cesdk.engine;
+    const page = engine.block.findByType('page')[0];
+
+    const graphic = engine.block.create('graphic');
+    const imageFill = engine.block.createFill('image');
+    engine.block.setString(
+      imageFill,
+      'fill/image/imageFileURI',
+      'https://img.ly/static/ubq_samples/sample_1.jpg'
+    );
+    engine.block.setFill(graphic, imageFill);
+    engine.block.setWidth(graphic, 100);
+    engine.block.setHeight(graphic, 100);
+    engine.block.appendChild(page, graphic);
+    engine.block.setPositionX(graphic, 0);
+    engine.block.setPositionY(graphic, 0);
+
+    await engine.scene.zoomToBlock(page, { padding: 40 });
+
+    engine.block.supportsShape(graphic); // Returns true
+    const text = engine.block.create('text');
+    engine.block.supportsShape(text); // Returns false
+
+    const rectShape = engine.block.createShape('rect');
+    engine.block.setShape(graphic, rectShape);
+
+    const shape = engine.block.getShape(graphic);
+    const shapeType = engine.block.getType(shape);
+
+    const starShape = engine.block.createShape('star');
+    engine.block.destroy(engine.block.getShape(graphic));
+    engine.block.setShape(graphic, starShape);
+    /* The following line would also destroy the currently attached starShape */
+    // engine.block.destroy(graphic);
+
+    const allShapeProperties = engine.block.findAllProperties(starShape);
+    engine.block.setInt(starShape, 'shape/star/points', 5);
+  }
+}
+
+export default Example;
+```
+
+Similarly to blocks, each shape object has a numeric ID which can be used to query and modify its properties.
+
+## Accessing Shapes
+
+To query whether a block supports shapes, use the `engine.block.supportsShape(id)` API. Currently, only the `graphic` design block supports shape objects. To query the shape of a design block, first create a shape and set it, then call `engine.block.getShape(id)`. You can pass the returned result into other APIs to query more information about the shape, such as its type via `engine.block.getType(id)`.
+
+```typescript highlight-accessShapes
+engine.block.supportsShape(graphic); // Returns true
+const text = engine.block.create('text');
+engine.block.supportsShape(text); // Returns false
+
+const rectShape = engine.block.createShape('rect');
+engine.block.setShape(graphic, rectShape);
+
+const shape = engine.block.getShape(graphic);
+const shapeType = engine.block.getType(shape);
+```
+
+## Replacing Shapes
+
+When replacing a shape, remember to destroy the previous shape object if you don't intend to use it further. Shape objects that are not attached to a design block will never be automatically destroyed.
+
+```typescript highlight-replaceShape
+const starShape = engine.block.createShape('star');
+engine.block.destroy(engine.block.getShape(graphic));
+engine.block.setShape(graphic, starShape);
+/* The following line would also destroy the currently attached starShape */
+// engine.block.destroy(graphic);
+```
+
+Destroying a design block will also destroy its attached shape block (shown in the commented line).
+
+## Shape Properties
+
+Just like design blocks, shapes with different types have different properties that you can query and modify via the API. Use `engine.block.findAllProperties(id)` to get a list of all properties of a given shape.
+
+```typescript highlight-getProperties
+const allShapeProperties = engine.block.findAllProperties(starShape);
+```
+
+For the star shape in this example, the call returns an array including properties like `"shape/star/innerDiameter"` and `"shape/star/points"`.
+
+Once we know the property keys of a shape, we can use the same APIs as for design blocks to modify those properties. For example, we can use `engine.block.setInt()` to change the number of points of the star to five.
+
+```typescript highlight-modifyProperties
+engine.block.setInt(starShape, 'shape/star/points', 5);
+```
+
+## Troubleshooting
+
+### Shape Not Changing
+
+- Verify the block supports shapes: `engine.block.supportsShape(block)` must return `true`
+- Check that the shape was created successfully and has a valid ID
+- Ensure the shape is assigned to the block using `engine.block.setShape()`
+
+### Property Modification Not Working
+
+- Confirm you're using the correct property key (use `findAllProperties()` to discover them)
+- Verify you're using the right setter method: `setInt()` for integers, `setFloat()` for floats, `setString()` for strings
+- Check that the property exists for that shape type (e.g., `shape/star/points` only exists on star shapes)
+
+## API Reference
+
+| Method                                  | Category     | Purpose                                      |
+| --------------------------------------- | ------------ | -------------------------------------------- |
+| `engine.block.supportsShape(id)`        | Validation   | Check if block supports shapes               |
+| `engine.block.createShape(type)`        | Creation     | Create new shape instance                    |
+| `engine.block.getShape(id)`             | Query        | Get shape from graphic block                 |
+| `engine.block.getType(id)`              | Query        | Get type of block or shape                   |
+| `engine.block.setShape(id, shape)`      | Modification | Apply shape to graphic block                 |
+| `engine.block.findAllProperties(id)`    | Query        | List all properties of block or shape        |
+| `engine.block.setInt(id, prop, val)`    | Modification | Set integer property (e.g., star points)     |
+| `engine.block.setFloat(id, prop, val)`  | Modification | Set float property (e.g., corner radius)     |
+| `engine.block.setString(id, prop, val)` | Modification | Set string property (e.g., vector path data) |
+| `engine.block.destroy(id)`              | Management   | Destroy block or shape                       |
+
+---
+
+## 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