@imgly/codesign-mcp 0.1.5 → 0.1.7

package/assets/docs/guide/export-save-publish/save.md

@@ -1,4 +1,4 @@
-> This is one page of the CE.SDK Vanilla JS/TS documentation. For a complete overview, see the [Vanilla JS/TS Documentation Index](https://img.ly/docs/cesdk/js.md). For all docs in one file, see [llms-full.txt](./llms-full.txt.md).
+> This is one page of the CE.SDK Node.js documentation. For a complete overview, see the [Node.js Documentation Index](https://img.ly/docs/cesdk/node.md). For all docs in one file, see [llms-full.txt](./llms-full.txt.md).
 
 **Navigation:** [Guides](./guides.md) > [Save](./export-save-publish/save.md)
 
@@ -6,186 +6,152 @@
 
 Save and serialize designs in CE.SDK for later retrieval, sharing, or storage using string or archive formats.
 
-![Save designs showing different save format options](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
-
 > **Reading time:** 8 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)
+>
 > - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-export-save-publish-save-browser/)
 
 CE.SDK provides two formats for persisting designs. Choose the format based on your storage and portability requirements.
 
-```typescript file=@cesdk_web_examples/guides-export-save-publish-save-browser/browser.ts reference-only
-import type { EditorPlugin, EditorPluginContext } from '@cesdk/cesdk-js';
-import {
-  BlurAssetSource,
-  ColorPaletteAssetSource,
-  CropPresetsAssetSource,
-  DemoAssetSources,
-  EffectsAssetSource,
-  FiltersAssetSource,
-  PagePresetsAssetSource,
-  StickerAssetSource,
-  TextAssetSource,
-  TextComponentAssetSource,
-  TypefaceAssetSource,
-  UploadAssetSources,
-  VectorShapeAssetSource
-} from '@cesdk/cesdk-js/plugins';
-import { DesignEditorConfig } from './design-editor/plugin';
-import packageJson from './package.json';
+```typescript file=@cesdk_web_examples/guides-export-save-publish-save-server-js/server-js.ts reference-only
+import CreativeEngine from '@cesdk/node';
+import { CompressionFormat, CompressionLevel } from '@cesdk/node';
+import { writeFileSync, readFileSync, mkdirSync, existsSync } from 'fs';
+import { createInterface } from 'readline';
+import { config } from 'dotenv';
+import path from 'path';
+
+config();
 
 /**
- * CE.SDK Plugin: Save Designs Guide
+ * CE.SDK Server Guide: Save Designs
  *
- * Demonstrates how to save and serialize designs in CE.SDK:
+ * Demonstrates how to save and serialize designs:
  * - Saving scenes to string format for database storage
  * - Saving scenes to archive format with embedded assets
- * - Using built-in save actions and customization
+ * - Loading saved content back into the engine
  */
-class Example implements EditorPlugin {
-  name = packageJson.name;
-
-  version = packageJson.version;
-
-  async initialize({ cesdk }: EditorPluginContext): Promise<void> {
-    if (cesdk == null) {
-      throw new Error('CE.SDK instance is required');
-    }
-
-    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());
-
-    const engine = cesdk.engine;
-
-    await engine.scene.loadFromURL(
-      'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_postcard_1.scene'
-    );
-
-    const page = engine.scene.getCurrentPage();
-    if (page == null) {
-      throw new Error('No page found in scene');
-    }
-    engine.scene.zoomToBlock(page, { padding: 40 });
 
-    cesdk.actions.register('saveScene', async () => {
-      const sceneString = await engine.scene.saveToString();
-      // Send to your backend API
-      console.log('Custom save:', sceneString.length, 'bytes');
+function prompt(question: string): Promise<string> {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer);
     });
+  });
+}
 
-    // Button: Save Scene & Download
-    const handleSaveScene = async () => {
-      const sceneString = await engine.scene.saveToString();
-      const sceneBlob = new Blob([sceneString], {
-        type: 'application/octet-stream'
-      });
-      await cesdk.utils.downloadFile(sceneBlob, 'application/octet-stream');
-      cesdk.ui.showNotification({
-        message: `Scene downloaded (${(sceneString.length / 1024).toFixed(1)} KB)`,
-        type: 'success'
-      });
-    };
-
-    // Button: Save to Archive & Download
-    const handleSaveToArchive = async () => {
-      const archiveBlob = await engine.scene.saveToArchive();
-      await cesdk.utils.downloadFile(archiveBlob, 'application/zip');
-      cesdk.ui.showNotification({
-        message: `Archive downloaded (${(archiveBlob.size / 1024).toFixed(1)} KB)`,
-        type: 'success'
-      });
-    };
-
-    const handleLoadScene = async () => {
-      await cesdk.actions.run('importScene', { format: 'scene' });
-    };
-
-    const handleLoadArchive = async () => {
-      await cesdk.actions.run('importScene', { format: 'archive' });
-      const loadedPage = engine.scene.getCurrentPage();
-      if (loadedPage != null) {
-        engine.scene.zoomToBlock(loadedPage, { padding: 40 });
-      }
-    };
-
-    cesdk.ui.insertOrderComponent(
-      { in: 'ly.img.navigation.bar', position: 'end' },
-      {
-        id: 'ly.img.actions.navigationBar',
-        children: [
-          {
-            id: 'ly.img.action.navigationBar',
-            key: 'save-scene',
-            label: 'Save Scene',
-            icon: '@imgly/Save',
-            onClick: handleSaveScene
-          },
-          {
-            id: 'ly.img.action.navigationBar',
-            key: 'save-archive',
-            label: 'Save Archive',
-            icon: '@imgly/Download',
-            onClick: handleSaveToArchive
-          },
-          {
-            id: 'ly.img.action.navigationBar',
-            key: 'load-scene',
-            label: 'Load Scene',
-            icon: '@imgly/Upload',
-            onClick: handleLoadScene
-          },
-          {
-            id: 'ly.img.action.navigationBar',
-            key: 'load-archive',
-            label: 'Load Archive',
-            icon: '@imgly/Upload',
-            onClick: handleLoadArchive
-          }
-        ]
+console.log('\n=== CE.SDK Save Designs ===\n');
+console.log('Select save format:');
+console.log('  1. String (for database storage)');
+console.log('  2. Archive (self-contained ZIP)');
+console.log('  3. Both formats\n');
+
+const choice = await prompt('Enter choice (1/2/3): ');
+
+const saveString =
+  choice === '1' || choice === '3' || !['1', '2', '3'].includes(choice);
+const saveArchive =
+  choice === '2' || choice === '3' || !['1', '2', '3'].includes(choice);
+
+if (!['1', '2', '3'].includes(choice)) {
+  console.log('Invalid choice. Defaulting to both formats.\n');
+}
+
+console.log('⏳ Initializing Creative Engine...');
+
+const engine = await CreativeEngine.init({
+  baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
+  // license: process.env.CESDK_LICENSE
+});
+
+try {
+  console.log('⏳ Loading template scene...');
+
+  await engine.scene.loadFromURL(
+    'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_postcard_1.scene'
+  );
+
+  const page = engine.scene.getCurrentPage();
+  if (page == null) {
+    throw new Error('No page found in scene');
+  }
+
+  const outputDir = './output';
+  if (!existsSync(outputDir)) {
+    mkdirSync(outputDir, { recursive: true });
+  }
+
+  console.log('✅ Scene loaded\n');
+
+  if (saveString) {
+    console.log('⏳ Saving to string...');
+    const sceneString = await engine.scene.saveToString();
+    writeFileSync(`${outputDir}/scene.scene`, sceneString);
+    console.log(
+      `✅ Scene saved: output/scene.scene (${(sceneString.length / 1024).toFixed(1)} KB)`
+    );
+
+    // Example: Save with compression (requires local build)
+    // To run with compression: npm run dev:local
+    const compressed = await engine.scene.saveToString({
+      compression: {
+        format: CompressionFormat.Zstd,
+        level: CompressionLevel.Default
       }
+    });
+    writeFileSync(`${outputDir}/scene-compressed.scene`, compressed);
+    console.log(
+      `✅ Compressed scene saved: output/scene-compressed.scene (${(compressed.length / 1024).toFixed(1)} KB, ${((1 - compressed.length / sceneString.length) * 100).toFixed(1)}% smaller)`
     );
   }
-}
 
-export default Example;
+  if (saveArchive) {
+    console.log('⏳ Saving to archive...');
+    const archiveBlob = await engine.scene.saveToArchive();
+    const archiveBuffer = Buffer.from(await archiveBlob.arrayBuffer());
+    writeFileSync(`${outputDir}/scene.zip`, archiveBuffer);
+    console.log(
+      `✅ Archive saved: output/scene.zip (${(archiveBuffer.length / 1024).toFixed(1)} KB)`
+    );
+  }
+
+  if (saveString) {
+    console.log('\n⏳ Loading from saved scene file...');
+    const sceneString = readFileSync(`${outputDir}/scene.scene`, 'utf-8');
+    await engine.scene.loadFromString(sceneString);
+    console.log('✅ Scene loaded from file');
+  }
+
+  if (saveArchive) {
+    console.log('⏳ Loading from saved archive...');
+    const archivePath = path.resolve(`${outputDir}/scene.zip`);
+    const archiveFileUrl = `file://${archivePath}`;
+    await engine.scene.loadFromArchiveURL(archiveFileUrl);
+    console.log('✅ Scene loaded from archive');
+  }
+
+  console.log('\n🎉 Complete! Files saved to:', outputDir);
+} finally {
+  engine.dispose();
+}
 ```
 
 ## Save Format Comparison
 
-| Format  | Method            | Assets            | Best For                     |
-| ------- | ----------------- | ----------------- | ---------------------------- |
-| String  | `saveToString()`  | Referenced by URL | Database storage, cloud sync |
-| Archive | `saveToArchive()` | Embedded in ZIP   | Offline use, file sharing    |
+| Format | Method | Assets | Best For |
+| ------ | ------ | ------ | -------- |
+| String | `saveToString()` | Referenced by URL | Database storage, cloud sync |
+| Archive | `saveToArchive()` | Embedded in ZIP | Offline use, file sharing |
 
 **String format** produces a lightweight Base64-encoded string where assets remain as URL references. Use this when asset URLs will remain accessible.
 
@@ -211,117 +177,90 @@ const archiveBlob = await engine.scene.saveToArchive();
 
 The archive includes all pages, elements, and asset data in a single portable file.
 
-## Compression Options
+## Compression Options (Preview)
 
 CE.SDK supports optional compression for saved scenes to reduce file size. Compression is particularly useful for large scenes or when storage space is limited.
 
 ```typescript
+import { CompressionFormat, CompressionLevel } from '@cesdk/node';
+
 // Save with Zstd compression (recommended)
-const compressed = await cesdk.engine.scene.saveToString({
-  compression: {
-    format: 'Zstd',
-    level: 'Default'
-  }
-});
+const compressed = await engine.scene.saveToString(
+  undefined, // allowedResourceSchemes
+  undefined, // onDisallowedResourceScheme
+  CompressionFormat.Zstd,    // compression format
+  CompressionLevel.Default   // compression level
+);
 ```
 
 **Compression Formats:**
 
-- `'None'` - No compression (default)
-- `'Zstd'` - Zstandard compression (recommended for best performance)
+- `CompressionFormat.None` - No compression (default)
+- `CompressionFormat.Zstd` - Zstandard compression (recommended for best performance)
 
 **Compression Levels:**
 
-- `'Fastest'` - Fastest compression, larger output
-- `'Default'` - Balanced speed and size (recommended)
-- `'Best'` - Best compression, slower
+- `CompressionLevel.Fastest` - Fastest compression, larger output
+- `CompressionLevel.Default` - Balanced speed and size (recommended)
+- `CompressionLevel.Best` - Best compression, slower
 
 **Performance:** Compression adds minimal overhead (\<50ms) while reducing scene size by approximately 64%. The Default level provides the best balance of speed and compression ratio.
 
-## Download to User Device
+**Availability:**
 
-Use `cesdk.utils.downloadFile()` to trigger a browser download with the correct MIME type.
+- **Browser (Web)**: Available in current release via `@cesdk/cesdk-js`
+- **Node.js**: Available in development builds. Use `npm run dev:local` in examples to test with local build, or wait for the next package release
+- **iOS/Android**: Planned for future releases
 
-For scene strings, convert to a Blob first:
+## Write to File System
 
-```typescript highlight=highlight-download-scene
-const sceneBlob = new Blob([sceneString], {
-  type: 'application/octet-stream'
-});
-await cesdk.utils.downloadFile(sceneBlob, 'application/octet-stream');
-```
+Use Node.js `writeFileSync` to persist saved designs to the file system.
 
-For archive blobs, pass directly to the download utility:
+Scene strings can be written directly as text:
 
-```typescript highlight=highlight-download-archive
-await cesdk.utils.downloadFile(archiveBlob, 'application/zip');
+```typescript highlight=highlight-write-scene
+writeFileSync(`${outputDir}/scene.scene`, sceneString);
 ```
 
-This utility handles creating and revoking object URLs automatically.
+For archives, convert the Blob to a Buffer before writing:
+
+```typescript highlight=highlight-write-archive
+const archiveBuffer = Buffer.from(await archiveBlob.arrayBuffer());
+writeFileSync(`${outputDir}/scene.zip`, archiveBuffer);
+```
 
 ## Load Scene from File
 
-Use the built-in `importScene` action to open a file picker for `.scene` files. This restores a previously saved design from its serialized string format.
+Read a previously saved `.scene` file from disk and restore it to the engine.
 
 ```typescript highlight=highlight-load-scene
-const handleLoadScene = async () => {
-  await cesdk.actions.run('importScene', { format: 'scene' });
-};
+const sceneString = readFileSync(`${outputDir}/scene.scene`, 'utf-8');
+await engine.scene.loadFromString(sceneString);
 ```
 
 Scene files are lightweight but require the original asset URLs to remain accessible.
 
 ## Load Archive from File
 
-Load a self-contained `.zip` archive that includes all embedded assets.
+Read a self-contained `.zip` archive from disk with all embedded assets.
 
 ```typescript highlight=highlight-load-archive
-const handleLoadArchive = async () => {
-  await cesdk.actions.run('importScene', { format: 'archive' });
+const archivePath = path.resolve(`${outputDir}/scene.zip`);
+const archiveFileUrl = `file://${archivePath}`;
+await engine.scene.loadFromArchiveURL(archiveFileUrl);
 ```
 
 Archives are portable and work offline since all assets are bundled within the file.
 
-## Built-in Save Action
-
-CE.SDK includes a built-in `saveScene` action that integrates with the navigation bar.
-
-### Running an Action
-
-Trigger the default save behavior programmatically using `actions.run()`:
-
-```typescript
-await cesdk.actions.run('saveScene');
-```
-
-This executes the registered handler for `saveScene`, which by default downloads the scene file.
-
-### Customizing an Action
-
-Override the default behavior by registering a custom handler:
-
-```typescript highlight=highlight-register-custom-action
-cesdk.actions.register('saveScene', async () => {
-  const sceneString = await engine.scene.saveToString();
-  // Send to your backend API
-  console.log('Custom save:', sceneString.length, 'bytes');
-});
-```
-
-The registered handler runs when the built-in save button is clicked or when the action is triggered via `actions.run()`.
-
 ## API Reference
 
-| Method                              | Description                                                     |
-| ----------------------------------- | --------------------------------------------------------------- |
-| `engine.scene.saveToString()`       | Serialize scene to Base64 string                                |
-| `engine.scene.saveToArchive()`      | Save scene with assets as ZIP blob                              |
-| `engine.scene.loadFromString()`     | Load scene from serialized string                               |
-| `engine.scene.loadFromURL()`        | Load scene from remote URL                                      |
+| Method | Description |
+| ------ | ----------- |
+| `engine.scene.saveToString()` | Serialize scene to Base64 string |
+| `engine.scene.saveToArchive()` | Save scene with assets as ZIP blob |
+| `engine.scene.loadFromString()` | Load scene from serialized string |
+| `engine.scene.loadFromURL()` | Load scene from remote URL |
 | `engine.scene.loadFromArchiveURL()` | Load scene from URL (file://, http://, https://, or object URL) |
-| `cesdk.utils.downloadFile()`        | Download blob or string to user device                          |
-| `cesdk.actions.run()`               | Execute a registered action with parameters                     |
-| `cesdk.actions.register()`          | Register or override an action handler                          |
 
 ## Next Steps
 
@@ -330,11 +269,13 @@ The registered handler runs when the built-in save button is clicked or when the
 - [Store Custom Metadata](./export-save-publish/store-custom-metadata.md) - Attach metadata like tags or version info to designs
 - [Partial Export](./export-save-publish/export/partial-export.md) - Export individual blocks or selections
 
+
+
 ---
 
 ## 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