@imgly/codesign-mcp 0.1.5 → 0.1.6

package/assets/docs/guide/conversion/to-pdf.md

@@ -1,4 +1,4 @@
-> 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).
+> This is one page of the CE.SDK Node.js documentation. For a complete overview, see the [Node.js Documentation Index](https://img.ly/docs/cesdk/node.md). For all docs in one file, see [llms-full.txt](./llms-full.txt.md).
 
 **Navigation:** [Guides](./guides.md) > [Conversion](./conversion.md) > [To PDF](./conversion/to-pdf.md)
 
@@ -6,217 +6,22 @@
 
 The CE.SDK allows you to convert JPEG, PNG, WebP, BMP and SVG images into PDFs directly in the browser—no server-side processing required. You can perform this conversion programmatically or through the user interface.
 
-![To PDF](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-conversion-to-pdf-browser)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-conversion-to-pdf-browser)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-conversion-to-pdf-browser/)
-
 The CE.SDK supports converting single or multiple images to PDF while allowing transformations such as cropping, rotating, and adding text before exporting. You can also customize PDF output settings, including resolution, compatibility and underlayer.
 
-```typescript file=@cesdk_web_examples/guides-conversion-to-pdf-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: To PDF Guide
- *
- * This example demonstrates:
- * - Exporting designs as PDF documents
- * - Configuring PDF output settings (DPI, compatibility, underlayer)
- * - Adding a custom PDF export button to the navigation bar
- */
-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 a template scene
-    await engine.scene.loadFromURL(
-      'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_postcard_1.scene'
-    );
-    const page = engine.scene.getCurrentPage()!;
-    await engine.scene.zoomToBlock(page);
-
-    // Add PDF export buttons to the navigation bar
-    cesdk.ui.insertOrderComponent(
-      { in: 'ly.img.navigation.bar', position: 'end' },
-      {
-        id: 'ly.img.actions.navigationBar',
-        children: [
-          {
-            id: 'ly.img.action.navigationBar',
-            key: 'export-pdf',
-            label: 'PDF',
-            icon: '@imgly/Download',
-            onClick: async () => {
-              // Export scene as PDF (includes all pages)
-              const scene = engine.scene.get()!;
-              const pdfBlob = await engine.block.export(scene, {
-                mimeType: 'application/pdf'
-              });
-
-              // Download using CE.SDK utils
-              await cesdk.utils.downloadFile(pdfBlob, 'application/pdf');
-
-              cesdk.ui.showNotification({
-                message: 'PDF exported successfully',
-                type: 'success'
-              });
-            }
-          },
-          {
-            id: 'ly.img.action.navigationBar',
-            key: 'export-high-compat',
-            label: 'High Compat',
-            icon: '@imgly/Download',
-            onClick: async () => {
-              const scene = engine.scene.get()!;
-
-              // Enable high compatibility mode for consistent rendering across PDF viewers
-              // This rasterizes complex elements like gradients with transparency at scene DPI
-              const pdfBlob = await engine.block.export(scene, {
-                mimeType: 'application/pdf',
-                exportPdfWithHighCompatibility: true
-              });
-
-              await cesdk.utils.downloadFile(pdfBlob, 'application/pdf');
-              cesdk.ui.showNotification({
-                message: 'High compatibility PDF exported',
-                type: 'success'
-              });
-            }
-          },
-          {
-            id: 'ly.img.action.navigationBar',
-            key: 'export-underlayer',
-            label: 'Underlayer',
-            icon: '@imgly/Download',
-            onClick: async () => {
-              const scene = engine.scene.get()!;
-
-              // Define the underlayer spot color before export
-              // RGB values (0.8, 0.8, 0.8) provide a preview representation
-              engine.editor.setSpotColorRGB('RDG_WHITE', 0.8, 0.8, 0.8);
-
-              // Export with underlayer for special media printing
-              const pdfBlob = await engine.block.export(scene, {
-                mimeType: 'application/pdf',
-                exportPdfWithHighCompatibility: true,
-                exportPdfWithUnderlayer: true,
-                underlayerSpotColorName: 'RDG_WHITE',
-                // Negative offset shrinks underlayer to prevent visible edges
-                underlayerOffset: -2.0
-              });
-
-              await cesdk.utils.downloadFile(pdfBlob, 'application/pdf');
-              cesdk.ui.showNotification({
-                message: 'PDF with underlayer exported',
-                type: 'success'
-              });
-            }
-          },
-          {
-            id: 'ly.img.action.navigationBar',
-            key: 'export-dpi',
-            label: 'Custom DPI',
-            icon: '@imgly/Download',
-            onClick: async () => {
-              const scene = engine.scene.get()!;
-
-              // Adjust the scene DPI for print-ready output
-              // Higher DPI = better quality but larger file size
-              engine.block.setFloat(scene, 'scene/dpi', 150);
-
-              const pdfBlob = await engine.block.export(scene, {
-                mimeType: 'application/pdf'
-              });
-
-              await cesdk.utils.downloadFile(pdfBlob, 'application/pdf');
-              cesdk.ui.showNotification({
-                message: 'PDF exported at 150 DPI',
-                type: 'success'
-              });
-            }
-          }
-        ]
-      }
-    );
-  }
-}
-
-export default Example;
-```
-
-This guide covers exporting designs as PDF documents, configuring output settings like DPI and compatibility, adding underlayers for specialty printing, and integrating PDF export into the user interface.
-
 ## Convert to PDF Programmatically
 
 You can use the CE.SDK to load an image, apply basic edits, and export it as a PDF programmatically. The following examples demonstrate how to convert a single image and how to merge multiple images into a single PDF.
 
 ### Convert a Single Image to PDF
 
-The example below loads an image, applies transformations, and exports it as a PDF.
+The example below loads an image, applies transformations, and exports it as a PDF:
 
-```ts
+```ts example=basic-scene marker=cesdk-init-after
 // Prepare an image URL
-const imageURL = 'https://img.ly/static/ubq_samples/sample_4.jpg';
+const imageURL = 'https://example.com/image.jpg';
 
 // Create a new scene by loading the image immediately
-await cesdk.createFromImage(imageURL);
+await instance.createFromImage(image);
 
 // Find the automatically added graphic block with an image fill
 const block = engine.block.findByType('graphic')[0];
@@ -225,25 +30,25 @@ const block = engine.block.findByType('graphic')[0];
 engine.block.setCropScaleRatio(block, 2.0);
 
 // Export as PDF Blob
-const page = engine.scene.getCurrentPage()!;
+const page = engine.scene.getCurrentPage();
 const blob = await engine.block.export(page, { mimeType: 'application/pdf' });
 // You can now save it or display it in your application
 ```
 
 ### Combine Multiple Images into a Single PDF
 
-The example below demonstrates how to merge multiple images into a single PDF document.
+The example below demonstrates how to merge multiple images into a single PDF document:
 
-```ts
+```ts example=merge-images marker=cesdk-init-after
 // Prepare image URLs
 const images = [
-  'https://img.ly/static/ubq_samples/sample_1.jpg',
-  'https://img.ly/static/ubq_samples/sample_2.jpg',
-  'https://img.ly/static/ubq_samples/sample_3.jpg'
+  'https://example.com/image1.jpg',
+  'https://example.com/image2.png',
+  'https://example.com/image3.webp',
 ];
 
 // Create an empty scene with a 'VerticalStack' layout
-const scene = engine.scene.create('VerticalStack');
+const scene = await engine.scene.create('VerticalStack');
 const [stack] = engine.block.findByType('stack');
 
 // Load all images as pages
@@ -262,188 +67,9 @@ const blob = await engine.block.export(scene, { mimeType: 'application/pdf' });
 // You can now save it or display it in your application
 ```
 
-## Export a Page as PDF
-
-Use `engine.block.export()` to export a design block as a PDF. The method accepts a block ID and export options including the MIME type.
-
-```typescript highlight=highlight-export-pdf
-// Export scene as PDF (includes all pages)
-const scene = engine.scene.get()!;
-const pdfBlob = await engine.block.export(scene, {
-  mimeType: 'application/pdf'
-});
-```
-
-Export returns a Blob containing the PDF data. You can export a single page for a single-page PDF, or export the entire scene to include all pages in a multi-page PDF document.
-
-## Download the PDF
-
-Use `cesdk.utils.downloadFile()` to save the exported PDF to the user's device.
-
-```typescript highlight=highlight-download
-// Download using CE.SDK utils
-await cesdk.utils.downloadFile(pdfBlob, 'application/pdf');
-```
-
-The utility handles creating a download link and triggering the browser's save dialog with the appropriate file extension.
-
-## PDF Conversion via the User Interface
-
-The CE.SDK allows you to enable PDF conversion directly from the user interface. You can customize the UI to include a "Convert to PDF" button, allowing users to trigger conversion to PDF after they [upload images](./insert-media/images.md) and perform any edits or adjustments.
-
-### Add a PDF Export Button
-
-Integrate PDF export into the CE.SDK interface by adding a custom button to the navigation bar.
-
-```typescript highlight=highlight-export-button
-// Add PDF export buttons to the navigation bar
-cesdk.ui.insertOrderComponent(
-  { in: 'ly.img.navigation.bar', position: 'end' },
-  {
-    id: 'ly.img.actions.navigationBar',
-    children: [
-      {
-        id: 'ly.img.action.navigationBar',
-        key: 'export-pdf',
-        label: 'PDF',
-        icon: '@imgly/Download',
-        onClick: async () => {
-          // Export scene as PDF (includes all pages)
-          const scene = engine.scene.get()!;
-          const pdfBlob = await engine.block.export(scene, {
-            mimeType: 'application/pdf'
-          });
-
-          // Download using CE.SDK utils
-          await cesdk.utils.downloadFile(pdfBlob, 'application/pdf');
-
-          cesdk.ui.showNotification({
-            message: 'PDF exported successfully',
-            type: 'success'
-          });
-        }
-      },
-      {
-        id: 'ly.img.action.navigationBar',
-        key: 'export-high-compat',
-        label: 'High Compat',
-        icon: '@imgly/Download',
-        onClick: async () => {
-          const scene = engine.scene.get()!;
-
-          // Enable high compatibility mode for consistent rendering across PDF viewers
-          // This rasterizes complex elements like gradients with transparency at scene DPI
-          const pdfBlob = await engine.block.export(scene, {
-            mimeType: 'application/pdf',
-            exportPdfWithHighCompatibility: true
-          });
-
-          await cesdk.utils.downloadFile(pdfBlob, 'application/pdf');
-          cesdk.ui.showNotification({
-            message: 'High compatibility PDF exported',
-            type: 'success'
-          });
-        }
-      },
-      {
-        id: 'ly.img.action.navigationBar',
-        key: 'export-underlayer',
-        label: 'Underlayer',
-        icon: '@imgly/Download',
-        onClick: async () => {
-          const scene = engine.scene.get()!;
-
-          // Define the underlayer spot color before export
-          // RGB values (0.8, 0.8, 0.8) provide a preview representation
-          engine.editor.setSpotColorRGB('RDG_WHITE', 0.8, 0.8, 0.8);
-
-          // Export with underlayer for special media printing
-          const pdfBlob = await engine.block.export(scene, {
-            mimeType: 'application/pdf',
-            exportPdfWithHighCompatibility: true,
-            exportPdfWithUnderlayer: true,
-            underlayerSpotColorName: 'RDG_WHITE',
-            // Negative offset shrinks underlayer to prevent visible edges
-            underlayerOffset: -2.0
-          });
-
-          await cesdk.utils.downloadFile(pdfBlob, 'application/pdf');
-          cesdk.ui.showNotification({
-            message: 'PDF with underlayer exported',
-            type: 'success'
-          });
-        }
-      },
-      {
-        id: 'ly.img.action.navigationBar',
-        key: 'export-dpi',
-        label: 'Custom DPI',
-        icon: '@imgly/Download',
-        onClick: async () => {
-          const scene = engine.scene.get()!;
-
-          // Adjust the scene DPI for print-ready output
-          // Higher DPI = better quality but larger file size
-          engine.block.setFloat(scene, 'scene/dpi', 150);
-
-          const pdfBlob = await engine.block.export(scene, {
-            mimeType: 'application/pdf'
-          });
-
-          await cesdk.utils.downloadFile(pdfBlob, 'application/pdf');
-          cesdk.ui.showNotification({
-            message: 'PDF exported at 150 DPI',
-            type: 'success'
-          });
-        }
-      }
-    ]
-  }
-);
-```
-
-The button triggers the export workflow when clicked, providing users with a convenient way to download their designs as PDF documents.
-
-### Alternative: Register a Custom Component
-
-You can also use `ui.registerComponent` to create a more customized button with full control over styling and behavior.
-
-```ts
-// Register a custom button component
-cesdk.ui.registerComponent('convert.nav', ({ builder: { Button }, engine }) => {
-  Button('convert-to-pdf', {
-    label: 'Convert To PDF',
-    icon: '@imgly/Download',
-    color: 'accent',
-    onClick: async () => {
-      // Export the current scene as a PDF blob
-      const scene = engine.scene.get()!;
-      const blob = await engine.block.export(scene, {
-        mimeType: 'application/pdf'
-      });
-      // Trigger download of the PDF blob
-      const element = document.createElement('a');
-      element.setAttribute('href', window.URL.createObjectURL(blob));
-      element.setAttribute('download', 'converted.pdf');
-      element.style.display = 'none';
-      element.click();
-      element.remove();
-    }
-  });
-});
-
-// Add the custom button at the end of the navigation bar
-cesdk.ui.setComponentOrder({ in: 'ly.img.navigation.bar' }, [
-  ...cesdk.ui.getComponentOrder({ in: 'ly.img.navigation.bar' }),
-  'convert.nav'
-]);
-```
-
-For more details on customizing the UI, see the [User Interface Configuration Guide](./user-interface/customization.md).
+## Configuring PDF Output
 
-## Configure PDF Output Settings
-
-The SDK provides various options for customizing PDF exports. You can control resolution, compatibility, and underlayer settings.
+The SDK provides various options for customizing PDF exports. You can control resolution, compatibility and underlayer.
 
 ### Available PDF Output Settings
 
@@ -452,33 +78,6 @@ The SDK provides various options for customizing PDF exports. You can control re
 - **Compatibility:** Enable this setting to improve compatibility with various PDF viewers. When enabled, images and effects are rasterized based on the scene's DPI instead of being embedded as vector elements.
 - **Underlayer:** Add an underlayer beneath the image content to optimize printing on non-white or specialty media (e.g., fabric, glass). The ink type is defined in `ExportOptions` using a spot color. You can also apply a positive or negative offset, in design units, to adjust the underlayer's scale.
 
-### Adjust DPI for Print Quality
-
-Control the output resolution by setting the scene's DPI property before export.
-
-```typescript highlight=highlight-dpi
-// Adjust the scene DPI for print-ready output
-// Higher DPI = better quality but larger file size
-engine.block.setFloat(scene, 'scene/dpi', 150);
-```
-
-Higher DPI values produce better quality output but result in larger file sizes. The default is 300 DPI, which is suitable for most print applications.
-
-### Enable High Compatibility Mode
-
-Enable high compatibility mode for consistent rendering across different PDF viewers.
-
-```typescript highlight=highlight-high-compatibility
-// Enable high compatibility mode for consistent rendering across PDF viewers
-// This rasterizes complex elements like gradients with transparency at scene DPI
-const pdfBlob = await engine.block.export(scene, {
-  mimeType: 'application/pdf',
-  exportPdfWithHighCompatibility: true
-});
-```
-
-When enabled, complex elements like gradients with transparency are rasterized at the scene's DPI setting instead of being embedded as native PDF objects. This ensures consistent appearance in viewers like Safari and macOS Preview but increases file size.
-
 ### PDF Performance Optimization
 
 The `exportPdfWithHighCompatibility` flag significantly impacts PDF export performance, especially for high-DPI content:
@@ -497,14 +96,14 @@ The `exportPdfWithHighCompatibility` flag significantly impacts PDF export perfo
 - Smaller file sizes (typically 30-40% reduction)
 - May have rendering issues in Safari/macOS Preview with gradients that use transparency
 
-```typescript
-const scene = engine.scene.get()!;
+```javascript
+const scene = engine.scene.get();
 
 // For maximum performance (test with your print workflow first)
 engine.block.setFloat(scene, 'scene/dpi', 150); // Reduce from default 300
 const blob = await engine.block.export(scene, {
   mimeType: 'application/pdf',
-  exportPdfWithHighCompatibility: false // Much faster
+  exportPdfWithHighCompatibility: false, // Much faster
 });
 ```
 
@@ -528,38 +127,12 @@ const blob = await engine.block.export(scene, {
 - Content has complex gradients with transparency
 - You cannot test with your print workflow before production
 
-### Add an Underlayer for Specialty Printing
-
-Add an underlayer for printing on non-white or transparent media like fabric or glass.
-
-```typescript highlight=highlight-spot-color
-// Define the underlayer spot color before export
-// RGB values (0.8, 0.8, 0.8) provide a preview representation
-engine.editor.setSpotColorRGB('RDG_WHITE', 0.8, 0.8, 0.8);
-```
-
-First define the spot color that will be used for the underlayer. The RGB values provide a preview representation in the editor.
-
-```typescript highlight=highlight-underlayer
-// Export with underlayer for special media printing
-const pdfBlob = await engine.block.export(scene, {
-  mimeType: 'application/pdf',
-  exportPdfWithHighCompatibility: true,
-  exportPdfWithUnderlayer: true,
-  underlayerSpotColorName: 'RDG_WHITE',
-  // Negative offset shrinks underlayer to prevent visible edges
-  underlayerOffset: -2.0
-});
-```
-
-The underlayer creates a solid background behind your design content. The negative offset shrinks the underlayer slightly to prevent visible edges around the printed output.
-
 ### Customizing PDF Output
 
-You can configure all PDF settings together when exporting.
+You can configure these settings when exporting:
 
-```ts
-const scene = engine.scene.get()!;
+```ts example=basic-scene marker=cesdk-init-after
+const scene = engine.scene.get();
 
 // Adjust the DPI to 72
 engine.block.setFloat(scene, 'scene/dpi', 72);
@@ -577,40 +150,17 @@ const blob = await engine.block.export(scene, {
   // Add an underlayer beneath the image content
   exportPdfWithUnderlayer: true,
   underlayerSpotColorName: 'RDG_WHITE',
-  underlayerOffset: -2.0
+  underlayerOffset: -2.0,
 });
 ```
 
-## Troubleshooting
-
-**PDF file size too large** — Reduce the scene DPI or disable high compatibility mode. Use JPEG compression for embedded images where quality loss is acceptable.
-
-**Gradients look different in some viewers** — Enable `exportPdfWithHighCompatibility` to rasterize gradients at the scene's DPI setting for consistent appearance across all PDF viewers.
-
-**Underlayer not visible in print** — Verify the spot color name matches your print vendor's configuration exactly. Check that the PDF wasn't flattened during post-processing.
-
-## API Reference
-
-| Method                                          | Description                                                                                                                                                                                          |
-| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `engine.block.export(block, options)`           | Export a block to a Blob with format options (`mimeType`, `exportPdfWithHighCompatibility`, `exportPdfWithUnderlayer`, `underlayerSpotColorName`, `underlayerOffset`, `targetWidth`, `targetHeight`) |
-| `engine.block.setFloat(block, property, value)` | Set a float property on a block (use `scene/dpi` to control PDF resolution)                                                                                                                          |
-| `engine.editor.setSpotColorRGB(name, r, g, b)`  | Define a spot color for underlayer printing                                                                                                                                                          |
-| `engine.scene.get()`                            | Get the current scene block ID                                                                                                                                                                       |
-| `engine.scene.getCurrentPage()`                 | Get the currently active page block                                                                                                                                                                  |
-| `cesdk.utils.downloadFile(blob, mimeType)`      | Download a Blob as a file                                                                                                                                                                            |
-
-## Next Steps
 
-- [Export Options](./export-save-publish/export/overview.md) — Explore all available export formats and configuration
-- [Size Limits](./export-save-publish/export/size-limits.md) — Handle large exports and memory constraints
-- [Export for Printing](./export-save-publish/for-printing.md) — Learn more about print-specific export settings
 
 ---
 
 ## More Resources
 
-- **[Vanilla JS/TS Documentation Index](https://img.ly/docs/cesdk/js.md)** - Browse all Vanilla JS/TS documentation
+- **[Node.js Documentation Index](https://img.ly/docs/cesdk/node.md)** - Browse all Node.js 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
+- **[Web Documentation](./node.md)** - Interactive documentation with examples
+- **[Support](mailto:support@img.ly)** - Contact IMG.LY support