@imgly/codesign-mcp 0.1.5 → 0.1.6

package/assets/docs/guide/concepts/design-units.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:** [Concepts](./concepts.md) > [Design Units](./concepts/design-units.md)
 
@@ -7,42 +7,27 @@
 Control measurement systems for precise physical dimensions—create print-ready
 documents with millimeter or inch units and configurable DPI for export quality.
 
-![Design Units example showing an A4 document configured with millimeter units](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-concepts-design-units-browser)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-concepts-design-units-browser)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-concepts-design-units-browser/)
+>
+> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-concepts-design-units-server-js)
+>
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-concepts-design-units-server-js)
 
 Design units determine the coordinate system for all layout values in CE.SDK—positions, sizes, and margins. The engine supports three unit types: **Pixel** for screen-based designs, **Millimeter** for metric print dimensions, and **Inch** for imperial print formats.
 
-```typescript file=@cesdk_web_examples/guides-concepts-design-units-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';
+```typescript file=@cesdk_web_examples/guides-concepts-design-units-server-js/server-js.ts reference-only
+import CreativeEngine from '@cesdk/node';
+import { config } from 'dotenv';
+
+// Load environment variables from .env file
+config();
 
 /**
- * CE.SDK Plugin: Design Units Guide
+ * CE.SDK Server Example: Design Units Guide
  *
  * Demonstrates working with design units in CE.SDK:
  * - Understanding unit types (Pixel, Millimeter, Inch)
@@ -50,60 +35,19 @@ import packageJson from './package.json';
  * - Configuring DPI for print output
  * - Setting up print-ready dimensions
  */
-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());
+async function main(): Promise<void> {
+  // Initialize the headless Creative Engine
+  const engine = await CreativeEngine.init({
+    baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
+    // license: process.env.CESDK_LICENSE,
+  });
 
-    // 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: 210, height: 297, unit: 'Pixel' }
-    });
-
-    const engine = cesdk.engine;
-
-    // Get the current scene
-    const scene = engine.scene.get();
-    if (scene === null) {
-      throw new Error('No scene available');
-    }
+  try {
+    // Create a new scene
+    const scene = engine.scene.create();
 
     // Get the current design unit
     const currentUnit = engine.scene.getDesignUnit();
-    // eslint-disable-next-line no-console
     console.log('Current design unit:', currentUnit); // 'Pixel' by default
 
     // Set design unit to Millimeter for print workflow
@@ -111,7 +55,6 @@ class Example implements EditorPlugin {
 
     // Verify the change
     const newUnit = engine.scene.getDesignUnit();
-    // eslint-disable-next-line no-console
     console.log('Design unit changed to:', newUnit); // 'Millimeter'
 
     // Set DPI to 300 for print-quality exports
@@ -120,16 +63,19 @@ class Example implements EditorPlugin {
 
     // Verify the DPI setting
     const dpi = engine.block.getFloat(scene, 'scene/dpi');
-    // eslint-disable-next-line no-console
     console.log('DPI set to:', dpi); // 300
 
-    // Get the page and set A4 dimensions (210 x 297 mm)
-    const page = engine.block.findByType('page')[0];
+    // Create a page and set A4 dimensions (210 x 297 mm)
+    const page = engine.block.create('page');
+    engine.block.appendChild(scene, page);
+
+    // Set page to A4 size in millimeters
+    engine.block.setWidth(page, 210);
+    engine.block.setHeight(page, 297);
 
     // Verify dimensions
     const pageWidth = engine.block.getWidth(page);
     const pageHeight = engine.block.getHeight(page);
-    // eslint-disable-next-line no-console
     console.log(`Page dimensions: ${pageWidth}mm x ${pageHeight}mm`);
 
     // Create a text block with millimeter dimensions
@@ -153,29 +99,28 @@ class Example implements EditorPlugin {
 
     // Demonstrate unit comparison
     // At 300 DPI: 1 inch = 300 pixels, 1 mm = ~11.81 pixels
-    // eslint-disable-next-line no-console
     console.log('Unit comparison at 300 DPI:');
-    // eslint-disable-next-line no-console
     console.log(
       '- A4 width (210mm) will export as',
       210 * (300 / 25.4),
       'pixels'
     );
-    // eslint-disable-next-line no-console
     console.log(
       '- A4 height (297mm) will export as',
       297 * (300 / 25.4),
       'pixels'
     );
 
-    // eslint-disable-next-line no-console
     console.log(
-      'Design units guide initialized. Scene configured for A4 print output.'
+      'Design units guide completed. Scene configured for A4 print output.'
     );
+  } finally {
+    // Always dispose the engine to free resources
+    engine.dispose();
   }
 }
 
-export default Example;
+main().catch(console.error);
 ```
 
 This guide covers how to get and set design units, configure DPI for export quality, and set up scenes for specific physical dimensions like A4 paper.
@@ -201,16 +146,12 @@ For pixel-based scenes, DPI primarily affects font size conversions since font s
 Use `engine.scene.getDesignUnit()` to retrieve the current scene's design unit. This returns one of three values: `'Pixel'`, `'Millimeter'`, or `'Inch'`.
 
 ```typescript highlight-get-design-unit
-// Get the current scene
-const scene = engine.scene.get();
-if (scene === null) {
-  throw new Error('No scene available');
-}
+    // Create a new scene
+    const scene = engine.scene.create();
 
-// Get the current design unit
-const currentUnit = engine.scene.getDesignUnit();
-// eslint-disable-next-line no-console
-console.log('Current design unit:', currentUnit); // 'Pixel' by default
+    // Get the current design unit
+    const currentUnit = engine.scene.getDesignUnit();
+    console.log('Current design unit:', currentUnit); // 'Pixel' by default
 ```
 
 ## Setting the Design Unit
@@ -218,13 +159,12 @@ console.log('Current design unit:', currentUnit); // 'Pixel' by default
 Use `engine.scene.setDesignUnit()` to change the measurement system. When you change the design unit, CE.SDK automatically converts existing layout values to maintain visual appearance.
 
 ```typescript highlight-set-design-unit
-// Set design unit to Millimeter for print workflow
-engine.scene.setDesignUnit('Millimeter');
+    // Set design unit to Millimeter for print workflow
+    engine.scene.setDesignUnit('Millimeter');
 
-// Verify the change
-const newUnit = engine.scene.getDesignUnit();
-// eslint-disable-next-line no-console
-console.log('Design unit changed to:', newUnit); // 'Millimeter'
+    // Verify the change
+    const newUnit = engine.scene.getDesignUnit();
+    console.log('Design unit changed to:', newUnit); // 'Millimeter'
 ```
 
 ## Configuring DPI
@@ -232,14 +172,13 @@ console.log('Design unit changed to:', newUnit); // 'Millimeter'
 Access DPI through the scene's `scene/dpi` property. For print workflows, 300 DPI is the standard for high-quality output.
 
 ```typescript highlight-configure-dpi
-// Set DPI to 300 for print-quality exports
-// Higher DPI produces higher resolution output
-engine.block.setFloat(scene, 'scene/dpi', 300);
-
-// Verify the DPI setting
-const dpi = engine.block.getFloat(scene, 'scene/dpi');
-// eslint-disable-next-line no-console
-console.log('DPI set to:', dpi); // 300
+    // Set DPI to 300 for print-quality exports
+    // Higher DPI produces higher resolution output
+    engine.block.setFloat(scene, 'scene/dpi', 300);
+
+    // Verify the DPI setting
+    const dpi = engine.block.getFloat(scene, 'scene/dpi');
+    console.log('DPI set to:', dpi); // 300
 ```
 
 DPI affects different aspects depending on the design unit:
@@ -252,14 +191,18 @@ DPI affects different aspects depending on the design unit:
 For print workflows, combine `setDesignUnit()` with appropriate DPI and page dimensions. Here's how to set up an A4 document ready for print export:
 
 ```typescript highlight-set-page-dimensions
-// Get the page and set A4 dimensions (210 x 297 mm)
-const page = engine.block.findByType('page')[0];
-
-// Verify dimensions
-const pageWidth = engine.block.getWidth(page);
-const pageHeight = engine.block.getHeight(page);
-// eslint-disable-next-line no-console
-console.log(`Page dimensions: ${pageWidth}mm x ${pageHeight}mm`);
+    // Create a page and set A4 dimensions (210 x 297 mm)
+    const page = engine.block.create('page');
+    engine.block.appendChild(scene, page);
+
+    // Set page to A4 size in millimeters
+    engine.block.setWidth(page, 210);
+    engine.block.setHeight(page, 297);
+
+    // Verify dimensions
+    const pageWidth = engine.block.getWidth(page);
+    const pageHeight = engine.block.getHeight(page);
+    console.log(`Page dimensions: ${pageWidth}mm x ${pageHeight}mm`);
 ```
 
 ## Font Sizes and Design Units
@@ -267,24 +210,24 @@ console.log(`Page dimensions: ${pageWidth}mm x ${pageHeight}mm`);
 Font sizes are always specified in points (`pt`), regardless of the scene's design unit. The DPI setting affects how points convert to pixels for rendering.
 
 ```typescript highlight-create-text-block
-// Create a text block with millimeter dimensions
-const textBlock = engine.block.create('text');
-engine.block.appendChild(page, textBlock);
-
-// Position text at 20mm from left, 30mm from top
-engine.block.setPositionX(textBlock, 20);
-engine.block.setPositionY(textBlock, 30);
-
-// Set text block size to 170mm x 50mm
-engine.block.setWidth(textBlock, 170);
-engine.block.setHeight(textBlock, 50);
-
-// Add content to the text block
-engine.block.setString(
-  textBlock,
-  'text/text',
-  'This A4 document uses millimeter units with 300 DPI for print-ready output.'
-);
+    // Create a text block with millimeter dimensions
+    const textBlock = engine.block.create('text');
+    engine.block.appendChild(page, textBlock);
+
+    // Position text at 20mm from left, 30mm from top
+    engine.block.setPositionX(textBlock, 20);
+    engine.block.setPositionY(textBlock, 30);
+
+    // Set text block size to 170mm x 50mm
+    engine.block.setWidth(textBlock, 170);
+    engine.block.setHeight(textBlock, 50);
+
+    // Add content to the text block
+    engine.block.setString(
+      textBlock,
+      'text/text',
+      'This A4 document uses millimeter units with 300 DPI for print-ready output.'
+    );
 ```
 
 When DPI changes, text blocks automatically adjust their rendered size to maintain visual consistency.
@@ -296,12 +239,17 @@ The relationship between design units and export resolution is important for pri
 ```typescript highlight-compare-units
 // Demonstrate unit comparison
 // At 300 DPI: 1 inch = 300 pixels, 1 mm = ~11.81 pixels
-// eslint-disable-next-line no-console
 console.log('Unit comparison at 300 DPI:');
-// eslint-disable-next-line no-console
-console.log('- A4 width (210mm) will export as', 210 * (300 / 25.4), 'pixels');
-// eslint-disable-next-line no-console
-console.log('- A4 height (297mm) will export as', 297 * (300 / 25.4), 'pixels');
+console.log(
+  '- A4 width (210mm) will export as',
+  210 * (300 / 25.4),
+  'pixels'
+);
+console.log(
+  '- A4 height (297mm) will export as',
+  297 * (300 / 25.4),
+  'pixels'
+);
 ```
 
 At 300 DPI:
@@ -323,11 +271,13 @@ Font sizes in points auto-adjust based on DPI. If text looks incorrect, verify t
 
 CE.SDK preserves visual appearance during unit conversion. If positions seem unexpected, check the original coordinate values—the numeric values change but visual positions should remain stable.
 
+
+
 ---
 
 ## 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