@imgly/codesign-mcp 0.1.5 → 0.1.6

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

@@ -1,492 +1,378 @@
-> 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 Photoshop](./open-the-editor/import-design/from-photoshop.md)
 
 ---
 
-Import Adobe Photoshop (PSD) files into CE.SDK, converting them into editable scenes while preserving layers, text, shapes, and positioning.
+Convert Adobe Photoshop (PSD) files to CE.SDK scene archives at build-time using Node.js. This approach is ideal for migrating existing template libraries or integrating PSD conversion into CI/CD pipelines.
 
 > **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-photoshop-browser)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-open-the-editor-import-design-from-photoshop-browser)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-open-the-editor-import-design-from-photoshop-browser/)
-
-![Import from Photoshop](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
-
-The `@imgly/psd-importer` package converts Photoshop files into CE.SDK scene format, preserving design structure for editing or export. This guide focuses on enabling end-users to upload their own PSD 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-photoshop.md).
+>
+> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-open-the-editor-import-design-from-photoshop-server-js)
+>
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-open-the-editor-import-design-from-photoshop-server-js)
 
-```typescript file=@cesdk_web_examples/guides-open-the-editor-import-design-from-photoshop-browser/browser.ts reference-only
-import type { EditorPlugin, EditorPluginContext } from '@cesdk/cesdk-js';
+The `@imgly/psd-importer` package converts Photoshop files into CE.SDK scene format on the server, allowing you to distribute pre-converted templates without client-side processing. This guide covers batch conversion of PSD template files to CE.SDK scene archives that can be shipped with your product. For enabling end-users to upload PSD files directly in the browser, see the [browser guide](./open-the-editor/import-design/from-photoshop.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-photoshop-server-js/server-js.ts reference-only
+import CreativeEngine from '@cesdk/node';
 import type { TypefaceResolver } from '@imgly/psd-importer';
 import {
   PSDParser,
-  addGfontsAssetLibrary,
-  createWebEncodeBufferToPNG
+  createPNGJSEncodeBufferToPNG,
+  addGfontsAssetLibrary
 } from '@imgly/psd-importer';
-import packageJson from './package.json';
+import { PNG } from 'pngjs';
+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 Photoshop 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 Photoshop 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 Photoshop Guide
- *
- * Demonstrates how to import Adobe Photoshop (PSD) files into CE.SDK:
- * - Creating a custom asset source for PSD templates
- * - Adding a custom nav bar button to upload PSD files
- * - Parsing PSD files with the PSD 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 PSD file to CE.SDK scene formats
+ * Outputs both an archive file and a scene string with stable URLs
  */
+async function convertPsd(
+  engine: InstanceType<typeof CreativeEngine>,
+  psdPath: string,
+  outputDir: string
+): Promise<{
+  archivePath: string;
+  sceneStringPath: string;
+  warnings: string[];
+  errors: string[];
+}> {
+  // Read the PSD file
+  const psdBuffer = await fs.readFile(psdPath);
+
+  // Create parser with Node.js PNG encoder
+  // The addGfontsAssetLibrary() call enables automatic font matching
+  // For custom font mapping, pass fontResolver in options (see customFontResolver example)
+  // Note: Cast engine to any because psd-importer types expect browser engine
+  const parser = await PSDParser.fromFile(
+    engine as any,
+    psdBuffer.buffer,
+    createPNGJSEncodeBufferToPNG(PNG),
+    // Pass fontResolver for advanced font mapping
+    { fontResolver: customFontResolver }
+  );
 
-// Asset source ID for PSD library
-const PSD_SOURCE_ID = 'psd-files';
-
-// Base URL for PSD template files
-const PSD_BASE_URL =
-  'https://staticimgly.com/imgly/docs-reference-files-temp/psd-template-import';
-
-// Sample PSD files from the CE.SDK showcases
-const SAMPLE_PSD_FILES: AssetResult[] = [
-  {
-    id: 'showcase-file-1',
-    label: 'Sample Design 1',
-    tags: ['sample', 'psd'],
-    meta: {
-      uri: `${PSD_BASE_URL}/showcase-file-1.psd`,
-      thumbUri: `${PSD_BASE_URL}/showcase-file-1-thumb.png`,
-      mimeType: 'application/x-photoshop',
-      width: 1920,
-      height: 1080
-    }
-  },
-  {
-    id: 'showcase-file-2',
-    label: 'Sample Design 2',
-    tags: ['sample', 'psd'],
-    meta: {
-      uri: `${PSD_BASE_URL}/showcase-file-2.psd`,
-      thumbUri: `${PSD_BASE_URL}/showcase-file-2-thumb.png`,
-      mimeType: 'application/x-photoshop',
-      width: 1920,
-      height: 1080
-    }
-  },
-  {
-    id: 'showcase-file-3',
-    label: 'Sample Design 3',
-    tags: ['sample', 'psd'],
-    meta: {
-      uri: `${PSD_BASE_URL}/showcase-file-3.psd`,
-      thumbUri: `${PSD_BASE_URL}/showcase-file-3-thumb.png`,
-      mimeType: 'application/x-photoshop',
-      width: 1920,
-      height: 1080
-    }
+  // Parse the PSD file
+  const result = await parser.parse();
+
+  // Extract warnings and errors from logger
+  const messages = result.logger.getMessages();
+  const warnings = messages
+    .filter((m) => m.type === 'warning')
+    .map((m) => m.message);
+  const errors = messages
+    .filter((m) => m.type === 'error')
+    .map((m) => m.message);
+
+  if (errors.length > 0) {
+    console.error(`  Errors: ${errors.length}`);
+  }
+  if (warnings.length > 0) {
+    console.warn(`  Warnings: ${warnings.length}`);
   }
-];
 
-class Example implements EditorPlugin {
-  name = packageJson.name;
+  // Generate output filename from input filename
+  const inputName = basename(psdPath, '.psd');
+  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, PSD 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}`;
+  };
 
-  version = packageJson.version;
+  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);
+  }
 
-  async initialize({ cesdk }: EditorPluginContext): Promise<void> {
-    if (!cesdk) {
-      throw new Error('CE.SDK instance is required for this plugin');
-    }
+  // 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);
 
-    const engine = cesdk.engine;
-
-    // Initialize CE.SDK with Google Fonts support for PSD 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 PSD 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 Photoshop 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 Photoshop 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
-      }
+  return { archivePath, sceneStringPath, warnings, errors };
+}
 
-      // 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 };
-    };
+/**
+ * Batch convert multiple PSD files to CE.SDK scene formats
+ * Processes files sequentially, continuing even if individual files fail
+ */
+async function batchConvertPsds(
+  psdPaths: string[],
+  outputDir: string
+): Promise<void> {
+  console.log(`Starting batch conversion of ${psdPaths.length} PSD 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,
+  });
 
-    // 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 PSD from URL or buffer
-    const importPsd = async (
-      source: string | ArrayBuffer,
-      sourceName: string
-    ) => {
-      console.log(`Processing PSD: ${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;
-      }
+  try {
+    // Configure Google Fonts for text element support
+    // Note: Cast engine to any because psd-importer types expect browser engine
+    await addGfontsAssetLibrary(engine as any);
 
-      // Parse the PSD file using the PSD importer
-      // The addGfontsAssetLibrary() call above enables automatic font matching
-      // For custom font mapping, pass fontResolver in options (see customFontResolver example)
-      const parser = await PSDParser.fromFile(
-        engine,
-        buffer,
-        createWebEncodeBufferToPNG(),
-        { fontResolver: customFontResolver }
-      );
-      const result = await parser.parse();
-
-      // Check for import warnings and errors
-      const messages = result.logger.getMessages();
-      const warnings = messages.filter((m) => m.type === 'warning');
-      const errors = messages.filter((m) => m.type === 'error');
-
-      if (errors.length > 0) {
-        console.error('Import errors:', errors);
-      }
-      if (warnings.length > 0) {
-        console.warn(
-          'Import warnings:',
-          warnings.map((w) => w.message)
-        );
-      }
+    let successCount = 0;
+    let failCount = 0;
+
+    // Process each PSD file
+    for (const psdPath of psdPaths) {
+      const fileName = basename(psdPath);
+      console.log(`\nProcessing: ${fileName}`);
+
+      try {
+        const { archivePath, sceneStringPath, warnings, errors } =
+          await convertPsd(engine, psdPath, outputDir);
+
+        // Log results
+        if (errors.length > 0) {
+          console.log(`  Errors: ${errors.length}`);
+          errors.forEach((e) => console.log(`    - ${e}`));
+        }
+        if (warnings.length > 0) {
+          console.log(`  Warnings: ${warnings.length}`);
+          warnings.forEach((w) => console.log(`    - ${w}`));
+        }
 
-      // 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, PSD 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);
+        console.log(`  Archive: ${archivePath}`);
+        console.log(`  Scene:   ${sceneStringPath}`);
+        successCount++;
+      } catch (error) {
+        console.error(`  Failed: ${(error as Error).message}`);
+        failCount++;
       }
-      const sceneString = await engine.scene.saveToString();
-      console.log(
-        `Scene persisted with stable URLs (${sceneString.length} bytes)`
-      );
+    }
 
-      // Load the archived scene into the editor
-      await cesdk.engine.scene.loadFromArchiveURL(archiveUrl);
+    console.log(`\nBatch conversion complete:`);
+    console.log(`  Success: ${successCount}/${psdPaths.length}`);
+    console.log(`  Failed: ${failCount}/${psdPaths.length}`);
+  } finally {
+    // Always dispose engine to free resources
+    engine.dispose();
+  }
+}
+
+/**
+ * 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);
 
-      // Verify scene loaded correctly
-      const pages = engine.scene.getPages();
-      console.log(`PSD imported successfully with ${pages.length} page(s)`);
+    await engine.scene.loadFromArchiveURL(archiveUrl);
 
-      // Zoom to fit the imported page
-      await cesdk.actions.run('zoom.toPage', { page: 'first', autoFit: true });
+    // Get scene information
+    const pages = engine.block.findByType('page');
+    const allBlocks = engine.block.findAll();
 
-      // Clean up object URL
-      URL.revokeObjectURL(archiveUrl);
+    return {
+      valid: pages.length > 0,
+      pageCount: pages.length,
+      blockCount: allBlocks.length
     };
+  } finally {
+    engine.dispose();
+  }
+}
 
-    // Add custom asset source for PSD templates
-    engine.asset.addSource({
-      id: PSD_SOURCE_ID,
-
-      async findAssets(
-        queryData: AssetQueryData
-      ): Promise<AssetsQueryResult<AssetResult>> {
-        let assets = SAMPLE_PSD_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))
-          );
-        }
+/**
+ * Find all PSD files in a directory and convert them
+ */
+export async function processDirectory(
+  inputDir: string,
+  outputDir: string
+): Promise<void> {
+  // Find all PSD files in directory
+  const files = await fs.readdir(inputDir);
+  const psdFiles = files
+    .filter((f) => f.toLowerCase().endsWith('.psd'))
+    .map((f) => join(inputDir, f));
+
+  if (psdFiles.length === 0) {
+    console.log(`No PSD files found in ${inputDir}`);
+    return;
+  }
 
-        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 batchConvertPsds(psdFiles, outputDir);
+}
 
-        await importPsd(asset.meta.uri as string, asset.label || asset.id);
-        return undefined; // Scene replaced, no new block created
-      }
-    });
+/**
+ * Main entry point - demonstrates batch PSD conversion workflow
+ */
+async function main(): Promise<void> {
+  console.log('PSD to CE.SDK Batch Converter');
+  console.log('=============================\n');
+
+  // Example: Convert a single PSD file
+  // In production, you would provide actual PSD files
+  const engine = await CreativeEngine.init({
+    // license: process.env.CESDK_LICENSE,
+  });
 
-    // Set labels for the asset source and library entry
-    cesdk.i18n.setTranslations({
-      en: {
-        [`libraries.${PSD_SOURCE_ID}.label`]: 'PSD Files',
-        'libraries.psd-library-entry.label': 'PSD Templates'
-      }
-    });
-
-    // Configure the asset library UI to show the PSD source
-    cesdk.ui.addAssetLibraryEntry({
-      id: 'psd-library-entry',
-      sourceIds: [PSD_SOURCE_ID],
-      previewLength: 3,
-      previewBackgroundType: 'contain',
-      gridBackgroundType: 'contain',
-      gridColumns: 2
-    });
-
-    // Add PSD 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: 'psd-library-dock',
-        label: 'PSD Templates',
-        icon: '@imgly/Template',
-        entries: ['psd-library-entry']
-      },
-      ...filteredDockOrder
-    ]);
-
-    // Add a custom nav bar button for uploading and importing PSD files
-    // Uses cesdk.utils.loadFile() to open the browser's file picker
-    cesdk.ui.registerComponent('psd.uploadButton', ({ builder }) => {
-      builder.Button('psd.uploadButton', {
-        label: 'Load PSD File',
-        icon: '@imgly/Upload',
-        variant: 'regular',
-        color: 'accent',
-        onClick: async () => {
-          const buffer = await cesdk.utils.loadFile({
-            accept: '.psd,application/x-photoshop,image/vnd.adobe.photoshop',
-            returnType: 'arrayBuffer'
-          });
-          await importPsd(buffer, 'uploaded.psd');
-        }
-      });
-    });
-
-    // 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' }),
-      'psd.uploadButton'
-    ]);
-
-    // Open the PSD Templates library by default
-    cesdk.ui.openPanel('//ly.img.panel/assetLibrary', {
-      payload: {
-        entries: ['psd-library-entry'],
-        title: 'PSD Templates'
-      }
-    });
-
-    // Override the importScene action to support PSD files alongside standard formats
-    // This integrates PSD import with the default import workflow
-    cesdk.actions.register(
-      'importScene',
-      async ({
-        format = 'scene'
-      }: {
-        format?: 'scene' | 'archive' | 'psd';
-      }) => {
-        if (format === 'psd') {
-          // Handle PSD import using cesdk.utils.loadFile
-          const buffer = await cesdk.utils.loadFile({
-            accept: '.psd,application/x-photoshop,image/vnd.adobe.photoshop',
-            returnType: 'arrayBuffer'
-          });
-          await importPsd(buffer, 'imported.psd');
-        } 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' });
-        }
-      }
-    );
+  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 PSD 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 PSD files:');
+    console.log('1. Place PSD files in an input directory');
+    console.log('2. Call: await processDirectory("./input", "./output")');
+  } finally {
+    engine.dispose();
   }
 }
 
-export default Example;
+// Run the example
+main().catch(console.error);
 ```
 
 ## Installation
 
-Install the `@imgly/psd-importer` package alongside CE.SDK:
+Install the `@imgly/psd-importer` package alongside the CE.SDK Node.js engine and the `pngjs` package for PNG encoding:
 
 ```bash
-npm install @imgly/psd-importer @cesdk/cesdk-js@$UBQ_VERSION$
+npm install @imgly/psd-importer @cesdk/node@$UBQ_VERSION$ pngjs
 ```
 
-The browser environment uses `createWebEncodeBufferToPNG()` for PNG encoding, which requires no additional dependencies.
+The server environment requires `pngjs` because Node.js doesn't have native browser APIs for PNG encoding. The `createPNGJSEncodeBufferToPNG(PNG)` function provides this capability.
 
-## Import Your First PSD
+## Convert Your First PSD
 
-Parse a PSD file and load it into CE.SDK with just a few lines of code:
+Convert a PSD file to a CE.SDK archive with just a few lines of code:
 
 ```typescript
-import CreativeEditorSDK from '@cesdk/cesdk-js';
-import { PSDParser, createWebEncodeBufferToPNG } from '@imgly/psd-importer';
-
-// Initialize CE.SDK
-const cesdk = await CreativeEditorSDK.create('#container', {
-  license: 'YOUR_LICENSE_KEY'
-});
-const engine = cesdk.engine;
+import CreativeEngine from '@cesdk/node';
+import { PSDParser, createPNGJSEncodeBufferToPNG } from '@imgly/psd-importer';
+import { PNG } from 'pngjs';
+import { promises as fs } from 'fs';
 
-// Fetch and parse a PSD file
-const response = await fetch('https://example.com/design.psd');
-const buffer = await response.arrayBuffer();
+// Initialize the engine
+const engine = await CreativeEngine.init({});
 
-// Parse the PSD - creates a scene in the engine
+// Read and parse the PSD file
+const psdBuffer = await fs.readFile('./design.psd');
 const parser = await PSDParser.fromFile(
-  engine,
-  buffer,
-  createWebEncodeBufferToPNG()
+  engine as any,
+  psdBuffer.buffer,
+  createPNGJSEncodeBufferToPNG(PNG)
 );
 await parser.parse();
 
-// The PSD is now loaded as an editable scene
-console.log('Pages:', engine.scene.getPages().length);
+// Save as a portable archive
+const archive = await engine.scene.saveToArchive();
+await fs.writeFile('./design.cesdk', Buffer.from(await archive.arrayBuffer()));
+
+// Clean up
+engine.dispose();
 ```
 
-This minimal example fetches a PSD from a URL and converts it into an editable CE.SDK scene. The following sections cover font handling, user uploads, and additional features.
+This minimal example reads a PSD file, converts it to a CE.SDK scene, and saves it as an archive. The archive can be loaded in any CE.SDK environment (browser or server). The following sections cover font handling, batch processing, and validation.
 
 ## Supported Elements
 
@@ -499,340 +385,424 @@ The PSD importer preserves the following Photoshop elements:
 - **Fills** - Solid color fills and strokes (weight, color, alignment)
 - **Images** - Raster image layers (without cropping)
 
-## Setting Up Font Matching
+## Setting Up the Conversion Environment
 
-Text elements in PSD files reference fonts that may not be available in CE.SDK. Use `addGfontsAssetLibrary()` to register Google Fonts as a font source before parsing:
+Initialize the CE.SDK Node.js engine and configure Google Fonts support before processing PSD files:
 
 ```typescript highlight=highlight-setup
-// Initialize CE.SDK with Google Fonts support for PSD 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 PSD files for best font matching
-await addGfontsAssetLibrary(engine);
-```
+import CreativeEngine from '@cesdk/node';
+import type { TypefaceResolver } from '@imgly/psd-importer';
+import {
+  PSDParser,
+  createPNGJSEncodeBufferToPNG,
+  addGfontsAssetLibrary
+} from '@imgly/psd-importer';
+import { PNG } from 'pngjs';
+import { config } from 'dotenv';
+import { promises as fs } from 'fs';
+import { join, basename } from 'path';
 
-Call this function on the engine before parsing PSD files. The importer attempts to match fonts from the PSD with available Google Fonts. For fonts not found, the importer uses a fallback font.
+// Load environment variables
+config();
+```
 
-## Checking Import Warnings
+The `pngjs` package provides the `PNG` constructor needed for `createPNGJSEncodeBufferToPNG()`. We use `dotenv` to load environment variables like the license key.
 
-Display warnings from the import result to inform users about unsupported features. Filter the logger messages and show appropriate notifications:
+## Converting a Single PSD File
 
-```typescript highlight=highlight-check-warnings
-// Check for import warnings and errors
-const messages = result.logger.getMessages();
-const warnings = messages.filter((m) => m.type === 'warning');
-const errors = messages.filter((m) => m.type === 'error');
+Read a PSD file, parse it using the PSD importer, and save the resulting scene as an archive:
 
-if (errors.length > 0) {
-  console.error('Import errors:', errors);
-}
-if (warnings.length > 0) {
-  console.warn(
-    'Import warnings:',
-    warnings.map((w) => w.message)
+```typescript highlight=highlight-convert-single
+/**
+ * Convert a single PSD file to CE.SDK scene formats
+ * Outputs both an archive file and a scene string with stable URLs
+ */
+async function convertPsd(
+  engine: InstanceType<typeof CreativeEngine>,
+  psdPath: string,
+  outputDir: string
+): Promise<{
+  archivePath: string;
+  sceneStringPath: string;
+  warnings: string[];
+  errors: string[];
+}> {
+  // Read the PSD file
+  const psdBuffer = await fs.readFile(psdPath);
+
+  // Create parser with Node.js PNG encoder
+  // The addGfontsAssetLibrary() call enables automatic font matching
+  // For custom font mapping, pass fontResolver in options (see customFontResolver example)
+  // Note: Cast engine to any because psd-importer types expect browser engine
+  const parser = await PSDParser.fromFile(
+    engine as any,
+    psdBuffer.buffer,
+    createPNGJSEncodeBufferToPNG(PNG),
+    // Pass fontResolver for advanced font mapping
+    { fontResolver: customFontResolver }
   );
-}
-```
 
-Common warnings include unsupported blend modes, font substitutions, and features that couldn't be converted. Errors indicate critical issues that prevented parts of the PSD from being imported.
-
-## Adding a File Upload Button
-
-Add a custom button to the navigation bar that allows users to upload and import PSD files directly. The button uses `cesdk.utils.loadFile()` to open the file picker and immediately imports the selected file:
-
-```typescript highlight=highlight-file-upload
-// Add a custom nav bar button for uploading and importing PSD files
-// Uses cesdk.utils.loadFile() to open the browser's file picker
-cesdk.ui.registerComponent('psd.uploadButton', ({ builder }) => {
-  builder.Button('psd.uploadButton', {
-    label: 'Load PSD File',
-    icon: '@imgly/Upload',
-    variant: 'regular',
-    color: 'accent',
-    onClick: async () => {
-      const buffer = await cesdk.utils.loadFile({
-        accept: '.psd,application/x-photoshop,image/vnd.adobe.photoshop',
-        returnType: 'arrayBuffer'
-      });
-      await importPsd(buffer, 'uploaded.psd');
-    }
-  });
-});
-
-// 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' }),
-  'psd.uploadButton'
-]);
-
-// Open the PSD Templates library by default
-cesdk.ui.openPanel('//ly.img.panel/assetLibrary', {
-  payload: {
-    entries: ['psd-library-entry'],
-    title: 'PSD Templates'
+  // Parse the PSD file
+  const result = await parser.parse();
+
+  // Extract warnings and errors from logger
+  const messages = result.logger.getMessages();
+  const warnings = messages
+    .filter((m) => m.type === 'warning')
+    .map((m) => m.message);
+  const errors = messages
+    .filter((m) => m.type === 'error')
+    .map((m) => m.message);
+
+  if (errors.length > 0) {
+    console.error(`  Errors: ${errors.length}`);
+  }
+  if (warnings.length > 0) {
+    console.warn(`  Warnings: ${warnings.length}`);
   }
-});
-```
 
-This registers a custom button component that uses `cesdk.utils.loadFile()` to handle file selection. When clicked, the button opens the system file picker, reads the selected file as an ArrayBuffer, and passes it directly to the PSD parser for immediate import into the editor.
+  // Generate output filename from input filename
+  const inputName = basename(psdPath, '.psd');
+  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, PSD 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}`;
+  };
 
-## Parsing the PSD File
+  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);
+  }
 
-Use `PSDParser.fromFile()` with `createWebEncodeBufferToPNG()` for browser environments. After parsing, the scene is immediately available in the engine:
+  // 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);
 
-```typescript highlight=highlight-parse-psd
-// 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;
+  return { archivePath, sceneStringPath, warnings, errors };
 }
-
-// Parse the PSD file using the PSD importer
-// The addGfontsAssetLibrary() call above enables automatic font matching
-// For custom font mapping, pass fontResolver in options (see customFontResolver example)
-const parser = await PSDParser.fromFile(
-  engine,
-  buffer,
-  createWebEncodeBufferToPNG(),
-  { fontResolver: customFontResolver }
-);
-const result = await parser.parse();
 ```
 
-The parser creates a new scene in the engine with all supported PSD elements converted to CE.SDK blocks. The result object contains a logger with messages about the import process.
+The `convertPSDToArchive` function:
 
-## Saving as Archive
+1. Reads the PSD file from disk as a buffer
+2. Creates a parser instance with the Node.js PNG encoder
+3. Parses the PSD, creating a scene in the engine
+4. Extracts warnings and errors from the logger
+5. Saves the scene as a `.cesdk` archive file
 
-After parsing, save the imported scene as an archive. This creates a portable bundle containing the scene and all its assets:
+## Batch Converting Multiple PSD Files
 
-```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);
-```
+Process multiple PSD files sequentially, continuing even if individual files fail:
 
-Archives can be stored, shared, or loaded later using `loadFromArchiveURL()`.
+```typescript highlight=highlight-batch-convert
+/**
+ * Batch convert multiple PSD files to CE.SDK scene formats
+ * Processes files sequentially, continuing even if individual files fail
+ */
+async function batchConvertPsds(
+  psdPaths: string[],
+  outputDir: string
+): Promise<void> {
+  console.log(`Starting batch conversion of ${psdPaths.length} PSD 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,
+  });
 
-## Saving Scenes with Stable URLs
+  try {
+    // Configure Google Fonts for text element support
+    // Note: Cast engine to any because psd-importer types expect browser engine
+    await addGfontsAssetLibrary(engine as any);
 
-By default, the PSD importer creates internal `buffer://` URLs for imported images. These are transient resources that work well when saving to an archive (`engine.scene.saveToArchive()`), which bundles all assets together.
+    let successCount = 0;
+    let failCount = 0;
 
-However, if you want to save scenes as JSON strings (`engine.scene.saveToString()`) with stable, permanent URLs (e.g., for storing in a database or referencing CDN-hosted assets), you need to relocate the transient resources first.
+    // Process each PSD file
+    for (const psdPath of psdPaths) {
+      const fileName = basename(psdPath);
+      console.log(`\nProcessing: ${fileName}`);
 
-### Why Relocate?
+      try {
+        const { archivePath, sceneStringPath, warnings, errors } =
+          await convertPsd(engine, psdPath, outputDir);
 
-- **Scene Archives** (`saveToArchive`): Include all assets in a single ZIP file. Transient `buffer://` URLs work fine.
-- **Scene Strings** (`saveToString`): Only contain references to assets. Transient URLs won't work when reloading the scene later. You need permanent URLs (e.g., `https://`).
+        // Log results
+        if (errors.length > 0) {
+          console.log(`  Errors: ${errors.length}`);
+          errors.forEach((e) => console.log(`    - ${e}`));
+        }
+        if (warnings.length > 0) {
+          console.log(`  Warnings: ${warnings.length}`);
+          warnings.forEach((w) => console.log(`    - ${w}`));
+        }
 
-### How to Relocate Transient Resources
+        console.log(`  Archive: ${archivePath}`);
+        console.log(`  Scene:   ${sceneStringPath}`);
+        successCount++;
+      } catch (error) {
+        console.error(`  Failed: ${(error as Error).message}`);
+        failCount++;
+      }
+    }
 
-After parsing the PSD file, use CE.SDK's native APIs to find and relocate all transient resources:
+    console.log(`\nBatch conversion complete:`);
+    console.log(`  Success: ${successCount}/${psdPaths.length}`);
+    console.log(`  Failed: ${failCount}/${psdPaths.length}`);
+  } finally {
+    // Always dispose engine to free resources
+    engine.dispose();
+  }
+}
+```
 
-```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, PSD 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);
-};
+Key aspects of batch conversion:
+
+- **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
+
+## Processing a Directory
+
+Scan a directory for PSD files and convert all of them:
+
+```typescript highlight=highlight-process-directory
+/**
+ * Find all PSD files in a directory and convert them
+ */
+export async function processDirectory(
+  inputDir: string,
+  outputDir: string
+): Promise<void> {
+  // Find all PSD files in directory
+  const files = await fs.readdir(inputDir);
+  const psdFiles = files
+    .filter((f) => f.toLowerCase().endsWith('.psd'))
+    .map((f) => join(inputDir, f));
+
+  if (psdFiles.length === 0) {
+    console.log(`No PSD files found in ${inputDir}`);
+    return;
+  }
 
-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);
+  await batchConvertPsds(psdFiles, outputDir);
 }
-const sceneString = await engine.scene.saveToString();
-console.log(`Scene persisted with stable URLs (${sceneString.length} bytes)`);
 ```
 
-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
-4. Relocate the resource URL using `engine.editor.relocateResource()`
-5. Save to string with `engine.scene.saveToString()` - all URLs will now be permanent
+This function finds all `.psd` files in the input directory and processes them as a batch.
 
-### Note on Font URLs
+## Validating Conversion Results
 
-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.
+Load a converted archive and verify its structure:
 
-## Loading into the Editor
+```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,
+  });
 
-Load the archived scene into the CE.SDK editor for user editing:
+  try {
+    // Load the archive
+    const archiveBuffer = await fs.readFile(archivePath);
+    const archiveBlob = new Blob([archiveBuffer]);
+    const archiveUrl = URL.createObjectURL(archiveBlob);
 
-```typescript highlight=highlight-load-editor
-// Load the archived scene into the editor
-await cesdk.engine.scene.loadFromArchiveURL(archiveUrl);
+    await engine.scene.loadFromArchiveURL(archiveUrl);
 
-// Verify scene loaded correctly
-const pages = engine.scene.getPages();
-console.log(`PSD imported successfully with ${pages.length} page(s)`);
+    // Get scene information
+    const pages = engine.block.findByType('page');
+    const allBlocks = engine.block.findAll();
 
-// Zoom to fit the imported page
-await cesdk.actions.run('zoom.toPage', { page: 'first', autoFit: true });
+    return {
+      valid: pages.length > 0,
+      pageCount: pages.length,
+      blockCount: allBlocks.length
+    };
+  } finally {
+    engine.dispose();
+  }
+}
 ```
 
-After loading, verify the scene contains at least one page. The imported design is now ready for editing in the CE.SDK editor.
+Validation checks:
 
-## Creating a PSD Template Library
+- The archive can be loaded without errors
+- At least one page exists in the scene
+- Block count indicates content was imported
 
-Add a custom asset source that provides PSD templates users can select from a library panel. This allows users to browse and apply pre-defined PSD designs directly from the editor UI:
+## Running the Conversion
 
-```typescript highlight=highlight-asset-source
-// Add custom asset source for PSD templates
-engine.asset.addSource({
-  id: PSD_SOURCE_ID,
+The main entry point demonstrates the complete batch conversion workflow:
 
-  async findAssets(
-    queryData: AssetQueryData
-  ): Promise<AssetsQueryResult<AssetResult>> {
-    let assets = SAMPLE_PSD_FILES;
+```typescript highlight=highlight-main
+/**
+ * Main entry point - demonstrates batch PSD conversion workflow
+ */
+async function main(): Promise<void> {
+  console.log('PSD to CE.SDK Batch Converter');
+  console.log('=============================\n');
+
+  // Example: Convert a single PSD file
+  // In production, you would provide actual PSD files
+  const engine = await CreativeEngine.init({
+    // license: process.env.CESDK_LICENSE,
+  });
 
-    // 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))
-      );
-    }
+  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 PSD 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 PSD files:');
+    console.log('1. Place PSD files in an input directory');
+    console.log('2. Call: await processDirectory("./input", "./output")');
+  } finally {
+    engine.dispose();
+  }
+}
+```
 
-    return {
-      assets,
-      total: assets.length,
-      currentPage: queryData.page,
-      nextPage: undefined
-    };
-  },
+Run the script with `vite-node` or `tsx`:
 
-  async applyAsset(asset: AssetResult): Promise<number | undefined> {
-    if (!asset.meta?.uri) {
-      console.error('Asset has no URI');
-      return undefined;
-    }
+```bash
+npx vite-node server-js.ts
+```
 
-    await importPsd(asset.meta.uri as string, asset.label || asset.id);
-    return undefined; // Scene replaced, no new block created
-  }
-});
+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);
 ```
 
-The asset source implements `findAssets()` to return a list of available PSD templates with thumbnails, and `applyAsset()` to import the selected PSD when users click on a template. The imported scene replaces the current editor content.
+Archives are portable - convert on server, load in browser or another server instance.
 
-## Custom Font Resolution
+## Saving Scenes with Stable URLs
 
-For advanced use cases, create a custom font resolver to control how PSD fonts map to available typefaces. This is useful when you need to:
+By default, the PSD importer creates internal `buffer://` URLs for imported images. These are transient resources that work well when saving to an archive (`engine.scene.saveToArchive()`), which bundles all assets together.
 
-- **Map proprietary fonts** - Replace Photoshop fonts with specific alternatives (e.g., Arial to Open Sans)
-- **Use enterprise fonts** - Integrate with custom font libraries or brand-specific typefaces
-- **Implement fallback logic** - Define priority-based font matching with graceful degradation
-- **Validate fonts** - Ensure only approved fonts are used in imported designs
+However, if you want to save scenes as JSON strings (`engine.scene.saveToString()`) with stable, permanent URLs (e.g., for storing in a database or referencing CDN-hosted assets), you need to relocate the transient resources first.
 
-```typescript highlight=highlight-custom-font-resolver
-// Optional: Create a custom font resolver for advanced font mapping
-// Use this when you need to map Photoshop fonts to specific alternatives,
-// use enterprise fonts, or implement custom fallback logic
-const customFontResolver: TypefaceResolver = async (fontParams, eng) => {
-  const { family, style, weight } = fontParams;
+### Why Relocate?
 
-  // Define font mappings from Photoshop fonts to available alternatives
-  const fontMappings: Record<string, string> = {
-    Arial: 'Open Sans',
-    Helvetica: 'Inter',
-    'Helvetica Neue': 'Inter',
-    'Times New Roman': 'Lora',
-    Georgia: 'Merriweather'
-  };
+- **Scene Archives** (`saveToArchive`): Include all assets in a single ZIP file. Transient `buffer://` URLs work fine.
+- **Scene Strings** (`saveToString`): Only contain references to assets. Transient URLs won't work when reloading the scene later. You need permanent URLs (e.g., `https://`).
 
-  // Use mapped font or original family name
-  const targetFamily = fontMappings[family] || family;
+### How to Relocate Transient Resources
 
-  // Search for the font in available typefaces
-  const result = await eng.asset.findAssets('ly.img.typeface', {
-    query: targetFamily,
-    page: 0,
-    perPage: 10
-  });
+After parsing the PSD file, use CE.SDK's native APIs to find and relocate all transient resources:
 
-  if (result.assets.length === 0) {
-    console.warn(`Font "${family}" not found, using default fallback`);
-    return null; // Let the parser use its default fallback
+```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, PSD 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);
   }
 
-  // Get the typeface from the asset payload
-  const asset = result.assets[0];
-  const typeface = asset.payload?.typeface;
-  if (!typeface) return null;
+  // 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);
+```
 
-  // 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];
+The relocation workflow:
 
-  return { typeface, font: matchingFont };
-};
-```
+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 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
 
-The font resolver receives font parameters (family, style, weight) from each text element in the PSD and returns a matching typeface and font from your available assets. Return `null` to let the parser use its default fallback behavior.
+### Note on Font URLs
 
-Pass the custom resolver to `PSDParser.fromFile()` via the options parameter. When both `addGfontsAssetLibrary()` and a custom resolver are used, the custom resolver takes precedence for font matching decisions.
+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.
 
 ## API Reference
 
 The `@imgly/psd-importer` package exports the following key APIs:
 
-| API                                                     | Description                                                                                                  |
-| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| `PSDParser.fromFile(engine, buffer, encoder, options?)` | Creates a parser instance from a PSD file buffer. Returns a parser with a `parse()` method.                  |
-| `createWebEncodeBufferToPNG()`                          | Creates a PNG encoder for browser environments using the Canvas API.                                         |
-| `addGfontsAssetLibrary(engine)`                         | Registers Google Fonts as a font source for text element matching. Call before parsing.                      |
-| `TypefaceResolver`                                      | Type for custom font resolver functions. Receives font parameters and returns a matching typeface/font pair. |
-| `options.fontResolver`                                  | `TypefaceResolver` - Custom function to resolve fonts from the PSD to available typefaces.                   |
-| `result.logger.getMessages()`                           | Returns an array of import messages with `type` ('warning' or 'error') and `message` properties.             |
+| API | Description |
+|-----|-------------|
+| `PSDParser.fromFile(engine, buffer, encoder, options?)` | Creates a parser instance from a PSD file buffer. Returns a parser with a `parse()` method. |
+| `createPNGJSEncodeBufferToPNG(PNG)` | Creates a PNG encoder for Node.js using the `pngjs` library. Pass the `PNG` constructor from `pngjs`. |
+| `addGfontsAssetLibrary(engine)` | Registers Google Fonts as a font source for text element matching. Call before parsing. |
+| `TypefaceResolver` | Type for custom font resolver functions. Receives font parameters and returns a matching typeface/font pair. |
+| `options.fontResolver` | `TypefaceResolver` - Custom function to resolve fonts from the PSD to available typefaces. |
+| `result.logger.getMessages()` | Returns an array of import messages with `type` ('warning' or 'error') and `message` properties. |
+
+**Type Casting Note:** The `@imgly/psd-importer` types expect the browser engine. When using `@cesdk/node`, cast the engine: `PSDParser.fromFile(engine as any, ...)`.
 
 ## Limitations
 
@@ -847,19 +817,21 @@ The PSD importer has the following limitations:
 
 ## Troubleshooting
 
-**Import fails silently:** Check the logger messages for errors using `result.logger.getMessages()`.
+**Conversion fails silently:** Check the logger messages from `result.logger.getMessages()`. The batch conversion functions log warnings and errors for each file.
+
+**Text appears with wrong font:** Ensure `addGfontsAssetLibrary()` is called before parsing. The importer attempts to match fonts with Google Fonts and uses a fallback for unavailable fonts.
+
+**Memory issues with large files:** Files over 900MB may encounter memory constraints. The importer gracefully skips problematic elements. Consider increasing Node.js memory with `--max-old-space-size`.
 
-**Text appears with wrong font:** Ensure `addGfontsAssetLibrary()` is called before parsing. Verify the font exists in Google Fonts. If not available, a fallback font is used.
+**Type errors with engine parameter:** The `@imgly/psd-importer` types expect the browser engine. Cast to `any` when using `@cesdk/node`: `PSDParser.fromFile(engine as any, ...)`.
 
-**Missing layers:** Some layer types or blend modes may not be supported. Check the import warnings for details about which layers couldn't be converted.
 
-**Large file handling:** Files over 900MB may encounter memory constraints. The importer gracefully skips problematic elements and continues with the rest of the file.
 
 ---
 
 ## 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