@imgly/codesign-mcp 0.1.5 → 0.1.6

package/assets/docs/guide/open-the-editor/import-design/from-indesign.md

@@ -1,453 +1,351 @@
-> 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) > [Open the Editor](./open-the-editor.md) > [Import a Design](./open-the-editor/import-design.md) > [From InDesign](./open-the-editor/import-design/from-indesign.md)
 
 ---
 
-Import Adobe InDesign (IDML) files into CE.SDK, converting them into editable scenes while preserving text, shapes, images, and positioning.
+Import Adobe InDesign (IDML) files into CE.SDK using Node.js, converting them into scene archives for distribution or further processing.
 
 > **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-open-the-editor-import-design-from-indesign-browser)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-open-the-editor-import-design-from-indesign-browser)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-open-the-editor-import-design-from-indesign-browser/)
-
-![Import from InDesign](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
-
-The `@imgly/idml-importer` package converts InDesign IDML files into CE.SDK scene format, preserving design structure for editing or export. This guide focuses on enabling end-users to upload their own IDML files directly in the browser and load them into the CE.SDK editor. For batch conversion of template libraries at build-time, see the [server guide](./open-the-editor/import-design/from-indesign.md).
+>
+> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-open-the-editor-import-design-from-indesign-server-js)
+>
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-open-the-editor-import-design-from-indesign-server-js)
 
-```typescript file=@cesdk_web_examples/guides-open-the-editor-import-design-from-indesign-browser/browser.ts reference-only
-import type { EditorPlugin, EditorPluginContext } from '@cesdk/cesdk-js';
+The `@imgly/idml-importer` package converts InDesign IDML files into CE.SDK scene format, preserving design structure for distribution or further processing. This guide focuses on batch converting IDML template files at build-time using Node.js—ideal for migrating existing template libraries or integrating with CI/CD pipelines. For enabling end-user uploads in the browser, see the [browser guide](./open-the-editor/import-design/from-indesign.md).
 
-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 type {
-  AssetQueryData,
-  AssetResult,
-  AssetsQueryResult
-} from '@cesdk/engine';
+```typescript file=@cesdk_web_examples/guides-open-the-editor-import-design-from-indesign-server-js/server-js.ts reference-only
+import CreativeEngine from '@cesdk/node';
 import type { TypefaceResolver } from '@imgly/idml-importer';
-import { IDMLParser, addGfontsAssetLibrary } from '@imgly/idml-importer';
-import packageJson from './package.json';
+import {
+  IDMLParser,
+  addGfontsAssetLibrary,
+  createPdfEmbeddedImporter
+} from '@imgly/idml-importer';
+import { PDFParser } from '@imgly/pdf-importer';
+import { JSDOM } from 'jsdom';
+import { config } from 'dotenv';
+import { promises as fs } from 'fs';
+import { join, basename } from 'path';
+
+// Load environment variables
+config();
+
+// Optional: Create a custom font resolver for advanced font mapping
+// Use this when you need to map InDesign fonts to specific alternatives,
+// use enterprise fonts, or implement custom fallback logic
+const customFontResolver: TypefaceResolver = async (fontParams, engine) => {
+  const { family, style, weight } = fontParams;
+
+  // Define font mappings from InDesign fonts to available alternatives
+  const fontMappings: Record<string, string> = {
+    Arial: 'Open Sans',
+    Helvetica: 'Inter',
+    'Helvetica Neue': 'Inter',
+    'Times New Roman': 'Lora',
+    Georgia: 'Merriweather'
+  };
+
+  // Use mapped font or original family name
+  const targetFamily = fontMappings[family] || family;
+
+  // Search for the font in available typefaces
+  const result = await engine.asset.findAssets('ly.img.typeface', {
+    query: targetFamily,
+    page: 0,
+    perPage: 10
+  });
+
+  if (result.assets.length === 0) {
+    console.warn(`Font "${family}" not found, using default fallback`);
+    return null; // Let the parser use its default fallback
+  }
+
+  // Get the typeface from the asset payload
+  const asset = result.assets[0];
+  const typeface = asset.payload?.typeface;
+  if (!typeface) return null;
+
+  // Find the best matching font variant (weight and style)
+  const matchingFont =
+    typeface.fonts.find(
+      (f: { weight?: string; style?: string }) =>
+        f.weight === weight && f.style === style
+    ) ||
+    typeface.fonts.find((f: { weight?: string }) => f.weight === weight) ||
+    typeface.fonts[0];
+
+  return { typeface, font: matchingFont };
+};
 
 /**
- * CE.SDK Plugin: Import from InDesign Guide
- *
- * Demonstrates how to import Adobe InDesign IDML files into CE.SDK:
- * - Creating a custom asset source for IDML templates
- * - Adding a custom nav bar button to upload IDML files
- * - Parsing IDML files with the IDML importer
- * - Displaying import warnings to users
- *
- * Note: In-library file uploads for custom asset sources will be supported
- * in a future CE.SDK release. This guide demonstrates using a custom nav bar
- * button as an alternative approach for user file uploads.
+ * Convert a single IDML file to CE.SDK scene formats
+ * Outputs both an archive file and a scene string with stable URLs
  */
-
-// Asset source ID for IDML library
-const IDML_SOURCE_ID = 'idml-files';
-
-// Base URL for IDML template files
-const IDML_BASE_URL =
-  'https://staticimgly.com/imgly/docs-reference-files-temp/indesign-template-import';
-
-// Sample IDML files for the asset library
-// These files are hosted on the IMG.LY CDN from the showcases-app public folder
-const SAMPLE_IDML_FILES: AssetResult[] = [
-  {
-    id: 'idml-socialmedia',
-    label: 'Social Media',
-    tags: ['sample', 'idml', 'social', 'marketing'],
-    meta: {
-      uri: `${IDML_BASE_URL}/socialmedia.idml`,
-      thumbUri: `${IDML_BASE_URL}/socialmedia-thumb@2x.png`,
-      mimeType: 'application/vnd.adobe.indesign-idml-package',
-      width: 1080,
-      height: 1080
-    }
-  },
-  {
-    id: 'idml-poster',
-    label: 'Poster',
-    tags: ['sample', 'idml', 'poster', 'print'],
-    meta: {
-      uri: `${IDML_BASE_URL}/poster.idml`,
-      thumbUri: `${IDML_BASE_URL}/poster-thumb@2x.png`,
-      mimeType: 'application/vnd.adobe.indesign-idml-package',
-      width: 1240,
-      height: 1754
-    }
-  },
-  {
-    id: 'idml-postcard',
-    label: 'Postcard',
-    tags: ['sample', 'idml', 'postcard', 'print'],
-    meta: {
-      uri: `${IDML_BASE_URL}/postcard.idml`,
-      thumbUri: `${IDML_BASE_URL}/postcard-thumb@2x.png`,
-      mimeType: 'application/vnd.adobe.indesign-idml-package',
-      width: 1050,
-      height: 600
+async function convertIdml(
+  engine: InstanceType<typeof CreativeEngine>,
+  idmlPath: string,
+  outputDir: string
+): Promise<{
+  archivePath: string;
+  sceneStringPath: string;
+  pageCount: number;
+}> {
+  // Read the IDML file
+  const idmlBuffer = await fs.readFile(idmlPath);
+
+  // Parse the IDML file using JSDOM for XML parsing.
+  // Server-side import requires JSDOM since DOMParser is browser-only.
+  // The addGfontsAssetLibrary() call enables automatic font matching.
+  // Register the PDF embedded-importer adapter explicitly so any
+  // <PDF>/.ai content inside the IDML imports as editable CE.SDK blocks
+  // via @imgly/pdf-importer (rather than a placeholder image).
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const parser = await IDMLParser.fromFile(
+    engine as any,
+    idmlBuffer.buffer,
+    (content: string) =>
+      new JSDOM(content, {
+        contentType: 'text/xml',
+        storageQuota: 10000000,
+        url: 'http://localhost'
+      }).window.document,
+    {
+      fontResolver: customFontResolver,
+      embeddedImporters: [createPdfEmbeddedImporter(PDFParser)]
     }
+  );
+  await parser.parse();
+
+  // Verify pages were imported successfully
+  const pages = engine.scene.getPages();
+  if (pages.length === 0) {
+    throw new Error(`No pages imported from IDML file: ${idmlPath}`);
+  }
+  console.log(`  Imported ${pages.length} page(s)`);
+
+  // Generate output filename from input filename
+  const inputName = basename(idmlPath, '.idml');
+  const archivePath = join(outputDir, `${inputName}.cesdk`);
+
+  // Save as scene archive
+  const archive = await engine.scene.saveToArchive();
+  const archiveBuffer = Buffer.from(await archive.arrayBuffer());
+  await fs.writeFile(archivePath, archiveBuffer);
+
+  // Optional: Save scene as JSON string with stable URLs instead of archive
+  // This is useful when storing scenes in a database or referencing CDN-hosted assets
+  // By default, IDML images use transient buffer:// URLs that only work with saveToArchive()
+  // To use saveToString(), relocate transient resources to permanent URLs first:
+
+  // Mock upload function - replace with your actual backend upload logic
+  const uploadToBackend = async (data: Uint8Array): Promise<string> => {
+    // In production, upload the data to your CDN/storage and return the permanent URL
+    // For this example, we write to a temp file and return a file:// URL
+    const hash = data.reduce((acc, byte) => (acc + byte) % 1000000, 0);
+    const tempPath = join(outputDir, `asset-${hash}.png`);
+    await fs.writeFile(tempPath, data);
+    return `file://${tempPath}`;
+  };
+
+  const transientResources = engine.editor.findAllTransientResources();
+  for (const resource of transientResources) {
+    const { URL: bufferUri, size } = resource;
+    const data = engine.editor.getBufferData(bufferUri, 0, size);
+    const permanentUrl = await uploadToBackend(data);
+    engine.editor.relocateResource(bufferUri, permanentUrl);
   }
-];
 
-class Example implements EditorPlugin {
-  name = packageJson.name;
+  // Now save as scene string - all URLs are permanent
+  const sceneString = await engine.scene.saveToString();
+  const sceneStringPath = join(outputDir, `${inputName}.scene`);
+  await fs.writeFile(sceneStringPath, sceneString);
 
-  version = packageJson.version;
+  return { archivePath, sceneStringPath, pageCount: pages.length };
+}
 
-  async initialize({ cesdk }: EditorPluginContext): Promise<void> {
-    if (!cesdk) {
-      throw new Error('CE.SDK instance is required for this plugin');
+/**
+ * Batch convert multiple IDML files to CE.SDK scene formats
+ * Processes files sequentially, continuing even if individual files fail
+ */
+async function batchConvertIdmls(
+  idmlPaths: string[],
+  outputDir: string
+): Promise<void> {
+  console.log(`Starting batch conversion of ${idmlPaths.length} IDML files...`);
+
+  // Ensure output directory exists
+  await fs.mkdir(outputDir, { recursive: true });
+
+  // Initialize engine once for all conversions
+  const engine = await CreativeEngine.init({
+    baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
+    // license: process.env.CESDK_LICENSE,
+  });
+
+  try {
+    // Configure Google Fonts for text element support
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    await addGfontsAssetLibrary(engine as any);
+
+    let successCount = 0;
+    let failCount = 0;
+
+    // Process each IDML file
+    for (const idmlPath of idmlPaths) {
+      const fileName = basename(idmlPath);
+      console.log(`\nProcessing: ${fileName}`);
+
+      try {
+        const { archivePath, sceneStringPath } = await convertIdml(
+          engine,
+          idmlPath,
+          outputDir
+        );
+
+        console.log(`  Archive: ${archivePath}`);
+        console.log(`  Scene:   ${sceneStringPath}`);
+        successCount++;
+      } catch (error) {
+        console.error(`  Failed: ${(error as Error).message}`);
+        failCount++;
+      }
     }
 
-    const engine = cesdk.engine;
-
-    // Initialize CE.SDK with Google Fonts support for IDML text matching
-    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());
-
-    // Register Google Fonts before parsing IDML files for best font matching
-    await addGfontsAssetLibrary(engine);
-
-    // Optional: Create a custom font resolver for advanced font mapping
-    // Use this when you need to map InDesign fonts to specific alternatives,
-    // use enterprise fonts, or implement custom fallback logic
-    const customFontResolver: TypefaceResolver = async (fontParams, eng) => {
-      const { family, style, weight } = fontParams;
-
-      // Define font mappings from InDesign fonts to available alternatives
-      const fontMappings: Record<string, string> = {
-        Arial: 'Open Sans',
-        Helvetica: 'Inter',
-        'Helvetica Neue': 'Inter',
-        'Times New Roman': 'Lora',
-        Georgia: 'Merriweather'
-      };
-
-      // Use mapped font or original family name
-      const targetFamily = fontMappings[family] || family;
-
-      // Search for the font in available typefaces
-      const result = await eng.asset.findAssets('ly.img.typeface', {
-        query: targetFamily,
-        page: 0,
-        perPage: 10
-      });
-
-      if (result.assets.length === 0) {
-        console.warn(`Font "${family}" not found, using default fallback`);
-        return null; // Let the parser use its default fallback
-      }
+    console.log(`\nBatch conversion complete:`);
+    console.log(`  Success: ${successCount}/${idmlPaths.length}`);
+    console.log(`  Failed: ${failCount}/${idmlPaths.length}`);
+  } finally {
+    // Always dispose engine to free resources
+    engine.dispose();
+  }
+}
 
-      // Get the typeface from the asset payload
-      const asset = result.assets[0];
-      const typeface = asset.payload?.typeface;
-      if (!typeface) return null;
-
-      // Find the best matching font variant (weight and style)
-      const matchingFont =
-        typeface.fonts.find(
-          (f: { weight?: string; style?: string }) =>
-            f.weight === weight && f.style === style
-        ) ||
-        typeface.fonts.find((f: { weight?: string }) => f.weight === weight) ||
-        typeface.fonts[0];
-
-      return { typeface, font: matchingFont };
+/**
+ * Validate conversion results by loading the archive and checking scene structure
+ */
+export async function validateArchive(archivePath: string): Promise<{
+  valid: boolean;
+  pageCount: number;
+  blockCount: number;
+}> {
+  const engine = await CreativeEngine.init({
+    // license: process.env.CESDK_LICENSE,
+  });
+
+  try {
+    // Load the archive
+    const archiveBuffer = await fs.readFile(archivePath);
+    const archiveBlob = new Blob([archiveBuffer]);
+    const archiveUrl = URL.createObjectURL(archiveBlob);
+
+    await engine.scene.loadFromArchiveURL(archiveUrl);
+
+    // Get scene information
+    const pages = engine.block.findByType('page');
+    const allBlocks = engine.block.findAll();
+
+    return {
+      valid: pages.length > 0,
+      pageCount: pages.length,
+      blockCount: allBlocks.length
     };
+  } finally {
+    engine.dispose();
+  }
+}
 
-    // Create an initial design scene
-    await cesdk.actions.run('scene.create', {
-      page: {
-        sourceId: 'ly.img.page.presets',
-        assetId: 'ly.img.page.presets.print.iso.a6.landscape'
-      }
-    });
-
-    // Helper function to import IDML from URL or buffer
-    const importIdml = async (
-      source: string | ArrayBuffer,
-      sourceName: string
-    ) => {
-      console.log(`Processing IDML: ${sourceName}`);
-
-      // Get buffer from URL or use directly
-      let buffer: ArrayBuffer;
-      if (typeof source === 'string') {
-        const response = await fetch(source);
-        buffer = await response.arrayBuffer();
-      } else {
-        buffer = source;
-      }
-
-      // Parse the IDML file using the IDML importer
-      // The addGfontsAssetLibrary() call above enables automatic font matching
-      // For custom font mapping, pass fontResolver as 4th parameter (see customFontResolver example)
-      const parser = await IDMLParser.fromFile(
-        engine,
-        buffer,
-        (content: string) =>
-          new DOMParser().parseFromString(content, 'text/xml'),
-        customFontResolver
-      );
-      await parser.parse();
-
-      // Verify pages were imported successfully
-      const pages = engine.scene.getPages();
-      if (pages.length === 0) {
-        console.error('No pages imported from IDML');
-        throw new Error('No pages could be imported from the IDML file');
-      }
-      console.log(`Successfully imported ${pages.length} page(s)`);
-
-      // Save the imported scene as an archive for editor loading
-      const sceneArchive = await engine.scene.saveToArchive();
-      const archiveUrl = URL.createObjectURL(sceneArchive);
-
-      // Optional: Save scene as JSON string with stable URLs instead of archive
-      // This is useful when storing scenes in a database or referencing CDN-hosted assets
-      // By default, IDML images use transient buffer:// URLs that only work with saveToArchive()
-      // To use saveToString(), relocate transient resources to permanent URLs first:
-
-      // Mock upload function - replace with your actual backend upload logic
-      const uploadToBackend = async (data: Uint8Array): Promise<string> => {
-        // In production, upload the data to your CDN/storage and return the permanent URL
-        // For this example, we create a blob URL to demonstrate the workflow
-        const blob = new Blob([new Uint8Array(data)], { type: 'image/png' });
-        return URL.createObjectURL(blob);
-      };
-
-      const transientResources = engine.editor.findAllTransientResources();
-      for (const resource of transientResources) {
-        const { URL: bufferUri, size } = resource;
-        const data = engine.editor.getBufferData(bufferUri, 0, size);
-        const permanentUrl = await uploadToBackend(data);
-        engine.editor.relocateResource(bufferUri, permanentUrl);
-      }
-      const sceneString = await engine.scene.saveToString();
-      console.log(
-        `Scene persisted with stable URLs (${sceneString.length} bytes)`
-      );
+/**
+ * Find all IDML files in a directory and convert them
+ */
+export async function processDirectory(
+  inputDir: string,
+  outputDir: string
+): Promise<void> {
+  // Find all IDML files in directory
+  const files = await fs.readdir(inputDir);
+  const idmlFiles = files
+    .filter((f) => f.toLowerCase().endsWith('.idml'))
+    .map((f) => join(inputDir, f));
+
+  if (idmlFiles.length === 0) {
+    console.log(`No IDML files found in ${inputDir}`);
+    return;
+  }
 
-      // Load the archived scene into the editor
-      await cesdk.engine.scene.loadFromArchiveURL(archiveUrl);
+  await batchConvertIdmls(idmlFiles, outputDir);
+}
 
-      // Verify scene loaded correctly
-      const loadedPages = engine.scene.getPages();
-      console.log(
-        `IDML imported successfully with ${loadedPages.length} page(s)`
-      );
+/**
+ * Main entry point - demonstrates batch IDML conversion workflow
+ */
+async function main(): Promise<void> {
+  console.log('IDML to CE.SDK Batch Converter');
+  console.log('==============================\n');
+
+  // Example: Convert a single IDML file
+  // In production, you would provide actual IDML files
+  const engine = await CreativeEngine.init({
+    // license: process.env.CESDK_LICENSE,
+  });
+
+  try {
+    // Configure Google Fonts for text element support
+    await addGfontsAssetLibrary(engine as any);
+
+    // Create a sample scene to demonstrate the export format
+    // In production, this would be replaced by actual IDML conversion
+    await engine.scene.create();
+    const page = engine.block.create('page');
+    engine.block.setWidth(page, 800);
+    engine.block.setHeight(page, 600);
+    engine.block.appendChild(engine.scene.get()!, page);
+
+    // Save as archive
+    await fs.mkdir('./output', { recursive: true });
+    const archive = await engine.scene.saveToArchive();
+    const archiveBuffer = Buffer.from(await archive.arrayBuffer());
+    await fs.writeFile('./output/sample.cesdk', archiveBuffer);
+
+    console.log('Sample archive created: ./output/sample.cesdk');
+    console.log('\nTo convert actual IDML files:');
+    console.log('1. Place IDML files in an input directory');
+    console.log('2. Call: await processDirectory("./input", "./output")');
+  } finally {
+    engine.dispose();
+  }
+}
 
-      // Zoom to fit the imported page
-      await cesdk.actions.run('zoom.toPage', { page: 'first', autoFit: true });
+// Run the example
+main().catch(console.error);
+```
 
-      // Clean up object URL
-      URL.revokeObjectURL(archiveUrl);
-    };
+This guide covers installation, setting up a conversion script, parsing IDML files, saving scene archives, batch processing multiple files, and understanding the current limitations.
 
-    // Add custom asset source for IDML templates
-    engine.asset.addSource({
-      id: IDML_SOURCE_ID,
-
-      async findAssets(
-        queryData: AssetQueryData
-      ): Promise<AssetsQueryResult<AssetResult>> {
-        let assets = SAMPLE_IDML_FILES;
-
-        // Filter by query if provided
-        if (queryData.query) {
-          const query = queryData.query.toLowerCase();
-          assets = assets.filter(
-            (a) =>
-              a.label?.toLowerCase().includes(query) ||
-              a.tags?.some((t) => t.toLowerCase().includes(query))
-          );
-        }
-
-        return {
-          assets,
-          total: assets.length,
-          currentPage: queryData.page,
-          nextPage: undefined
-        };
-      },
-
-      async applyAsset(asset: AssetResult): Promise<number | undefined> {
-        if (!asset.meta?.uri) {
-          console.error('Asset has no URI');
-          return undefined;
-        }
-
-        await importIdml(asset.meta.uri as string, asset.label || asset.id);
-        return undefined; // Scene replaced, no new block created
-      }
-    });
+## Installation
 
-    // Set labels for the asset source and library entry
-    cesdk.i18n.setTranslations({
-      en: {
-        [`libraries.${IDML_SOURCE_ID}.label`]: 'IDML Files',
-        'libraries.idml-library-entry.label': 'InDesign Templates'
-      }
-    });
-
-    // Configure the asset library UI to show the IDML source
-    cesdk.ui.addAssetLibraryEntry({
-      id: 'idml-library-entry',
-      sourceIds: [IDML_SOURCE_ID],
-      previewLength: 3,
-      previewBackgroundType: 'contain',
-      gridBackgroundType: 'contain',
-      gridColumns: 2
-    });
-
-    // Add IDML library to the dock and remove the default Templates entry
-    const existingDockOrder = cesdk.ui.getComponentOrder({ in: 'ly.img.dock' });
-    const filteredDockOrder = existingDockOrder.filter(
-      (entry) => entry.key !== 'ly.img.templates'
-    );
-    cesdk.ui.setComponentOrder({ in: 'ly.img.dock' }, [
-      {
-        id: 'ly.img.assetLibrary.dock',
-        key: 'idml-library-dock',
-        label: 'InDesign Templates',
-        icon: '@imgly/Template',
-        entries: ['idml-library-entry']
-      },
-      ...filteredDockOrder
-    ]);
-
-    // Add a custom nav bar button for uploading and importing IDML files
-    // Uses cesdk.utils.loadFile() to open the browser's file picker
-    cesdk.ui.registerComponent('idml.uploadButton', ({ builder }) => {
-      builder.Button('idml.uploadButton', {
-        label: 'Load IDML File',
-        icon: '@imgly/Upload',
-        variant: 'regular',
-        color: 'accent',
-        onClick: async () => {
-          const buffer = await cesdk.utils.loadFile({
-            accept: '.idml,application/vnd.adobe.indesign-idml-package',
-            returnType: 'arrayBuffer'
-          });
-          await importIdml(buffer, 'uploaded.idml');
-        }
-      });
-    });
-
-    // Add the upload button to the right side of the navigation bar
-    cesdk.ui.setComponentOrder({ in: 'ly.img.navigation.bar' }, [
-      ...cesdk.ui.getComponentOrder({ in: 'ly.img.navigation.bar' }),
-      'idml.uploadButton'
-    ]);
-
-    // Open the IDML Templates library by default
-    cesdk.ui.openPanel('//ly.img.panel/assetLibrary', {
-      payload: {
-        entries: ['idml-library-entry'],
-        title: 'InDesign Templates'
-      }
-    });
-
-    // Override the importScene action to support IDML files alongside standard formats
-    // This integrates IDML import with the default import workflow
-    cesdk.actions.register(
-      'importScene',
-      async ({
-        format = 'scene'
-      }: {
-        format?: 'scene' | 'archive' | 'idml';
-      }) => {
-        if (format === 'idml') {
-          // Handle IDML import using cesdk.utils.loadFile
-          const buffer = await cesdk.utils.loadFile({
-            accept: '.idml,application/vnd.adobe.indesign-idml-package',
-            returnType: 'arrayBuffer'
-          });
-          await importIdml(buffer, 'imported.idml');
-        } else if (format === 'scene') {
-          // Handle standard .scene files
-          const scene = await cesdk.utils.loadFile({
-            accept: '.scene',
-            returnType: 'text'
-          });
-          await cesdk.engine.scene.loadFromString(scene);
-          await cesdk.actions.run('zoom.toPage', { page: 'first' });
-        } else {
-          // Handle archive files (.zip)
-          const blobURL = await cesdk.utils.loadFile({
-            accept: '.zip',
-            returnType: 'objectURL'
-          });
-          try {
-            await cesdk.engine.scene.loadFromArchiveURL(blobURL);
-          } finally {
-            URL.revokeObjectURL(blobURL);
-          }
-          await cesdk.actions.run('zoom.toPage', { page: 'first' });
-        }
-      }
-    );
-  }
-}
+Install the `@imgly/idml-importer` package alongside the Node.js SDK. Server-side conversion requires `jsdom` for XML parsing:
 
-export default Example;
+```bash
+npm install @imgly/idml-importer @cesdk/node@$UBQ_VERSION$ jsdom
+npm install --save-dev @types/jsdom
 ```
 
-## Installation
+The `jsdom` package provides the XML parsing functionality that `DOMParser` provides in browsers.
 
-Install the `@imgly/idml-importer` package alongside CE.SDK:
+### Optional: Embedded PDF / Adobe Illustrator support
+
+IDML files exported from InDesign can carry embedded PDF or Adobe Illustrator (`.ai`) content. To import these as editable CE.SDK blocks rather than placeholder images, also install `@imgly/pdf-importer` and register its adapter via the `embeddedImporters` option on `IDMLParser.fromFile`:
 
 ```bash
-npm install @imgly/idml-importer @cesdk/cesdk-js@$UBQ_VERSION$
+npm install @imgly/pdf-importer
 ```
 
-The browser environment uses the native `DOMParser` API for XML parsing, which requires no additional dependencies.
+The IDML importer does not import `@imgly/pdf-importer` itself — registering the adapter is opt-in, so consumers who don't need embedded-PDF support pay no install cost.
 
 ## Supported Elements
 
@@ -463,72 +361,62 @@ The IDML importer preserves the following InDesign elements:
 
 ## Setting Up Font Matching
 
-Text elements in IDML files reference fonts that may not be available in CE.SDK. Use `addGfontsAssetLibrary()` to register Google Fonts as a font source before parsing:
+Text elements in IDML files reference fonts that may not be available in CE.SDK. Use `addGfontsAssetLibrary()` from the `@imgly/idml-importer` package to register Google Fonts as a font source before parsing:
 
 ```typescript highlight=highlight-setup
-// Initialize CE.SDK with Google Fonts support for IDML text matching
-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());
-
-// Register Google Fonts before parsing IDML files for best font matching
-await addGfontsAssetLibrary(engine);
+import CreativeEngine from '@cesdk/node';
+import type { TypefaceResolver } from '@imgly/idml-importer';
+import {
+  IDMLParser,
+  addGfontsAssetLibrary,
+  createPdfEmbeddedImporter
+} from '@imgly/idml-importer';
+import { PDFParser } from '@imgly/pdf-importer';
+import { JSDOM } from 'jsdom';
+import { config } from 'dotenv';
+import { promises as fs } from 'fs';
+import { join, basename } from 'path';
+
+// Load environment variables
+config();
 ```
 
 Call this function on the engine before parsing IDML files. The importer attempts to match fonts from the IDML with available Google Fonts. For fonts not found, the importer uses a fallback font.
 
 ## Parsing the IDML File
 
-Use `IDMLParser.fromFile()` with the browser's native `DOMParser` for XML parsing. After parsing, the scene is immediately available in the engine:
+Use `IDMLParser.fromFile()` with `jsdom` for XML parsing. Unlike the browser's native `DOMParser`, server-side parsing requires explicit JSDOM configuration:
 
 ```typescript highlight=highlight-parse-idml
-// Get buffer from URL or use directly
-let buffer: ArrayBuffer;
-if (typeof source === 'string') {
-  const response = await fetch(source);
-  buffer = await response.arrayBuffer();
-} else {
-  buffer = source;
-}
-
-// Parse the IDML file using the IDML importer
-// The addGfontsAssetLibrary() call above enables automatic font matching
-// For custom font mapping, pass fontResolver as 4th parameter (see customFontResolver example)
+// Parse the IDML file using JSDOM for XML parsing.
+// Server-side import requires JSDOM since DOMParser is browser-only.
+// The addGfontsAssetLibrary() call enables automatic font matching.
+// Register the PDF embedded-importer adapter explicitly so any
+// <PDF>/.ai content inside the IDML imports as editable CE.SDK blocks
+// via @imgly/pdf-importer (rather than a placeholder image).
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 const parser = await IDMLParser.fromFile(
-  engine,
-  buffer,
-  (content: string) => new DOMParser().parseFromString(content, 'text/xml'),
-  customFontResolver
+  engine as any,
+  idmlBuffer.buffer,
+  (content: string) =>
+    new JSDOM(content, {
+      contentType: 'text/xml',
+      storageQuota: 10000000,
+      url: 'http://localhost'
+    }).window.document,
+  {
+    fontResolver: customFontResolver,
+    embeddedImporters: [createPdfEmbeddedImporter(PDFParser)]
+  }
 );
 await parser.parse();
 ```
 
-The parser creates a new scene in the engine with all supported IDML elements converted to CE.SDK blocks.
+The JSDOM options ensure proper XML handling:
+
+- `contentType: 'text/xml'` - Parses as XML rather than HTML
+- `storageQuota` - Prevents quota errors with larger documents
+- `url` - Required by JSDOM for relative resource resolution
 
 ## Checking Import Results
 
@@ -538,25 +426,125 @@ Verify the import succeeded by checking the page count. If no pages were importe
 // Verify pages were imported successfully
 const pages = engine.scene.getPages();
 if (pages.length === 0) {
-  console.error('No pages imported from IDML');
-  throw new Error('No pages could be imported from the IDML file');
+  throw new Error(`No pages imported from IDML file: ${idmlPath}`);
 }
-console.log(`Successfully imported ${pages.length} page(s)`);
+console.log(`  Imported ${pages.length} page(s)`);
 ```
 
-Log warnings about any unsupported features to help users understand what couldn't be converted.
+Log any warnings to identify IDML features that didn't convert correctly.
+
+## Converting a Single IDML File
+
+Read an IDML file, parse it using the IDML importer, and save the resulting scene as an archive:
+
+```typescript highlight=highlight-convert-single
+/**
+ * Convert a single IDML file to CE.SDK scene formats
+ * Outputs both an archive file and a scene string with stable URLs
+ */
+async function convertIdml(
+  engine: InstanceType<typeof CreativeEngine>,
+  idmlPath: string,
+  outputDir: string
+): Promise<{
+  archivePath: string;
+  sceneStringPath: string;
+  pageCount: number;
+}> {
+  // Read the IDML file
+  const idmlBuffer = await fs.readFile(idmlPath);
+
+  // Parse the IDML file using JSDOM for XML parsing.
+  // Server-side import requires JSDOM since DOMParser is browser-only.
+  // The addGfontsAssetLibrary() call enables automatic font matching.
+  // Register the PDF embedded-importer adapter explicitly so any
+  // <PDF>/.ai content inside the IDML imports as editable CE.SDK blocks
+  // via @imgly/pdf-importer (rather than a placeholder image).
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const parser = await IDMLParser.fromFile(
+    engine as any,
+    idmlBuffer.buffer,
+    (content: string) =>
+      new JSDOM(content, {
+        contentType: 'text/xml',
+        storageQuota: 10000000,
+        url: 'http://localhost'
+      }).window.document,
+    {
+      fontResolver: customFontResolver,
+      embeddedImporters: [createPdfEmbeddedImporter(PDFParser)]
+    }
+  );
+  await parser.parse();
+
+  // Verify pages were imported successfully
+  const pages = engine.scene.getPages();
+  if (pages.length === 0) {
+    throw new Error(`No pages imported from IDML file: ${idmlPath}`);
+  }
+  console.log(`  Imported ${pages.length} page(s)`);
+
+  // Generate output filename from input filename
+  const inputName = basename(idmlPath, '.idml');
+  const archivePath = join(outputDir, `${inputName}.cesdk`);
+
+  // Save as scene archive
+  const archive = await engine.scene.saveToArchive();
+  const archiveBuffer = Buffer.from(await archive.arrayBuffer());
+  await fs.writeFile(archivePath, archiveBuffer);
+
+  // Optional: Save scene as JSON string with stable URLs instead of archive
+  // This is useful when storing scenes in a database or referencing CDN-hosted assets
+  // By default, IDML images use transient buffer:// URLs that only work with saveToArchive()
+  // To use saveToString(), relocate transient resources to permanent URLs first:
+
+  // Mock upload function - replace with your actual backend upload logic
+  const uploadToBackend = async (data: Uint8Array): Promise<string> => {
+    // In production, upload the data to your CDN/storage and return the permanent URL
+    // For this example, we write to a temp file and return a file:// URL
+    const hash = data.reduce((acc, byte) => (acc + byte) % 1000000, 0);
+    const tempPath = join(outputDir, `asset-${hash}.png`);
+    await fs.writeFile(tempPath, data);
+    return `file://${tempPath}`;
+  };
+
+  const transientResources = engine.editor.findAllTransientResources();
+  for (const resource of transientResources) {
+    const { URL: bufferUri, size } = resource;
+    const data = engine.editor.getBufferData(bufferUri, 0, size);
+    const permanentUrl = await uploadToBackend(data);
+    engine.editor.relocateResource(bufferUri, permanentUrl);
+  }
+
+  // Now save as scene string - all URLs are permanent
+  const sceneString = await engine.scene.saveToString();
+  const sceneStringPath = join(outputDir, `${inputName}.scene`);
+  await fs.writeFile(sceneStringPath, sceneString);
+
+  return { archivePath, sceneStringPath, pageCount: pages.length };
+}
+```
+
+The `convertIdmlToArchive` function:
+
+1. Reads the IDML buffer
+2. Creates a parser instance with JSDOM for XML parsing
+3. Parses the IDML, creating a scene in the engine
+4. Verifies pages were imported successfully
+5. Saves the scene as a `.cesdk` archive file
 
 ## Saving as Archive
 
-After parsing, save the imported scene as an archive. This creates a portable bundle containing the scene and all its assets:
+After parsing, save the imported scene as an archive. Archives bundle the scene with all referenced assets, creating a portable file that can be distributed or loaded later:
 
 ```typescript highlight=highlight-save-archive
-// Save the imported scene as an archive for editor loading
-const sceneArchive = await engine.scene.saveToArchive();
-const archiveUrl = URL.createObjectURL(sceneArchive);
+// Save as scene archive
+const archive = await engine.scene.saveToArchive();
+const archiveBuffer = Buffer.from(await archive.arrayBuffer());
+await fs.writeFile(archivePath, archiveBuffer);
 ```
 
-Archives can be stored, shared, or loaded later using `loadFromArchiveURL()`.
+Write the archive to the filesystem as a `.cesdk` file for later use with `loadFromArchiveURL()`.
 
 ## Saving Scenes with Stable URLs
 
@@ -574,35 +562,40 @@ However, if you want to save scenes as JSON strings (`engine.scene.saveToString(
 After parsing the IDML file, use CE.SDK's native APIs to find and relocate all transient resources:
 
 ```typescript highlight=highlight-stable-urls
-// Optional: Save scene as JSON string with stable URLs instead of archive
-// This is useful when storing scenes in a database or referencing CDN-hosted assets
-// By default, IDML images use transient buffer:// URLs that only work with saveToArchive()
-// To use saveToString(), relocate transient resources to permanent URLs first:
-
-// Mock upload function - replace with your actual backend upload logic
-const uploadToBackend = async (data: Uint8Array): Promise<string> => {
-  // In production, upload the data to your CDN/storage and return the permanent URL
-  // For this example, we create a blob URL to demonstrate the workflow
-  const blob = new Blob([new Uint8Array(data)], { type: 'image/png' });
-  return URL.createObjectURL(blob);
-};
+  // Optional: Save scene as JSON string with stable URLs instead of archive
+  // This is useful when storing scenes in a database or referencing CDN-hosted assets
+  // By default, IDML images use transient buffer:// URLs that only work with saveToArchive()
+  // To use saveToString(), relocate transient resources to permanent URLs first:
+
+  // Mock upload function - replace with your actual backend upload logic
+  const uploadToBackend = async (data: Uint8Array): Promise<string> => {
+    // In production, upload the data to your CDN/storage and return the permanent URL
+    // For this example, we write to a temp file and return a file:// URL
+    const hash = data.reduce((acc, byte) => (acc + byte) % 1000000, 0);
+    const tempPath = join(outputDir, `asset-${hash}.png`);
+    await fs.writeFile(tempPath, data);
+    return `file://${tempPath}`;
+  };
+
+  const transientResources = engine.editor.findAllTransientResources();
+  for (const resource of transientResources) {
+    const { URL: bufferUri, size } = resource;
+    const data = engine.editor.getBufferData(bufferUri, 0, size);
+    const permanentUrl = await uploadToBackend(data);
+    engine.editor.relocateResource(bufferUri, permanentUrl);
+  }
 
-const transientResources = engine.editor.findAllTransientResources();
-for (const resource of transientResources) {
-  const { URL: bufferUri, size } = resource;
-  const data = engine.editor.getBufferData(bufferUri, 0, size);
-  const permanentUrl = await uploadToBackend(data);
-  engine.editor.relocateResource(bufferUri, permanentUrl);
-}
-const sceneString = await engine.scene.saveToString();
-console.log(`Scene persisted with stable URLs (${sceneString.length} bytes)`);
+  // Now save as scene string - all URLs are permanent
+  const sceneString = await engine.scene.saveToString();
+  const sceneStringPath = join(outputDir, `${inputName}.scene`);
+  await fs.writeFile(sceneStringPath, sceneString);
 ```
 
 The relocation workflow:
 
 1. Find all transient resources using `engine.editor.findAllTransientResources()`
 2. Extract binary data for each resource using `engine.editor.getBufferData()`
-3. Upload the data to your backend or CDN
+3. Upload the data to your storage service (S3, GCS, CDN, etc.)
 4. Relocate the resource URL using `engine.editor.relocateResource()`
 5. Save to string with `engine.scene.saveToString()` - all URLs will now be permanent
 
@@ -610,33 +603,242 @@ The relocation workflow:
 
 When using the default font resolver with Google Fonts, the resulting scene string will contain Google CDN URLs for fonts. If you need fonts hosted on your own infrastructure, configure a custom font resolver instead of using the default Google Fonts integration.
 
-## Loading into the Editor
+## Batch Converting Multiple IDML Files
+
+Process multiple IDML files sequentially, continuing even if individual files fail:
+
+```typescript highlight=highlight-batch-convert
+/**
+ * Batch convert multiple IDML files to CE.SDK scene formats
+ * Processes files sequentially, continuing even if individual files fail
+ */
+async function batchConvertIdmls(
+  idmlPaths: string[],
+  outputDir: string
+): Promise<void> {
+  console.log(`Starting batch conversion of ${idmlPaths.length} IDML files...`);
+
+  // Ensure output directory exists
+  await fs.mkdir(outputDir, { recursive: true });
+
+  // Initialize engine once for all conversions
+  const engine = await CreativeEngine.init({
+    baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
+    // license: process.env.CESDK_LICENSE,
+  });
+
+  try {
+    // Configure Google Fonts for text element support
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    await addGfontsAssetLibrary(engine as any);
+
+    let successCount = 0;
+    let failCount = 0;
+
+    // Process each IDML file
+    for (const idmlPath of idmlPaths) {
+      const fileName = basename(idmlPath);
+      console.log(`\nProcessing: ${fileName}`);
+
+      try {
+        const { archivePath, sceneStringPath } = await convertIdml(
+          engine,
+          idmlPath,
+          outputDir
+        );
+
+        console.log(`  Archive: ${archivePath}`);
+        console.log(`  Scene:   ${sceneStringPath}`);
+        successCount++;
+      } catch (error) {
+        console.error(`  Failed: ${(error as Error).message}`);
+        failCount++;
+      }
+    }
+
+    console.log(`\nBatch conversion complete:`);
+    console.log(`  Success: ${successCount}/${idmlPaths.length}`);
+    console.log(`  Failed: ${failCount}/${idmlPaths.length}`);
+  } finally {
+    // Always dispose engine to free resources
+    engine.dispose();
+  }
+}
+```
 
-Load the archived scene into the CE.SDK editor for user editing:
+Key aspects of batch conversion:
 
-```typescript highlight=highlight-load-editor
-// Load the archived scene into the editor
-await cesdk.engine.scene.loadFromArchiveURL(archiveUrl);
+- **Single engine instance** - Initialize once and reuse for all conversions to improve performance
+- **Error isolation** - Each file is processed in a try-catch block so one failure doesn't stop the batch
+- **Progress logging** - Track success and failure counts for reporting
+- **Resource cleanup** - Always dispose the engine in a finally block
 
-// Verify scene loaded correctly
-const loadedPages = engine.scene.getPages();
-console.log(`IDML imported successfully with ${loadedPages.length} page(s)`);
+## Processing a Directory
 
-// Zoom to fit the imported page
-await cesdk.actions.run('zoom.toPage', { page: 'first', autoFit: true });
+Scan a directory for IDML files and convert all of them:
+
+```typescript highlight=highlight-process-directory
+/**
+ * Find all IDML files in a directory and convert them
+ */
+export async function processDirectory(
+  inputDir: string,
+  outputDir: string
+): Promise<void> {
+  // Find all IDML files in directory
+  const files = await fs.readdir(inputDir);
+  const idmlFiles = files
+    .filter((f) => f.toLowerCase().endsWith('.idml'))
+    .map((f) => join(inputDir, f));
+
+  if (idmlFiles.length === 0) {
+    console.log(`No IDML files found in ${inputDir}`);
+    return;
+  }
+
+  await batchConvertIdmls(idmlFiles, outputDir);
+}
 ```
 
-After loading, verify the scene contains at least one page. The imported design is now ready for editing in the CE.SDK editor.
+This function finds all `.idml` files in the input directory and processes them as a batch.
+
+## Validating Conversion Results
+
+Load a converted archive and verify its structure:
+
+```typescript highlight=highlight-validate-results
+/**
+ * Validate conversion results by loading the archive and checking scene structure
+ */
+export async function validateArchive(archivePath: string): Promise<{
+  valid: boolean;
+  pageCount: number;
+  blockCount: number;
+}> {
+  const engine = await CreativeEngine.init({
+    // license: process.env.CESDK_LICENSE,
+  });
+
+  try {
+    // Load the archive
+    const archiveBuffer = await fs.readFile(archivePath);
+    const archiveBlob = new Blob([archiveBuffer]);
+    const archiveUrl = URL.createObjectURL(archiveBlob);
+
+    await engine.scene.loadFromArchiveURL(archiveUrl);
+
+    // Get scene information
+    const pages = engine.block.findByType('page');
+    const allBlocks = engine.block.findAll();
+
+    return {
+      valid: pages.length > 0,
+      pageCount: pages.length,
+      blockCount: allBlocks.length
+    };
+  } finally {
+    engine.dispose();
+  }
+}
+```
+
+Validation checks:
+
+- The archive can be loaded without errors
+- At least one page exists in the scene
+- Block count indicates content was imported
+
+## Running the Conversion
+
+The main entry point demonstrates the complete batch conversion workflow:
+
+```typescript highlight=highlight-main
+/**
+ * Main entry point - demonstrates batch IDML conversion workflow
+ */
+async function main(): Promise<void> {
+  console.log('IDML to CE.SDK Batch Converter');
+  console.log('==============================\n');
+
+  // Example: Convert a single IDML file
+  // In production, you would provide actual IDML files
+  const engine = await CreativeEngine.init({
+    // license: process.env.CESDK_LICENSE,
+  });
+
+  try {
+    // Configure Google Fonts for text element support
+    await addGfontsAssetLibrary(engine as any);
+
+    // Create a sample scene to demonstrate the export format
+    // In production, this would be replaced by actual IDML conversion
+    await engine.scene.create();
+    const page = engine.block.create('page');
+    engine.block.setWidth(page, 800);
+    engine.block.setHeight(page, 600);
+    engine.block.appendChild(engine.scene.get()!, page);
+
+    // Save as archive
+    await fs.mkdir('./output', { recursive: true });
+    const archive = await engine.scene.saveToArchive();
+    const archiveBuffer = Buffer.from(await archive.arrayBuffer());
+    await fs.writeFile('./output/sample.cesdk', archiveBuffer);
+
+    console.log('Sample archive created: ./output/sample.cesdk');
+    console.log('\nTo convert actual IDML files:');
+    console.log('1. Place IDML files in an input directory');
+    console.log('2. Call: await processDirectory("./input", "./output")');
+  } finally {
+    engine.dispose();
+  }
+}
+```
+
+Run the script with `vite-node` or `tsx`:
+
+```bash
+npx vite-node server-js.ts
+```
+
+For production use, modify the script to accept input/output directories as arguments.
+
+## Saving and Loading Archives
+
+Scene archives (`.cesdk` files) contain the complete scene with all embedded assets:
+
+```typescript
+// Save scene as archive
+const archive = await engine.scene.saveToArchive();
+const archiveBuffer = Buffer.from(await archive.arrayBuffer());
+await fs.writeFile('output.cesdk', archiveBuffer);
+
+// Load archive in browser or server
+await engine.scene.loadFromArchiveURL(archiveUrl);
+```
+
+Archives are portable - convert on server, load in browser or another server instance.
+
+## Engine Cleanup
+
+Always dispose of the engine when processing is complete to free system resources:
+
+```typescript highlight=highlight-cleanup
+// Always dispose engine to free resources
+engine.dispose();
+```
+
+Using a `try/finally` block ensures cleanup happens even if an error occurs during processing.
 
 ## API Reference
 
 The `@imgly/idml-importer` package exports the following key APIs:
 
-| API                                              | Description                                                                                                         |
-| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
-| `IDMLParser.fromFile(engine, buffer, xmlParser)` | Creates a parser instance from an IDML file buffer. The `xmlParser` function converts XML strings to DOM documents. |
-| `parser.parse()`                                 | Parses the IDML file and creates a CE.SDK scene. Returns when parsing is complete.                                  |
-| `addGfontsAssetLibrary(engine)`                  | Registers Google Fonts as a font source for text element matching. Call before parsing.                             |
+| API | Description |
+|-----|-------------|
+| `IDMLParser.fromFile(engine, buffer, xmlParser, options?)` | Creates a parser instance from an IDML file buffer. The `xmlParser` function converts XML strings to DOM documents. `options` accepts `fontResolver` and `embeddedImporters`. |
+| `parser.parse()` | Parses the IDML file and creates a CE.SDK scene. Returns when parsing is complete. |
+| `addGfontsAssetLibrary(engine)` | Registers Google Fonts as a font source for text element matching. Call before parsing. |
+| `createPdfEmbeddedImporter(PDFParser)` | Adapter for the `embeddedImporters` array. Imports embedded PDF / `.ai` content as editable CE.SDK blocks via `@imgly/pdf-importer`. Requires the package to be installed; pass its `PDFParser` class as the only argument. |
 
 ## Limitations
 
@@ -645,8 +847,7 @@ The IDML importer has the following limitations:
 - **Linked images** - Only embedded images are supported. Linked images become placeholders. Embed all images in InDesign before exporting to IDML.
 - **Text flow** - Text that flows between multiple text frames is not supported and may appear duplicated.
 - **Image fitting** - Images shrunk inside their frames may not render as expected.
-- **PDF content** - Embedded PDF content is replaced with placeholders.
-- **Page sizes** - Different page sizes within the same document are not supported. All pages use the first page's dimensions.
+- **Embedded PDF / `.ai`** - Imports as editable blocks when `@imgly/pdf-importer` is installed and `createPdfEmbeddedImporter(PDFParser)` is registered in `embeddedImporters`. Without the adapter, embeds fall through to a placeholder image. Non-rectangular frame clipping and per-embed PDF crop attributes are not yet applied.
 - **Advanced text** - Complex text formatting beyond bold/italic may not be preserved.
 
 ## Pre-Import Checklist
@@ -668,13 +869,15 @@ Before exporting from InDesign:
 
 **Text is duplicated:** This can happen when text flows between multiple frames. The IDML importer doesn't support linked text frames.
 
-**Pages have wrong size:** All pages use the first page's dimensions. Ensure consistent page sizes in the InDesign document.
+**Embedded PDFs show as placeholders:** Install `@imgly/pdf-importer` and pass `createPdfEmbeddedImporter(PDFParser)` in the `embeddedImporters` option to `IDMLParser.fromFile`. Without the adapter, `<PDF>` and `.ai` embeds fall through to a placeholder image.
+
+
 
 ---
 
 ## 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