@imgly/codesign-mcp 0.1.0

package/assets/docs/guide/export-save-publish/export/to-raw-data.md

@@ -0,0 +1,303 @@
+> 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) > [Export Media Assets](./export-save-publish/export.md) > [To Raw Data](./export-save-publish/export/to-raw-data.md)
+
+---
+
+Exporting designs to raw pixel data gives you direct access to uncompressed
+RGBA bytes, enabling custom image processing, GPU texture uploads, and
+integration with advanced graphics pipelines. Unlike compressed formats like
+PNG or JPEG, raw data export provides the pixel buffer without encoding
+overhead, making it ideal for performance-critical applications and scenarios
+where you need to manipulate individual pixels programmatically.
+
+![Export to Raw Data example showing grayscale image processing with export button](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
+
+> **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)
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples)
+> - [Live demo](https://img.ly/docs/cesdk/examples/guides-export-save-publish-export-to-raw-data-browser/)
+
+```typescript file=@cesdk_web_examples/guides-export-save-publish-export-to-raw-data-browser/src/browser.ts reference-only
+import type { EditorPlugin, EditorPluginContext } from '@cesdk/cesdk-js';
+import packageJson from '../package.json';
+import {
+  BlurAssetSource,
+  CaptionPresetsAssetSource,
+  ColorPaletteAssetSource,
+  CropPresetsAssetSource,
+  DemoAssetSources,
+  EffectsAssetSource,
+  FiltersAssetSource,
+  PagePresetsAssetSource,
+  StickerAssetSource,
+  TextAssetSource,
+  TypefaceAssetSource,
+  UploadAssetSources,
+  VectorShapeAssetSource
+} from '@cesdk/cesdk-js/plugins';
+import { DesignEditorConfig } from '../design-editor/plugin';
+
+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());
+
+    // Load asset source plugins
+    await cesdk.addPlugin(new BlurAssetSource());
+    await cesdk.addPlugin(new CaptionPresetsAssetSource());
+    await cesdk.addPlugin(new ColorPaletteAssetSource());
+    await cesdk.addPlugin(new CropPresetsAssetSource());
+    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 TypefaceAssetSource());
+    await cesdk.addPlugin(new VectorShapeAssetSource());
+    await cesdk.addPlugin(
+      new UploadAssetSources({
+        include: ['ly.img.image.upload']
+      })
+    );
+    await cesdk.addPlugin(
+      new DemoAssetSources({
+        include: ['ly.img.image.*']
+      })
+    );
+    await cesdk.actions.run('scene.create', {
+      page: { width: 800, height: 600, unit: 'Pixel' }
+    });
+
+    const engine = cesdk.engine;
+    const page = engine.block.findByType('page')[0];
+
+    // Set explicit page dimensions
+
+    const imageUri = 'https://img.ly/static/ubq_samples/sample_1.jpg';
+
+    // Create a single image block to demonstrate raw data export
+    const imageBlock = await engine.block.addImage(imageUri, {
+      size: { width: 800, height: 600 }
+    });
+    engine.block.appendChild(page, imageBlock);
+    engine.block.setPositionX(imageBlock, 0);
+    engine.block.setPositionY(imageBlock, 0);
+
+    // Add export button to navigation bar
+    cesdk.ui.insertOrderComponent(
+      { in: 'ly.img.navigation.bar', position: 'end' },
+      {
+        id: 'ly.img.actions.navigationBar',
+        children: ['ly.img.exportImage.navigationBar']
+      }
+    );
+
+    // Override the built-in exportDesign action
+    cesdk.actions.register('exportDesign', async () => {
+      // Export to raw pixel data
+      const width = Math.floor(engine.block.getWidth(imageBlock));
+      const height = Math.floor(engine.block.getHeight(imageBlock));
+
+      const blob = await engine.block.export(imageBlock, {
+        mimeType: 'application/octet-stream',
+        targetWidth: width,
+        targetHeight: height
+      });
+
+      // Convert blob to raw pixel array
+      const arrayBuffer = await blob.arrayBuffer();
+      const pixelData = new Uint8Array(arrayBuffer);
+
+      // Apply grayscale processing
+      const processedData = this.toGrayscale(pixelData, width, height);
+
+      // Download processed image
+      await this.downloadProcessedImage(processedData, width, height);
+    });
+  }
+
+  /**
+   * Convert image to grayscale by averaging RGB channels
+   */
+  private toGrayscale(
+    pixelData: Uint8Array,
+    _width: number,
+    _height: number
+  ): Uint8Array {
+    const result = new Uint8Array(pixelData);
+    for (let i = 0; i < result.length; i += 4) {
+      const avg = Math.round((result[i] + result[i + 1] + result[i + 2]) / 3);
+      result[i] = avg; // R
+      result[i + 1] = avg; // G
+      result[i + 2] = avg; // B
+      // Keep alpha unchanged: result[i + 3]
+    }
+    return result;
+  }
+
+  /**
+   * Convert processed pixel data to PNG and trigger download
+   */
+  private async downloadProcessedImage(
+    pixelData: Uint8Array,
+    width: number,
+    height: number
+  ): Promise<void> {
+    // Create canvas and render pixel data
+    const canvas = document.createElement('canvas');
+    canvas.width = width;
+    canvas.height = height;
+    const ctx = canvas.getContext('2d');
+
+    if (!ctx) {
+      throw new Error('Failed to get canvas context');
+    }
+
+    // Create ImageData from pixel array
+    const imageData = new ImageData(
+      new Uint8ClampedArray(pixelData),
+      width,
+      height
+    );
+    ctx.putImageData(imageData, 0, 0);
+
+    // Convert canvas to blob
+    const blob = await new Promise<Blob>((resolve, reject) => {
+      canvas.toBlob(
+        (blob) => {
+          if (blob) {
+            resolve(blob);
+          } else {
+            reject(new Error('Failed to convert canvas to blob'));
+          }
+        },
+        'image/png',
+        1.0
+      );
+    });
+
+    // Trigger download
+    const url = URL.createObjectURL(blob);
+    const link = document.createElement('a');
+    link.href = url;
+    link.download = 'processed-image.png';
+    link.click();
+
+    // Clean up
+    URL.revokeObjectURL(url);
+  }
+}
+
+export default Example;
+```
+
+## When to Use Raw Data Export
+
+Raw pixel data export provides direct access to uncompressed RGBA bytes from CE.SDK, giving you complete control over individual pixels for custom processing workflows.
+
+Use raw data export when you need pixel-level access to exported designs for custom algorithms or integrations. For standard image delivery, use PNG or JPEG exports instead, as they provide compression and are ready to use without additional processing.
+
+## Understanding Raw Data Format
+
+When you export with `mimeType: 'application/octet-stream'`, CE.SDK returns a Blob containing uncompressed RGBA pixel data. The format is straightforward:
+
+- **4 bytes per pixel** representing Red, Green, Blue, and Alpha channels
+- **Values from 0-255** for each channel (8-bit unsigned integers)
+- **Row-major order** with pixels arranged left-to-right, top-to-bottom
+- **Total size** equals width × height × 4 bytes
+
+## How to Export Raw Data
+
+To export a block as raw pixel data, use the `engine.block.export()` method with `mimeType: 'application/octet-stream'`:
+
+```typescript highlight-basic-export
+const blob = await engine.block.export(imageBlock, {
+  mimeType: 'application/octet-stream',
+  targetWidth: width,
+  targetHeight: height
+});
+```
+
+This returns a Blob containing uncompressed RGBA pixel data that you can process with custom algorithms.
+
+## Download Exported Data
+
+The example overrides the built-in `exportDesign` action to implement a custom workflow that exports to raw data, processes the pixels, and downloads the result:
+
+```typescript highlight-export-action-body
+// Export to raw pixel data
+const width = Math.floor(engine.block.getWidth(imageBlock));
+const height = Math.floor(engine.block.getHeight(imageBlock));
+
+const blob = await engine.block.export(imageBlock, {
+  mimeType: 'application/octet-stream',
+  targetWidth: width,
+  targetHeight: height
+});
+
+// Convert blob to raw pixel array
+const arrayBuffer = await blob.arrayBuffer();
+const pixelData = new Uint8Array(arrayBuffer);
+
+// Apply grayscale processing
+const processedData = this.toGrayscale(pixelData, width, height);
+
+// Download processed image
+await this.downloadProcessedImage(processedData, width, height);
+```
+
+This complete workflow demonstrates exporting to raw pixel data, applying grayscale processing, and downloading the processed image as PNG.
+
+## Performance Considerations
+
+Raw data export involves trade-offs between flexibility and efficiency:
+
+**Memory Usage**: Raw RGBA data requires 4 bytes per pixel. A 1920×1080 CE.SDK export uses approximately 8.3 MB uncompressed, compared to 1-3 MB for PNG. Reduce memory usage with the `targetWidth` and `targetHeight` export options:
+
+```typescript
+const blob = await engine.block.export(blockId, {
+  mimeType: 'application/octet-stream',
+  targetWidth: 960,
+  targetHeight: 540
+});
+```
+
+**Processing Speed**: Operating directly on pixel data from CE.SDK exports is fast because there's no encoding/decoding overhead. However, processing millions of pixels can be time-consuming for complex algorithms. Consider using Web Workers for heavy processing to avoid blocking the main thread.
+
+**When to Use Raw vs. Compressed for CE.SDK Exports**:
+
+- Use raw data when you need custom post-processing before final delivery
+- Use PNG or JPEG for direct downloads from CE.SDK
+- Use raw data for intermediate processing steps in multi-stage pipelines
+- Use compressed formats for final output or network transfer
+
+## API Reference
+
+| Method                                    | Description                                                                   |
+| ----------------------------------------- | ----------------------------------------------------------------------------- |
+| `engine.block.export()`                   | Exports a block with `mimeType: 'application/octet-stream'` for raw RGBA data |
+| `engine.block.getWidth()`                 | Returns the width of a block in pixels                                        |
+| `engine.block.getHeight()`                | Returns the height of a block in pixels                                       |
+| `Blob.arrayBuffer()`                      | Converts the blob to an ArrayBuffer for raw data access                       |
+| `ImageData()`                             | Creates an ImageData object from a Uint8ClampedArray                          |
+| `CanvasRenderingContext2D.putImageData()` | Paints pixel data onto a canvas                                               |
+
+---
+
+## 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/export-save-publish/export/to-webp.md

@@ -0,0 +1,261 @@
+> 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) > [Export Media Assets](./export-save-publish/export.md) > [To WebP](./export-save-publish/export/to-webp.md)
+
+---
+
+Export designs to WebP format for optimized web delivery with smaller file sizes than PNG or JPEG.
+
+![Export to WebP showing the editor with export options](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
+
+> **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-export-save-publish-export-to-webp-browser)
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-export-save-publish-export-to-webp-browser)
+> - [Live demo](https://img.ly/docs/cesdk/examples/guides-export-save-publish-export-to-webp-browser/)
+
+WebP delivers smaller file sizes than PNG and JPEG while preserving image quality and transparency support.
+
+```typescript file=@cesdk_web_examples/guides-export-save-publish-export-to-webp-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: Export to WebP Guide
+ *
+ * Demonstrates exporting designs to WebP format with:
+ * - Built-in export action triggered programmatically
+ * - Three export buttons showcasing different quality presets
+ * - Lossy, lossless, and social media export options
+ */
+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');
+    }
+
+    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());
+
+    const engine = cesdk.engine;
+
+    // Load template and zoom to fit
+    await engine.scene.loadFromURL(
+      'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_postcard_1.scene'
+    );
+    const page = engine.scene.getCurrentPage();
+    if (!page) throw new Error('No page found');
+
+    await engine.scene.zoomToBlock(page, { padding: 40 });
+
+    // Three export buttons with different WebP settings
+    cesdk.ui.insertOrderComponent(
+      { in: 'ly.img.navigation.bar', position: 'end' },
+      {
+        id: 'ly.img.actions.navigationBar',
+        children: [
+          {
+            id: 'ly.img.action.navigationBar',
+            key: 'webp-lossy',
+            label: 'Lossy',
+            icon: '@imgly/Download',
+            onClick: async () => {
+              const p = engine.scene.getCurrentPage()!;
+              // Export with lossy compression
+              const blob = await engine.block.export(p, {
+                mimeType: 'image/webp',
+                webpQuality: 0.8
+              });
+              // Download using CE.SDK utils
+              await cesdk.utils.downloadFile(blob, 'image/webp');
+            }
+          },
+          {
+            id: 'ly.img.action.navigationBar',
+            key: 'webp-lossless',
+            label: 'Lossless',
+            icon: '@imgly/Download',
+            onClick: async () => {
+              const p = engine.scene.getCurrentPage()!;
+              const blob = await engine.block.export(p, {
+                mimeType: 'image/webp',
+                webpQuality: 1.0
+              });
+              await cesdk.utils.downloadFile(blob, 'image/webp');
+            }
+          },
+          {
+            id: 'ly.img.action.navigationBar',
+            key: 'webp-social',
+            label: 'Social',
+            icon: '@imgly/Download',
+            onClick: async () => {
+              const p = engine.scene.getCurrentPage()!;
+              // Export with target dimensions for social media
+              const blob = await engine.block.export(p, {
+                mimeType: 'image/webp',
+                webpQuality: 0.9,
+                targetWidth: 1200,
+                targetHeight: 630
+              });
+              await cesdk.utils.downloadFile(blob, 'image/webp');
+            }
+          },
+          {
+            id: 'ly.img.action.navigationBar',
+            key: 'export-action',
+            label: 'Export',
+            icon: '@imgly/Download',
+            onClick: () => {
+              // Run built-in export with WebP format
+              cesdk.actions.run('exportDesign', { mimeType: 'image/webp' });
+            }
+          }
+        ]
+      }
+    );
+  }
+}
+
+export default Example;
+```
+
+This guide covers exporting to WebP, configuring quality settings, and triggering downloads.
+
+## Export to WebP
+
+Call `engine.block.export()` with `mimeType: 'image/webp'` and a `webpQuality` value between 0 and 1.
+
+```typescript highlight=highlight-export-webp
+// Export with lossy compression
+const blob = await engine.block.export(p, {
+  mimeType: 'image/webp',
+  webpQuality: 0.8
+});
+```
+
+The `webpQuality` parameter controls compression. A value of 0.8 provides a good balance between file size and visual quality for most use cases.
+
+## Export Options
+
+WebP export supports these options:
+
+| Option         | Type           | Description                                 |
+| -------------- | -------------- | ------------------------------------------- |
+| `mimeType`     | `'image/webp'` | Required. Specifies WebP format             |
+| `webpQuality`  | `number`       | Quality from 0 to 1. Default 1.0 (lossless) |
+| `targetWidth`  | `number`       | Optional resize width                       |
+| `targetHeight` | `number`       | Optional resize height                      |
+
+Combine `targetWidth` and `targetHeight` to resize the output, useful for social media or thumbnail generation.
+
+```typescript highlight=highlight-export-options
+// Export with target dimensions for social media
+const blob = await engine.block.export(p, {
+  mimeType: 'image/webp',
+  webpQuality: 0.9,
+  targetWidth: 1200,
+  targetHeight: 630
+});
+```
+
+Set `webpQuality` to 1.0 for lossless compression when pixel-perfect output is required.
+
+## Built-in Export Action
+
+Run the `exportDesign` action to execute the default export flow programmatically.
+
+```typescript highlight=highlight-trigger-export
+// Run built-in export with WebP format
+cesdk.actions.run('exportDesign', { mimeType: 'image/webp' });
+```
+
+This executes the registered export action, which handles the complete export process including format selection and file download.
+
+## Download Export
+
+Use `cesdk.utils.downloadFile()` to trigger the browser's download dialog for the exported blob.
+
+```typescript highlight=highlight-download
+// Download using CE.SDK utils
+await cesdk.utils.downloadFile(blob, 'image/webp');
+```
+
+Pass the blob and MIME type to prompt the user to save the file locally.
+
+> **Note:** WebP is supported in all modern browsers. For older browsers, consider PNG or JPEG as fallback formats.
+
+## API Reference
+
+| API                          | Description                                                      |
+| ---------------------------- | ---------------------------------------------------------------- |
+| `engine.block.export()`      | Exports a block to an image blob with format and quality options |
+| `cesdk.actions.run()`        | Runs a built-in action like `exportDesign`                       |
+| `cesdk.utils.downloadFile()` | Triggers browser download dialog for a blob                      |
+
+## Next Steps
+
+[Export Overview](./export-save-publish/export/overview.md) - Learn about all supported export formats and their options.
+
+[Export to PDF](./export-save-publish/export/to-pdf.md) - Generate print-ready PDF documents from your designs.
+
+[Size Limits](./export-save-publish/export/size-limits.md) - Understand export size constraints and optimization strategies.
+
+[Partial Export](./export-save-publish/export/partial-export.md) - Export specific blocks or regions instead of the full design.
+
+---
+
+## More Resources
+
+- **[Vanilla JS/TS Documentation Index](https://img.ly/docs/cesdk/js.md)** - Browse all Vanilla JS/TS documentation
+- **[Complete Documentation](./llms-full.txt.md)** - Full documentation in one file (for LLMs)
+- **[Web Documentation](./js.md)** - Interactive documentation with examples
+- **[Support](mailto:support@img.ly)** - Contact IMG.LY support