@imgly/codesign-mcp 0.1.5 → 0.1.6

package/assets/docs/guide/text/language-support.md

@@ -1,92 +1,79 @@
-> 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) > [Create and Edit Text](./text.md) > [Language Support](./text/language-support.md)
 
 ---
 
-Support right-to-left text, complex scripts, and multilingual typography in
-your designs using CE.SDK's comprehensive text rendering capabilities.
-
-![Text and Language Support example showing multilingual text in different scripts](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
+Support right-to-left text, complex scripts, and multilingual typography programmatically in headless Node.js environments.
 
 > **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-text-language-support-browser)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-text-language-support-browser)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-text-language-support-browser/)
-
-CE.SDK provides built-in support for creating designs that work seamlessly across different languages and writing systems. The engine automatically handles text shaping, bidirectional layout, and script-specific rendering - supporting all Unicode characters, complex script ligatures, and mixed LTR/RTL content without additional configuration.
-
-```typescript file=@cesdk_web_examples/guides-text-language-support-browser/browser.ts reference-only
-import type {
-  EditorPlugin,
-  EditorPluginContext,
-  CreativeEngine
-} 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';
+>
+> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-text-language-support-server-js)
+>
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-text-language-support-server-js)
+
+CE.SDK provides comprehensive multilingual text support through the Block API. We can create text blocks in any language and the engine automatically handles complex text rendering including right-to-left scripts, ligatures, diacritical marks, and bidirectional text. This enables programmatic generation of designs for global audiences without UI complexity.
+
+```typescript file=@cesdk_web_examples/guides-text-language-support-server-js/server-js.ts reference-only
+import CreativeEngine from "@cesdk/node";
+import { config } from "dotenv";
+import { writeFileSync, mkdirSync, existsSync } from "fs";
+
+// Load environment variables
+config();
+
+/**
+ * CE.SDK Server Guide: Text and Language Support
+ */
 
 // Typeface definitions
 const ROBOTO_BOLD = {
-  name: 'Roboto',
+  name: "Roboto",
   fonts: [
     {
-      uri: 'https://fonts.gstatic.com/s/roboto/v30/KFOlCnqEu92Fr1MmEU9vAw.ttf',
-      subFamily: 'Bold',
-      weight: 'bold' as const,
-      style: 'normal' as const
-    }
-  ]
+      uri: "https://fonts.gstatic.com/s/roboto/v30/KFOlCnqEu92Fr1MmEU9vAw.ttf",
+      subFamily: "Bold",
+      weight: "bold" as const,
+      style: "normal" as const,
+    },
+  ],
 };
 
 const NOTO_NASKH_ARABIC = {
-  name: 'Noto Naskh Arabic',
+  name: "Noto Naskh Arabic",
   fonts: [
     {
-      uri: `${window.location.origin}${import.meta.env.BASE_URL}NotoNaskhArabic-Regular.ttf`,
-      subFamily: 'Regular',
-      weight: 'normal' as const,
-      style: 'normal' as const
-    }
-  ]
+      uri: new URL("./assets/NotoNaskhArabic-Regular.ttf", import.meta.url)
+        .href,
+      subFamily: "Regular",
+      weight: "normal" as const,
+      style: "normal" as const,
+    },
+  ],
 };
 
 const NOTO_SANS_KR = {
-  name: 'Noto Sans KR',
+  name: "Noto Sans KR",
   fonts: [
     {
-      uri: `${window.location.origin}${import.meta.env.BASE_URL}NotoSansKR-VariableFont_wght.ttf`,
-      subFamily: 'Regular',
-      weight: 'normal' as const,
-      style: 'normal' as const
-    }
-  ]
+      uri: new URL("./assets/NotoSansKR-VariableFont_wght.ttf", import.meta.url)
+        .href,
+      subFamily: "Regular",
+      weight: "normal" as const,
+      style: "normal" as const,
+    },
+  ],
 };
 
 // Layout configuration
 const LAYOUT = {
   PAGE: { width: 800, height: 1200 },
   TEXT: { x: 50, width: 700, defaultHeight: 140, fontSize: 20 },
-  SPACING: { gap: 16, startY: 50 }
+  SPACING: { gap: 16, startY: 50 },
 };
 
 // Typeface interface
@@ -95,11 +82,12 @@ interface Typeface {
   fonts: Array<{
     uri: string;
     subFamily: string;
-    weight: 'normal' | 'bold';
-    style: 'normal' | 'italic';
+    weight: "normal" | "bold";
+    style: "normal" | "italic";
   }>;
 }
 
+// Helper function to create text blocks
 function createTextBlock(
   engine: CreativeEngine,
   page: number,
@@ -107,211 +95,269 @@ function createTextBlock(
   typeface: Typeface,
   yPosition: number,
   height: number = LAYOUT.TEXT.defaultHeight,
-  alignment: 'Left' | 'Center' | 'Right' = 'Left'
+  alignment: "Left" | "Center" | "Right" = "Left",
 ): void {
-  const textBlock = engine.block.create('text');
-  engine.block.setString(textBlock, 'text/text', text);
+  const textBlock = engine.block.create("text");
+  engine.block.setString(textBlock, "text/text", text);
+  engine.block.appendChild(page, textBlock);
   engine.block.setPositionX(textBlock, LAYOUT.TEXT.x);
   engine.block.setPositionY(textBlock, yPosition);
   engine.block.setWidth(textBlock, LAYOUT.TEXT.width);
   engine.block.setHeight(textBlock, height);
-  engine.block.setFloat(textBlock, 'text/fontSize', LAYOUT.TEXT.fontSize);
+  engine.block.setFloat(textBlock, "text/fontSize", LAYOUT.TEXT.fontSize);
   engine.block.setTypeface(textBlock, typeface);
-  if (alignment !== 'Left') {
-    engine.block.setEnum(textBlock, 'text/horizontalAlignment', alignment);
+  if (alignment !== "Left") {
+    engine.block.setEnum(textBlock, "text/horizontalAlignment", alignment);
   }
-  engine.block.appendChild(page, textBlock);
 }
 
-/**
- * CE.SDK Plugin: Text Language Support Guide
- *
- * Demonstrates multilingual text support:
- * - RTL text rendering (Arabic)
- * - Complex script support (Korean)
- * - Custom font loading for Unicode coverage
- * - Text alignment for different writing directions
- */
-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');
-    }
-    // Add custom multilingual fonts to asset library
-    cesdk.engine.asset.addLocalSource('multilingual-typefaces');
-
-    cesdk.engine.asset.addAssetToSource('multilingual-typefaces', {
-      id: 'noto-naskh-arabic',
-      label: { en: 'Noto Naskh Arabic' },
-      payload: {
-        typeface: {
-          name: 'Noto Naskh Arabic',
-          fonts: [
-            {
-              uri: `${window.location.origin}${import.meta.env.BASE_URL}NotoNaskhArabic-Regular.ttf`,
-              subFamily: 'Regular',
-              weight: 'normal',
-              style: 'normal'
-            }
-          ]
-        }
-      }
-    });
-
-    cesdk.engine.asset.addAssetToSource('multilingual-typefaces', {
-      id: 'noto-sans-kr',
-      label: { en: 'Noto Sans KR' },
-      payload: {
-        typeface: {
-          name: 'Noto Sans KR',
-          fonts: [
-            {
-              uri: `${window.location.origin}${import.meta.env.BASE_URL}NotoSansKR-VariableFont_wght.ttf`,
-              subFamily: 'Regular',
-              weight: 'normal',
-              style: 'normal'
-            }
-          ]
-        }
-      }
-    });
-
-    cesdk.ui.updateAssetLibraryEntry('ly.img.typefaces', {
-      sourceIds: ['ly.img.typeface', 'multilingual-typefaces']
-    });
-
-    const engine = cesdk.engine;
-
-    // Create a blank scene with a white canvas
-    const scene = engine.scene.create();
-    const page = engine.block.create('page');
-    engine.block.setWidth(page, LAYOUT.PAGE.width);
-    engine.block.setHeight(page, LAYOUT.PAGE.height);
-    engine.block.appendChild(scene, page);
-    engine.scene.zoomToBlock(page);
-
-    // Create four text elements demonstrating multilingual font support
-    const textElements = [
-      { text: 'RTL Arabic', typeface: ROBOTO_BOLD, height: 140 },
-      {
-        text: 'هذا مثال.',
-        typeface: NOTO_NASKH_ARABIC,
-        height: 160,
-        alignment: 'Right' as const
-      },
-      { text: 'Korean', typeface: ROBOTO_BOLD, height: 140 },
-      { text: '이는 한 예입니다.', typeface: NOTO_SANS_KR, height: 140 }
-    ];
-
-    let currentY = LAYOUT.SPACING.startY;
-    for (const element of textElements) {
-      createTextBlock(
-        engine,
-        page,
-        element.text,
-        element.typeface,
-        currentY,
-        element.height,
-        element.alignment
-      );
-      currentY += element.height + LAYOUT.SPACING.gap;
-    }
+// Initialize CE.SDK engine in headless mode
+const engine = await CreativeEngine.init({
+  baseURL: process.env.IMGLY_LOCAL_ASSETS_URL,
+  // license: process.env.CESDK_LICENSE, // Optional (trial mode available)
+});
+
+// Create a design scene with specific page dimensions
+engine.scene.create("VerticalStack", {
+  page: { size: { width: LAYOUT.PAGE.width, height: LAYOUT.PAGE.height } },
+});
+const page = engine.block.findByType("page")[0];
+
+try {
+  // Create four text elements demonstrating multilingual font support
+  const textElements = [
+    { text: "RTL Arabic", typeface: ROBOTO_BOLD, height: 140 },
+    {
+      text: "هذا مثال.",
+      typeface: NOTO_NASKH_ARABIC,
+      height: 160,
+      alignment: "Right" as const,
+    },
+    { text: "Korean", typeface: ROBOTO_BOLD, height: 140 },
+    { text: "이는 한 예입니다.", typeface: NOTO_SANS_KR, height: 140 },
+  ];
+
+  let currentY = LAYOUT.SPACING.startY;
+  for (const element of textElements) {
+    createTextBlock(
+      engine,
+      page,
+      element.text,
+      element.typeface,
+      currentY,
+      element.height,
+      element.alignment,
+    );
+    currentY += element.height + LAYOUT.SPACING.gap;
+  }
+
+  // Zoom to show all content
+  engine.scene.zoomToBlock(page, { padding: 40 });
+
+  // Export the scene to PNG
+  const blob = await engine.block.export(page, { mimeType: "image/png" });
+  const buffer = Buffer.from(await blob.arrayBuffer());
+
+  // Ensure output directory exists
+  if (!existsSync("output")) {
+    mkdirSync("output");
   }
+
+  // Save to file
+  writeFileSync("output/text-language-support.png", buffer);
+  console.log(
+    "✅ Exported multilingual text to output/text-language-support.png",
+  );
+} finally {
+  engine.dispose();
 }
+```
+
+This guide covers headless rendering of RTL text, font configuration for different scripts, complex script support, and variable bindings for multilingual content.
+
+## Initialize Headless Engine
 
-export default Example;
+We initialize CE.SDK in headless mode for server-side text processing. The engine provides the same text rendering capabilities as the browser version but optimized for programmatic usage and image export.
+
+```typescript highlight-setup
+// Initialize CE.SDK engine in headless mode
+const engine = await CreativeEngine.init({
+  baseURL: process.env.IMGLY_LOCAL_ASSETS_URL,
+  // license: process.env.CESDK_LICENSE, // Optional (trial mode available)
+});
+
+// Create a design scene with specific page dimensions
+engine.scene.create("VerticalStack", {
+  page: { size: { width: LAYOUT.PAGE.width, height: LAYOUT.PAGE.height } },
+});
+const page = engine.block.findByType("page")[0];
 ```
 
-This guide covers how to work with multilingual text using both the built-in text UI and programmatic APIs for font configuration, text direction, and dynamic language content.
+The headless engine creates scenes programmatically and exports designs to PNG, PDF, or other formats without browser dependencies.
+
+## Right-to-Left Text Detection
+
+We create text blocks with RTL content and the engine automatically detects text direction based on Unicode character properties. CE.SDK implements the Unicode Bidirectional Algorithm (UAX #9) to handle RTL languages like Arabic, Hebrew, Persian, and Urdu.
 
-## Programmatic Font and Typeface Management
+```typescript highlight-apply-fonts
+  // Create four text elements demonstrating multilingual font support
+  const textElements = [
+    { text: "RTL Arabic", typeface: ROBOTO_BOLD, height: 140 },
+    {
+      text: "هذا مثال.",
+      typeface: NOTO_NASKH_ARABIC,
+      height: 160,
+      alignment: "Right" as const,
+    },
+    { text: "Korean", typeface: ROBOTO_BOLD, height: 140 },
+    { text: "이는 한 예입니다.", typeface: NOTO_SANS_KR, height: 140 },
+  ];
+
+  let currentY = LAYOUT.SPACING.startY;
+  for (const element of textElements) {
+    createTextBlock(
+      engine,
+      page,
+      element.text,
+      element.typeface,
+      currentY,
+      element.height,
+      element.alignment,
+    );
+    currentY += element.height + LAYOUT.SPACING.gap;
+  }
+```
 
-### Initialize CE.SDK
+The engine analyzes strong directional characters to determine text flow. Arabic and Hebrew letters establish right-to-left direction automatically. Mixed content with embedded LTR words renders correctly without additional configuration.
 
-For applications that need to manage multilingual text programmatically, we start by setting up CE.SDK and creating a scene.
+## Text Alignment for RTL Scripts
 
-```typescript highlight-setup
-// Create a blank scene with a white canvas
-const scene = engine.scene.create();
-const page = engine.block.create('page');
-engine.block.setWidth(page, LAYOUT.PAGE.width);
-engine.block.setHeight(page, LAYOUT.PAGE.height);
-engine.block.appendChild(scene, page);
-engine.scene.zoomToBlock(page);
+CE.SDK defaults to 'Auto' alignment, which automatically aligns text based on script direction. RTL scripts (Arabic, Hebrew) align right, while LTR scripts align left. This eliminates the need to manually configure alignment for different writing systems.
+
+```typescript highlight-text-alignment
+if (alignment !== "Left") {
+  engine.block.setEnum(textBlock, "text/horizontalAlignment", alignment);
+}
 ```
 
-This creates a blank 800×1200px canvas that we'll use for demonstrating multilingual text features.
+The alignment options:
 
-### Configuring Typefaces for Language Support
+- **'Auto'** (default) - Automatically aligns based on the text's script direction. RTL scripts align right, LTR scripts align left.
+- **'Left'** - Always align text to the left
+- **'Right'** - Always align text to the right
+- **'Center'** - Center-align text (language-neutral)
+
+With 'Auto' alignment, the Arabic text in our example automatically aligns to the right without explicit configuration:
+
+```typescript
+{
+  text: "هذا مثال.",
+  typeface: NOTO_NASKH_ARABIC,
+  height: 160,
+  // No alignment needed - Auto handles RTL automatically
+}
+```
+
+You can still override alignment when needed:
+
+```typescript
+{
+  text: "Centered Title",
+  typeface: ROBOTO_BOLD,
+  height: 80,
+  alignment: "Center" as const  // Override Auto for centering
+}
+```
+
+To check the effective alignment when 'Auto' is set, use `getTextEffectiveHorizontalAlignment()`:
+
+```typescript
+const effectiveAlignment = engine.block.getTextEffectiveHorizontalAlignment(textBlock);
+// Returns 'Left' or 'Right' based on text content, never 'Auto'
+```
+
+This approach simplifies multilingual templates - the same template works correctly for both LTR and RTL languages without alignment adjustments.
+
+## Font Configuration for Language Support
 
 To support specific languages and scripts, we define typefaces as constants with appropriate Unicode coverage. This example uses a constants-based approach for reusable typeface definitions that can be referenced throughout the code.
 
 ```typescript highlight-configure-fonts
 // Typeface definitions
 const ROBOTO_BOLD = {
-  name: 'Roboto',
+  name: "Roboto",
   fonts: [
     {
-      uri: 'https://fonts.gstatic.com/s/roboto/v30/KFOlCnqEu92Fr1MmEU9vAw.ttf',
-      subFamily: 'Bold',
-      weight: 'bold' as const,
-      style: 'normal' as const
-    }
-  ]
+      uri: "https://fonts.gstatic.com/s/roboto/v30/KFOlCnqEu92Fr1MmEU9vAw.ttf",
+      subFamily: "Bold",
+      weight: "bold" as const,
+      style: "normal" as const,
+    },
+  ],
 };
 
 const NOTO_NASKH_ARABIC = {
-  name: 'Noto Naskh Arabic',
+  name: "Noto Naskh Arabic",
   fonts: [
     {
-      uri: `${window.location.origin}${import.meta.env.BASE_URL}NotoNaskhArabic-Regular.ttf`,
-      subFamily: 'Regular',
-      weight: 'normal' as const,
-      style: 'normal' as const
-    }
-  ]
+      uri: new URL("./assets/NotoNaskhArabic-Regular.ttf", import.meta.url)
+        .href,
+      subFamily: "Regular",
+      weight: "normal" as const,
+      style: "normal" as const,
+    },
+  ],
 };
 
 const NOTO_SANS_KR = {
-  name: 'Noto Sans KR',
+  name: "Noto Sans KR",
   fonts: [
     {
-      uri: `${window.location.origin}${import.meta.env.BASE_URL}NotoSansKR-VariableFont_wght.ttf`,
-      subFamily: 'Regular',
-      weight: 'normal' as const,
-      style: 'normal' as const
-    }
-  ]
+      uri: new URL("./assets/NotoSansKR-VariableFont_wght.ttf", import.meta.url)
+        .href,
+      subFamily: "Regular",
+      weight: "normal" as const,
+      style: "normal" as const,
+    },
+  ],
 };
 ```
 
 The example defines three typefaces as named constants:
 
-- **ROBOTO_BOLD** - A web font for Latin script labels
-- **NOTO_NASKH_ARABIC** - Optimized for Arabic script with proper contextual forms
-- **NOTO_SANS_KR** - Variable font supporting Korean (Hangul) characters
+- **ROBOTO\_BOLD** - A web font for Latin script labels
+- **NOTO\_NASKH\_ARABIC** - Optimized for Arabic script with proper contextual forms
+- **NOTO\_SANS\_KR** - Variable font supporting Korean (Hangul) characters
 
 Each typeface includes:
 
 - **name** - The typeface family name
 - **fonts** - Array of font objects with URIs and styles
-- **uri** - Path to font file (TTF, OTF, WOFF2 formats supported)
+- **uri** - Path to font file (uses `new URL()` with `import.meta.url` for local assets)
 - **weight** - Font weight (normal, bold, or numeric values)
 - **style** - Font style (normal or italic)
 
+Defining typefaces as constants provides several benefits:
+
+- **Reusability** - Reference the same typeface multiple times without duplication
+- **Maintainability** - Update font URIs or properties in one location
+- **Type safety** - TypeScript can infer and validate typeface structure
+- **Clarity** - Clear semantic names indicate which script each font supports
+
 > **Note:** CE.SDK uses system fonts with Unicode support by default. Custom typefaces
 > are useful when you need specific brand fonts or enhanced coverage for
 > particular scripts.
 
-### Applying Fonts with a Helper Function
+## Applying Fonts Programmatically
+
+Instead of manually configuring each text block, this example uses a helper function and data-driven approach to apply fonts efficiently.
 
-The `createTextBlock()` function encapsulates all text block setup logic, reducing code duplication. Text elements are defined as an array and processed in a loop:
+### Helper Function
+
+The `createTextBlock()` function encapsulates all text block setup logic, reducing code duplication:
 
 ```typescript highlight-helper-function
+// Helper function to create text blocks
 function createTextBlock(
   engine: CreativeEngine,
   page: number,
@@ -319,189 +365,110 @@ function createTextBlock(
   typeface: Typeface,
   yPosition: number,
   height: number = LAYOUT.TEXT.defaultHeight,
-  alignment: 'Left' | 'Center' | 'Right' = 'Left'
+  alignment: "Left" | "Center" | "Right" = "Left",
 ): void {
-  const textBlock = engine.block.create('text');
-  engine.block.setString(textBlock, 'text/text', text);
+  const textBlock = engine.block.create("text");
+  engine.block.setString(textBlock, "text/text", text);
+  engine.block.appendChild(page, textBlock);
   engine.block.setPositionX(textBlock, LAYOUT.TEXT.x);
   engine.block.setPositionY(textBlock, yPosition);
   engine.block.setWidth(textBlock, LAYOUT.TEXT.width);
   engine.block.setHeight(textBlock, height);
-  engine.block.setFloat(textBlock, 'text/fontSize', LAYOUT.TEXT.fontSize);
+  engine.block.setFloat(textBlock, "text/fontSize", LAYOUT.TEXT.fontSize);
   engine.block.setTypeface(textBlock, typeface);
-  if (alignment !== 'Left') {
-    engine.block.setEnum(textBlock, 'text/horizontalAlignment', alignment);
+  if (alignment !== "Left") {
+    engine.block.setEnum(textBlock, "text/horizontalAlignment", alignment);
   }
-  engine.block.appendChild(page, textBlock);
 }
 ```
 
-```typescript highlight-apply-fonts
-// Create four text elements demonstrating multilingual font support
-const textElements = [
-  { text: 'RTL Arabic', typeface: ROBOTO_BOLD, height: 140 },
-  {
-    text: 'هذا مثال.',
-    typeface: NOTO_NASKH_ARABIC,
-    height: 160,
-    alignment: 'Right' as const
-  },
-  { text: 'Korean', typeface: ROBOTO_BOLD, height: 140 },
-  { text: '이는 한 예입니다.', typeface: NOTO_SANS_KR, height: 140 }
-];
-
-let currentY = LAYOUT.SPACING.startY;
-for (const element of textElements) {
-  createTextBlock(
-    engine,
-    page,
-    element.text,
-    element.typeface,
-    currentY,
-    element.height,
-    element.alignment
-  );
-  currentY += element.height + LAYOUT.SPACING.gap;
-}
-```
-
-This approach provides several benefits:
-
-- **DRY Principle** - Eliminates repetitive block setup code
-- **Easy to Extend** - Add new languages by appending to the configuration array
-- **Maintainable** - Change layout spacing or dimensions in one place
-
-The `engine.block.setTypeface()` method applies fonts at the block level. CE.SDK automatically uses the configured fonts to render text with proper glyph coverage for the languages in your content.
+This function handles:
 
-## Working with Right-to-Left (RTL) Text
+- Creating text blocks
+- Setting text content and styling
+- Applying typefaces
+- Positioning and sizing
+- Conditional alignment (only when not 'Left')
 
-### Understanding Automatic RTL Detection
+### Data-Driven Configuration
 
-CE.SDK automatically detects text direction based on Unicode character properties. When you create a text block with RTL content like Arabic or Hebrew, the engine analyzes the text and applies right-to-left rendering automatically.
+Text elements are defined as an array and processed in a loop:
 
 ```typescript highlight-apply-fonts
-// Create four text elements demonstrating multilingual font support
-const textElements = [
-  { text: 'RTL Arabic', typeface: ROBOTO_BOLD, height: 140 },
-  {
-    text: 'هذا مثال.',
-    typeface: NOTO_NASKH_ARABIC,
-    height: 160,
-    alignment: 'Right' as const
-  },
-  { text: 'Korean', typeface: ROBOTO_BOLD, height: 140 },
-  { text: '이는 한 예입니다.', typeface: NOTO_SANS_KR, height: 140 }
-];
-
-let currentY = LAYOUT.SPACING.startY;
-for (const element of textElements) {
-  createTextBlock(
-    engine,
-    page,
-    element.text,
-    element.typeface,
-    currentY,
-    element.height,
-    element.alignment
-  );
-  currentY += element.height + LAYOUT.SPACING.gap;
-}
-```
-
-The engine implements the Unicode Bidirectional Algorithm (UAX #9), which:
-
-- **Detects strong directional characters** - Characters like Arabic or Hebrew letters establish RTL flow
-- **Handles neutral characters** - Spaces, punctuation, and numbers display correctly in context
-- **Manages embedding** - LTR words (like English brand names) embed correctly within RTL text
-
-This automatic detection works for:
-
-- **Arabic** - Including Persian and Urdu variants
-- **Hebrew** - Modern and Biblical Hebrew
-- **Mixed content** - English or other LTR text within RTL paragraphs
-
-### Text Alignment for RTL Languages
-
-CE.SDK now defaults to 'Auto' alignment, which automatically aligns text based on script direction. RTL scripts (Arabic, Hebrew) align right, while LTR scripts align left. This eliminates the need to manually configure alignment for different writing systems.
-
-```typescript highlight-text-alignment
-if (alignment !== 'Left') {
-  engine.block.setEnum(textBlock, 'text/horizontalAlignment', alignment);
-}
+  // Create four text elements demonstrating multilingual font support
+  const textElements = [
+    { text: "RTL Arabic", typeface: ROBOTO_BOLD, height: 140 },
+    {
+      text: "هذا مثال.",
+      typeface: NOTO_NASKH_ARABIC,
+      height: 160,
+      alignment: "Right" as const,
+    },
+    { text: "Korean", typeface: ROBOTO_BOLD, height: 140 },
+    { text: "이는 한 예입니다.", typeface: NOTO_SANS_KR, height: 140 },
+  ];
+
+  let currentY = LAYOUT.SPACING.startY;
+  for (const element of textElements) {
+    createTextBlock(
+      engine,
+      page,
+      element.text,
+      element.typeface,
+      currentY,
+      element.height,
+      element.alignment,
+    );
+    currentY += element.height + LAYOUT.SPACING.gap;
+  }
 ```
 
-The alignment options:
-
-- **'Auto'** (default) - Automatically aligns based on the text's script direction. RTL scripts align right, LTR scripts align left.
-- **'Left'** - Always align text to the left
-- **'Right'** - Always align text to the right
-- **'Center'** - Center-align text (language-neutral)
-
-With 'Auto' alignment, the Arabic text in our example automatically aligns to the right without explicit configuration:
+This approach uses three key patterns:
 
-```typescript
-{
-  text: 'هذا مثال.',
-  typeface: NOTO_NASKH_ARABIC,
-  height: 160,
-  // No alignment needed - Auto handles RTL automatically
-}
-```
+**1. Helper Function** - The `createTextBlock()` function creates and configures a text block with a single call. As a standalone function (not a class method), it takes the engine instance as the first parameter. Other parameters include text content, typeface, position, height, and optional alignment.
 
-You can still override alignment when needed:
+**2. Data-Driven Configuration** - Text elements are defined as an array of objects specifying content, typeface, height, and alignment. This declarative approach makes it easy to see all elements at a glance and modify them as needed.
 
-```typescript
-{
-  text: 'Centered Title',
-  typeface: ROBOTO_BOLD,
-  height: 80,
-  alignment: 'Center' as const  // Override Auto for centering
-}
-```
+**3. Loop-Based Creation** - A for loop iterates through the configuration array, automatically calculating Y positions and creating each text block. The `currentY` variable tracks vertical position and updates after each element.
 
-To check the effective alignment when 'Auto' is set, use `getTextEffectiveHorizontalAlignment()`:
+Benefits of this pattern:
 
-```typescript
-const effectiveAlignment =
-  engine.block.getTextEffectiveHorizontalAlignment(textBlock);
-// Returns 'Left' or 'Right' based on text content, never 'Auto'
-```
+- **DRY Principle** - Eliminates repetitive block setup code
+- **Easy to Extend** - Add new languages by appending to the configuration array
+- **Maintainable** - Change layout spacing or dimensions in one place
+- **Educational** - Demonstrates best practices for managing multiple similar elements
 
-This approach simplifies multilingual templates - the same template works correctly for both LTR and RTL languages without alignment adjustments.
+The `engine.block.setTypeface()` method applies fonts at the block level. CE.SDK automatically uses the configured fonts to render text with proper glyph coverage for the languages in your content.
 
 ## Complex Script Support
 
-CE.SDK automatically handles complex script features without requiring additional configuration. The text engine provides:
+CE.SDK automatically handles complex script features without additional configuration. The text engine provides script-aware text shaping that applies:
 
 ### Arabic Script Features
 
-When rendering Arabic text, the engine automatically applies:
+The engine automatically applies Arabic-specific rendering:
 
 - **Contextual letter forms** - Letters change shape based on position (initial, medial, final, isolated)
 - **Required ligatures** - Mandatory character combinations render as single glyphs
 - **Diacritical marks** - Tashkeel marks position correctly above and below letters
 - **Kashida** - Text justification through letter elongation
 
-These features work automatically when you use fonts that include the necessary OpenType tables.
-
 ### Other Complex Scripts
 
-The text engine similarly supports other writing systems:
+The text engine supports additional writing systems:
 
 - **Devanagari** (Hindi, Sanskrit) - Conjunct formations and half-forms
 - **Thai** - Vowel and tone mark positioning above and below base characters
 - **Japanese** - Kanji, hiragana, and katakana rendering
 - **Southeast Asian scripts** - Khmer subscripts, Myanmar ligatures
 
-All complex script features are applied automatically based on Unicode properties and font capabilities.
-
-## Creating Multilingual Design Templates
+All complex script features apply automatically based on Unicode properties and font capabilities.
 
-### Using Variables for Multilingual Content
+## Variables for Multilingual Content
 
-For designs that need to display different language content dynamically, use variable bindings. Variables enable you to switch languages while maintaining proper text rendering for each script.
+We use variable bindings to create dynamic multilingual content. Variables enable language switching while maintaining proper text rendering for each script.
 
-Benefits of using variables:
+Variable benefits:
 
 - **Dynamic language switching** - Update variable values to change content language
 - **Consistent formatting** - Text styling and layout remain stable across languages
@@ -509,43 +476,61 @@ Benefits of using variables:
 
 Variables are particularly useful for:
 
-- **Localized marketing materials** - Same design, different language content
+- **Localized materials** - Same design, different language content
 - **A/B testing** - Test messaging across languages
 - **Regional campaigns** - Deploy region-specific content from a single template
 
-### Template Design Considerations
+## Mixed-Direction Text
 
-When designing multilingual templates, account for:
+The engine handles mixed-direction text automatically through the Unicode Bidirectional Algorithm. LTR and RTL content coexist correctly within the same text block.
 
-- **Text expansion** - Some languages require 30-50% more space than English
-- **Direction changes** - RTL layouts may need mirrored designs
-- **Font availability** - Ensure typefaces cover all target scripts
-- **Line height** - Scripts with diacritics may need additional vertical space
+When we create text mixing English (LTR) with Arabic or Hebrew (RTL), the engine:
 
-Test templates with representative content in all target languages to verify layout works correctly.
-
-## Font Fallback and Character Coverage
-
-### Font Selection Priority
+- **Detects strong directional characters** - Establishes text flow based on Unicode BiDi class
+- **Handles neutral characters** - Spaces, punctuation, and numbers display correctly in context
+- **Manages embedding** - LTR words embed correctly within RTL paragraphs
 
-When rendering text, CE.SDK follows a fallback chain to ensure all characters display correctly:
+The engine resolves bidirectional layout automatically without requiring Unicode directional formatting characters.
 
-1. **Primary typeface** - The explicitly assigned font
-2. **System fonts** - Fonts available on the user's system
-3. **Fallback glyphs** - Generic replacement characters when no font contains the glyph
+## Exporting Multilingual Designs
 
-This fallback system ensures text always renders, even when fonts lack specific characters.
+We export scenes to various formats using `engine.block.export()`. The headless engine supports PNG, JPEG, PDF, and other formats for programmatic image generation.
 
-### Ensuring Complete Character Coverage
+```typescript highlight-export
+  // Export the scene to PNG
+  const blob = await engine.block.export(page, { mimeType: "image/png" });
+  const buffer = Buffer.from(await blob.arrayBuffer());
 
-To avoid missing glyph issues:
+  // Ensure output directory exists
+  if (!existsSync("output")) {
+    mkdirSync("output");
+  }
 
-- **Use comprehensive typefaces** - Noto fonts family provides extensive Unicode coverage
-- **Test with target languages** - Verify fonts include required scripts before deployment
-- **Configure fallback stacks** - Define multiple typefaces for comprehensive coverage
-- **Check font formats** - Ensure fonts include OpenType layout tables for complex scripts
+  // Save to file
+  writeFileSync("output/text-language-support.png", buffer);
+  console.log(
+    "✅ Exported multilingual text to output/text-language-support.png",
+  );
+```
 
-Testing with representative text samples in all target languages helps identify coverage gaps before production.
+Exported images preserve all multilingual text rendering including RTL layout, complex scripts, and mixed-direction content. This enables automated generation of localized designs for global markets.
+
+## API Reference
+
+| Method | Purpose |
+|--------|---------|
+| `engine.block.create('text')` | Create text block for multilingual content |
+| `engine.block.setString(id, 'text/text', value)` | Set text content in any language |
+| `engine.block.getString(id, 'text/text')` | Get text content |
+| `engine.block.setEnum(id, 'text/horizontalAlignment', value)` | Set horizontal text alignment (Auto, Left, Right, Center) |
+| `engine.block.getEnum(id, 'text/horizontalAlignment')` | Get horizontal text alignment |
+| `engine.block.getTextEffectiveHorizontalAlignment(id)` | Get resolved alignment (Auto resolves to Left or Right) |
+| `engine.block.setTypeface()` | Apply typeface to text block |
+| `engine.block.getTypeface()` | Get current typeface of text block |
+| `engine.block.setFloat(id, 'text/fontSize', value)` | Set font size |
+| `engine.block.setTextColor()` | Set color for character range |
+| `engine.variable.setString()` | Create or update text variable for multilingual content |
+| `engine.block.export()` | Export block or scene to various formats |
 
 ## Troubleshooting
 
@@ -553,10 +538,10 @@ Testing with representative text samples in all target languages helps identify
 
 **Issue**: Characters render as replacement glyphs (□ or ?) instead of the intended script.
 
-**Solution**: The selected font lacks glyphs for the text content. Use fonts with appropriate Unicode coverage:
+**Solution**: The font lacks glyphs for the text content. Use fonts with appropriate Unicode coverage:
 
 - Verify font supports required Unicode blocks
-- Test with Noto fonts family for comprehensive coverage
+- Use Noto fonts family for comprehensive coverage
 - Check font file format compatibility (TTF, OTF, WOFF2)
 - Ensure font files are accessible with correct URIs
 
@@ -569,36 +554,38 @@ Testing with representative text samples in all target languages helps identify
 - Verify alignment is set to 'Auto' (default) or explicitly 'Right'
 - Use `engine.block.getTextEffectiveHorizontalAlignment(block)` to check resolved alignment
 - Verify font includes bidirectional layout features
-- Check that font supports RTL scripts
 - Test with known RTL-compatible fonts (Noto Sans Arabic, Noto Sans Hebrew)
+- Check that text content includes strong RTL directional characters
 
-### Ligatures or Diacritics Display Incorrectly
+### Complex Script Features Display Incorrectly
 
-**Issue**: Complex script features like ligatures or diacritical marks appear disconnected or mispositioned.
+**Issue**: Ligatures or diacritical marks appear disconnected or mispositioned.
 
 **Solution**: Use fonts specifically designed for the target script:
 
 - Verify font includes GSUB/GPOS OpenType tables
 - Use script-specific Noto fonts
 - Check font includes required OpenType layout features
-- Test with fonts known to support the script
+- Ensure font supports the specific script's shaping requirements
+
+### Variable Substitution Not Working
+
+**Issue**: Variable placeholders like `{{variable}}` display literally instead of substituting values.
 
-### Mixed-Direction Text Layout Issues
+**Solution**: Ensure variables are defined before creating text blocks:
 
-**Issue**: Text with both LTR and RTL content displays incorrectly.
+- Call `engine.variable.setString()` before setting text content
+- Verify variable names match exactly (case-sensitive)
+- Check variable placeholders use double curly braces `{{name}}`
+- Confirm variables are set in the same engine instance
 
-**Solution**: The engine's automatic bidirectional handling should resolve most cases. If issues persist:
 
-- Test with different fonts to verify bidirectional support
-- Use Unicode directional formatting characters sparingly (RLM U+200F, LRM U+200E)
-- Verify text editor preserves directional markers
-- Check that text content includes proper strong directional characters
 
 ---
 
 ## 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