@imgly/codesign-mcp 0.1.5 → 0.1.7

package/assets/docs/guide/performance.md

@@ -1,217 +1,324 @@
-> 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) > [Improve Performance](./performance.md)
 
 ---
 
-Optimize CE.SDK integration for faster load times, efficient memory usage, and
-smooth runtime performance in browser environments.
+Optimize CE.SDK integration for faster startup, efficient memory usage, and
+reliable performance in Node.js server environments.
 
-CE.SDK has a large bundle size that can impact initial page load. Optimizing how you load, use, and dispose of the editor improves application performance and user experience.
+The `@cesdk/node` package provides full CreativeEngine functionality for server-side processing. Optimizing how you load, use, and dispose of the engine improves throughput and resource efficiency in production environments.
 
-This guide covers code splitting techniques to defer loading, source sets for managing large assets, export optimization with workers and quality settings, and proper lifecycle management.
+This guide covers code splitting for serverless environments, memory monitoring for long-running processes, export timeout configuration, and proper lifecycle management patterns.
 
 ## Code Splitting
 
-Delay loading the engine module to improve initial page load time. Use dynamic imports to load the engine only when needed.
+Use dynamic imports to load the engine only when needed. This reduces cold start time in serverless environments where the engine may not be used for every request.
 
-### Using a Bundler
+```ts
+async function loadCreativeEngine(): Promise<typeof CreativeEngine> {
+  console.log('Lazy loading CreativeEngine...');
+  const startTime = Date.now();
 
-Use dynamic `import()` with bundlers like Webpack, Rollup, or Vite to create separate chunks that load on demand. The bundler automatically handles code splitting when you use dynamic imports.
+  // Dynamic import - engine module is loaded only when this function is called
+  const { default: CreativeEngine } = await import('@cesdk/node');
 
-```ts
-async function loadCreativeEditorSDK(): Promise<typeof CreativeEditorSDK> {
-  const { default: CreativeEditorSDK } = await import('@cesdk/cesdk-js');
-  return CreativeEditorSDK;
+  const loadTime = Date.now() - startTime;
+  console.log(`CreativeEngine loaded in ${loadTime}ms`);
+
+  return CreativeEngine;
 }
 ```
 
-This approach keeps CE.SDK in a separate bundle that loads only when `loadCreativeEditorSDK()` is called. Users who never open the editor avoid downloading the SDK entirely.
+This pattern defers engine loading until `loadCreativeEngine()` is called. In serverless functions, requests that don't require image processing skip the engine load entirely.
+
+## Memory Management
 
-### Using CDN
+Monitor memory usage in long-running server processes using the editor's memory APIs. This helps detect memory accumulation across requests and triggers cleanup actions.
 
-Load CE.SDK directly from CDN using dynamic imports. This works in modern browsers without any build tooling.
+### Monitoring Memory Usage
+
+Use `engine.editor.getUsedMemory()` to check current memory consumption and `engine.editor.getAvailableMemory()` to check remaining capacity.
 
 ```ts
-async function loadCreativeEditorSDK(): Promise<typeof CreativeEditorSDK> {
-  const { default: CreativeEditorSDK } =
-    await import('https://cdn.img.ly/packages/imgly/cesdk-js/$UBQ_VERSION$/index.js');
-  return CreativeEditorSDK;
+function logMemoryStats(engine: CreativeEngine, label: string): void {
+  const usedMemory = engine.editor.getUsedMemory();
+  const availableMemory = engine.editor.getAvailableMemory();
+
+  // Convert to Number for arithmetic (memory APIs may return BigInt)
+  const usedNum = Number(usedMemory);
+  const availableNum = Number(availableMemory);
+  const totalMemory = usedNum + availableNum;
+  const usagePercentage = ((usedNum / totalMemory) * 100).toFixed(2);
+
+  console.log(`Memory Stats [${label}]:`);
+  console.log(`  Used: ${formatBytes(usedMemory)}`);
+  console.log(`  Available: ${formatBytes(availableMemory)}`);
+  console.log(`  Usage: ${usagePercentage}%`);
 }
-```
 
-CDN loading offloads bandwidth from your servers and leverages global CDN caching for faster delivery.
+function formatBytes(bytes: number | bigint): string {
+  const numBytes = typeof bytes === 'bigint' ? Number(bytes) : bytes;
+  if (numBytes === 0) return '0 Bytes';
+  const k = 1024;
+  const sizes = ['Bytes', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(numBytes) / Math.log(k));
+  return parseFloat((numBytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
+}
+```
 
-## Managing Large Assets
+Track these values across requests to:
 
-High-resolution images and videos consume significant memory. Optimize asset loading to reduce memory pressure and improve performance.
+- Detect memory accumulation that indicates leaks
+- Trigger engine disposal and recreation when approaching limits
+- Log memory metrics for production monitoring
 
-### Use Source Sets
+### Calculating Usage Percentage
 
-Source sets allow you to provide multiple resolution variants of the same image. The engine automatically selects the most appropriate resolution based on the current display size, loading smaller images for previews and higher resolution assets only when needed for exports.
+Calculate memory usage as a percentage to implement automatic cleanup thresholds. Memory APIs may return BigInt values, so convert to Number for arithmetic operations.
 
 ```ts
-const imageFill = engine.block.createFill('image');
-
-engine.block.setSourceSet(imageFill, 'fill/image/sourceSet', [
-  {
-    uri: 'https://img.ly/static/ubq_samples/sample_1_512x341.jpg',
-    width: 512,
-    height: 341
-  },
-  {
-    uri: 'https://img.ly/static/ubq_samples/sample_1_1024x683.jpg',
-    width: 1024,
-    height: 683
-  },
-  {
-    uri: 'https://img.ly/static/ubq_samples/sample_1_2048x1366.jpg',
-    width: 2048,
-    height: 1366
-  }
-]);
+const usedMemory = engine.editor.getUsedMemory();
+const availableMemory = engine.editor.getAvailableMemory();
+
+// Convert to Number for arithmetic (memory APIs may return BigInt)
+const usedNum = Number(usedMemory);
+const availableNum = Number(availableMemory);
+const totalMemory = usedNum + availableNum;
+const usagePercentage = (usedNum / totalMemory) * 100;
 
-engine.block.setFill(block, imageFill);
+if (usagePercentage > 80) {
+  console.warn('High memory usage detected, consider disposing engine');
+}
 ```
 
-This approach reduces initial load times and memory usage during editing while ensuring high-quality exports. See [Source Sets](./import-media/source-sets.md) for more details.
+### Managing Memory in Request Handlers
 
-### Additional Optimization Tips
+For HTTP servers or queue workers, reset state between requests to prevent memory accumulation:
 
-- Remove unused assets from the scene when no longer needed
-- Dispose the engine when the editing session ends
-- Use optimized image formats (WebP, AVIF) for faster loading
+- Clear the scene before processing each request
+- Avoid storing references to blocks across requests
+- Consider disposing and recreating the engine after a threshold of requests
 
 ## Export Optimization
 
-Optimize export performance through worker configuration and export settings.
-
-### Use Export Workers
+Configure export behavior for reliable processing of large designs or complex scenes.
 
-CE.SDK uses Web Workers to offload export rendering to background threads, keeping the main thread responsive during exports. Workers are enabled by default for both image and video exports.
+### Export Timeouts
 
-For video exports, the `exportWorker` configuration option controls worker usage:
+Configure inactivity timeouts to prevent hanging exports. Use `engine.unstable_setExportInactivityTimeout()` for image exports and `engine.unstable_setVideoExportInactivityTimeout()` for video exports.
 
 ```ts
-const config = {
-  license: 'YOUR_CESDK_LICENSE_KEY',
-  callbacks: {
-    exportWorker: true // Enabled by default
-  }
-};
-
-const cesdk = await CreativeEditorSDK.create('#cesdk_container', config);
+// Configure export timeouts for reliability
+engine.unstable_setExportInactivityTimeout(30_000);
+engine.unstable_setVideoExportInactivityTimeout(60_000);
+console.log('Export timeouts configured (30s image, 60s video)');
 ```
 
-### Optimize Export Settings
+The default timeout is 10 seconds. Increase this value for:
 
-Adjust export parameters to balance quality and performance:
-
-- **Lower resolution**: Reduce `targetWidth` and `targetHeight` for faster exports on slower devices
-- **Adjust quality**: Use lower JPEG quality (0.7-0.8) for smaller file sizes and faster encoding
-- **Choose efficient formats**: WebP typically offers better compression than PNG for images with transparency
-
-```ts
-// Export with optimized settings for performance
-const blob = await engine.block.export(page, 'image/jpeg', {
-  targetWidth: 1920,
-  targetHeight: 1080,
-  jpegQuality: 0.8
-});
-```
+- High-resolution exports (4K+)
+- Complex scenes with many elements
+- Video exports with multiple tracks
+- Servers with limited CPU resources
 
 ### Export Size Limits
 
-Check device export capabilities before attempting large exports using `engine.editor.getMaxExportSize()`.
+Check export capabilities before processing large designs using `engine.editor.getMaxExportSize()`.
 
 ```ts
 const maxExportSize = engine.editor.getMaxExportSize();
+console.log('Max export size:', maxExportSize, 'pixels');
 
-// Verify design fits within limits
+// Validate design dimensions before export
 const pageWidth = engine.block.getWidth(page);
 const pageHeight = engine.block.getHeight(page);
 
 if (pageWidth > maxExportSize || pageHeight > maxExportSize) {
-  console.warn(
-    'Design exceeds maximum export size - consider reducing dimensions'
-  );
+  throw new Error('Design exceeds maximum export size');
 }
 ```
 
-This returns the maximum dimension in pixels that the device can reliably export.
+Validate design dimensions against this limit before starting export to fail fast on oversized designs.
 
 ## Engine Lifecycle
 
-Follow proper patterns for initializing and disposing the engine to prevent memory leaks and ensure consistent behavior.
+Follow proper patterns for initializing and disposing the engine to prevent memory leaks and ensure consistent behavior across requests.
 
 ### Initialization
 
-Initialize the engine once and reuse the instance. Pass essential configuration including license key and baseURL.
+Initialize the engine with minimal configuration for server environments. The engine doesn't need UI-related settings.
 
 ```ts
-import CreativeEditorSDK from '@cesdk/cesdk-js';
+import CreativeEngine from '@cesdk/node';
 
 const config = {
-  license: 'YOUR_CESDK_LICENSE_KEY',
-  baseURL: 'https://cdn.img.ly/packages/imgly/cesdk-engine/$UBQ_VERSION$/assets'
+  license: process.env.CESDK_LICENSE || '',
+  logger: (level: string, ...args: unknown[]) => {
+    if (level === 'error' || level === 'warn') {
+      console.log(`[${level}]`, ...args);
+    }
+  }
 };
 
-const cesdk = await CreativeEditorSDK.create('#cesdk_container', config);
-const engine = cesdk.engine;
+const engine = await CreativeEngine.init(config);
+```
+
+Consider logging levels carefully in production to avoid excessive log output.
+
+### Engine Reuse Patterns
+
+For server environments, choose between per-request engines or a shared engine based on your workload:
+
+**Per-Request Pattern** (recommended for serverless):
+
+```ts
+async function handleRequest(designData: Buffer): Promise<Buffer> {
+  const CreativeEngine = await loadCreativeEngine();
+  const engine = await CreativeEngine.init(config);
+
+  try {
+    const result = await processDesign(engine, designData);
+    return result;
+  } finally {
+    engine.dispose();
+  }
+}
 ```
 
-When using the full CE.SDK (not just the engine), the editor creates a managed canvas element accessible via `cesdk.engine`. Avoid creating multiple engine instances simultaneously.
+**Shared Engine Pattern** (for long-running servers):
+
+```ts
+let engine: CreativeEngine | null = null;
+
+async function getEngine(): Promise<CreativeEngine> {
+  if (!engine) {
+    const CreativeEngine = await loadCreativeEngine();
+    engine = await CreativeEngine.init(config);
+  }
+  return engine;
+}
+
+async function handleRequest(designData: Buffer): Promise<Buffer> {
+  const eng = await getEngine();
+
+  // Clear previous state
+  const scenes = eng.scene.findAll();
+  scenes.forEach((scene) => eng.block.destroy(scene));
+
+  return processDesign(eng, designData);
+}
+```
 
 ### Disposal
 
-Call `dispose()` when the editing session ends to free all resources including GPU memory, textures, and native allocations.
+Always dispose the engine when processing completes to free native resources. In serverless environments, dispose before the function returns:
+
+```ts
+async function processDesign(engine: CreativeEngine): Promise<void> {
+  try {
+    // Process the design
+    await doWork(engine);
+  } finally {
+    // Always dispose to free resources
+    engine.dispose();
+    console.log('Engine disposed');
+  }
+}
+```
+
+For shared engines in long-running processes, dispose on process shutdown:
 
 ```ts
-cesdk.dispose();
+process.on('SIGTERM', async () => {
+  if (engine) {
+    engine.dispose();
+  }
+  process.exit(0);
+});
 ```
 
-After disposal, the engine instance becomes unusable. Create a new instance if the user returns to the editor.
+## Serverless Considerations
+
+Serverless environments have specific constraints that affect CE.SDK performance:
 
-## Asset Loading
+### Cold Start Optimization
 
-For production deployments, host engine assets on your own servers to improve reliability and reduce dependency on external CDNs. Configure `baseURL` to point to your asset location.
+- Use code splitting to defer engine loading
+- Pre-warm functions that process designs frequently
+- Consider provisioned concurrency for latency-sensitive workloads
 
-See [Serve Assets From Your Server](./serve-assets.md) for detailed setup instructions.
+### Memory Limits
+
+- Monitor memory usage against function limits
+- Configure function memory to accommodate engine requirements (minimum 512MB recommended)
+- Dispose engine promptly to avoid memory accumulation
+
+### Execution Time
+
+- Set appropriate function timeouts for export operations
+- Configure export inactivity timeouts below function timeout
+- Stream large exports instead of buffering in memory
 
 ## Troubleshooting
 
-### Large Initial Load Time
+### High Memory Usage
+
+Monitor memory with `getUsedMemory()` and `getAvailableMemory()`. If memory accumulates across requests:
 
-Implement code splitting to defer engine loading until needed. Use dynamic imports with bundlers or CDN loading to keep the main bundle small.
+- Ensure `dispose()` is called after each request in per-request patterns
+- Clear scenes between requests in shared engine patterns
+- Consider periodic engine recreation in long-running processes
 
-### Slow Export Performance
+### Slow Cold Starts
 
-Enable export workers (default) and reduce export resolution or quality settings. For complex scenes, consider exporting at a lower resolution and scaling up if needed.
+Implement code splitting to defer engine loading. For latency-sensitive workloads:
+
+- Use provisioned concurrency in serverless environments
+- Implement keep-alive requests to prevent function cold starts
+- Pre-load the engine during process initialization
+
+### Export Timeouts
+
+Increase timeout using `unstable_setExportInactivityTimeout()` for images or `unstable_setVideoExportInactivityTimeout()` for videos. For persistent issues:
+
+- Reduce export resolution
+- Simplify scene complexity
+- Increase server CPU resources
 
 ### Memory Leaks
 
-Ensure `dispose()` is called when the editor is closed. In SPAs, use cleanup functions in component lifecycle hooks to dispose the engine on unmount.
+If memory grows unbounded:
+
+- Verify `dispose()` is called in all code paths, including error handlers
+- Check for stored references to engine blocks
+- Implement periodic engine recreation as a safety measure
 
 ## API Reference
 
-| Method                             | Description                            |
-| ---------------------------------- | -------------------------------------- |
-| `CreativeEditorSDK.create()`       | Initialize a new CE.SDK instance       |
-| `cesdk.dispose()`                  | Clean up all resources                 |
-| `engine.editor.getMaxExportSize()` | Get maximum export dimension in pixels |
-| `engine.block.export()`            | Export a block to image or video       |
+| Method                                              | Description                            |
+| --------------------------------------------------- | -------------------------------------- |
+| `CreativeEngine.init()`                             | Initialize a new engine instance       |
+| `engine.dispose()`                                  | Clean up engine resources              |
+| `engine.editor.getUsedMemory()`                     | Get current memory usage in bytes      |
+| `engine.editor.getAvailableMemory()`                | Get available memory in bytes          |
+| `engine.editor.getMaxExportSize()`                  | Get maximum export dimension in pixels |
+| `engine.unstable_setExportInactivityTimeout()`      | Configure image export timeout         |
+| `engine.unstable_setVideoExportInactivityTimeout()` | Configure video export timeout         |
 
 ## Next Steps
 
 - [Architecture](./concepts/architecture.md) - Understand CE.SDK structure and components
-- [Headless Mode](./concepts/headless-mode/browser.md) - Run the engine without UI for automation
+- [Headless Mode](./concepts/headless-mode.md) - Run the engine without UI for automation
 - [Export Overview](./export-save-publish/export/overview.md) - Learn about export formats and options
 
+
+
 ---
 
 ## 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