@imgly/codesign-mcp 0.1.5 → 0.1.6

package/assets/docs/guide/create-composition/collage.md

@@ -1,432 +1,650 @@
-> This is one page of the CE.SDK Vanilla JS/TS documentation. For a complete overview, see the [Vanilla JS/TS Documentation Index](https://img.ly/docs/cesdk/js.md). For all docs in one file, see [llms-full.txt](./llms-full.txt.md).
+> This is one page of the CE.SDK Node.js documentation. For a complete overview, see the [Node.js Documentation Index](https://img.ly/docs/cesdk/node.md). For all docs in one file, see [llms-full.txt](./llms-full.txt.md).
 
 **Navigation:** [Guides](./guides.md) > [Create and Edit Compositions](./create-composition.md) > [Create a Collage](./create-composition/collage.md)
 
 ---
 
-This guide shows you how to add a **Collage** feature in your web app with the help of the CE.SDK. A collage allows you to reuse images and assets as you change the layout of the scene.
+Create collages in a headless Node.js environment by loading layout templates and transferring image content between scenes.
 
-<Picture src={demoCollage} style={{ width: '100%' }} alt="Example of a layout change in the demo app" formats={['webp']} />
-
-> **Reading time:** 15 minutes
+> **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/blob/main/showcase-layouts/src/components/case/CaseComponent.jsx)
-> - [Open in StackBlitz](https://stackblitz.com/fork/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/showcase-layouts?title=IMG.LY+CE.SDK%3A+Layouts&file=src%2Fcomponents%2Fcase%2FCaseComponent.jsx)
-> - [Live demo](https://img.ly/showcases/cesdk/layouts/web)
+>
+> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-create-composition-collage-server-js)
+>
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-create-composition-collage-server-js)
+
+In server-side workflows, collages are created by loading a layout scene file that defines the visual structure, then transferring content from an existing scene into those positions. This approach enables batch processing of images into various collage formats.
+
+```typescript file=@cesdk_web_examples/guides-create-composition-collage-server-js/server-js.ts reference-only
+import CreativeEngine, { DesignBlockId } from '@cesdk/node';
+import { writeFileSync } from 'fs';
+import { config as loadEnv } from 'dotenv';
+
+// Load environment variables
+loadEnv();
+
+/**
+ * Create a Collage (Server/Node.js)
+ *
+ * This example demonstrates how to create collages programmatically:
+ * 1. Creating a scene with images
+ * 2. Loading a layout scene file
+ * 3. Transferring content from the original scene to the layout
+ * 4. Exporting the final collage
+ */
+
+// Sort blocks by visual position (top-to-bottom, left-to-right)
+// This ensures consistent content mapping between layouts
+function visuallySortBlocks(
+  engine: CreativeEngine,
+  blocks: DesignBlockId[]
+): DesignBlockId[] {
+  return blocks
+    .map((block) => ({
+      block,
+      x: Math.round(engine.block.getPositionX(block)),
+      y: Math.round(engine.block.getPositionY(block))
+    }))
+    .sort((a, b) => {
+      if (a.y === b.y) return a.x - b.x;
+      return a.y - b.y;
+    })
+    .map((item) => item.block);
+}
 
-**Layouts** in CE.SDK are predefined templates that dictate how to arrange images and assets within a single composition. They allow you to create visually appealing collages by specifying each image’s:
+// Recursively collect all descendant blocks
+function getChildrenTree(
+  engine: CreativeEngine,
+  blockId: DesignBlockId
+): DesignBlockId[] {
+  const children = engine.block.getChildren(blockId);
+  const result: DesignBlockId[] = [];
+  for (const child of children) {
+    result.push(child);
+    result.push(...getChildrenTree(engine, child));
+  }
+  return result;
+}
 
-- Position
-- Size
-- Orientation relative to other assets on the page
+async function run() {
+  let engine: CreativeEngine | undefined;
+
+  try {
+    const config = {
+  baseURL: process.env.IMGLY_LOCAL_ASSETS_URL,
+      // license: process.env.CESDK_LICENSE,
+      logger: (message: string, logLevel?: string) => {
+        if (logLevel === 'ERROR' || logLevel === 'WARN') {
+          console.log(`[${logLevel}]`, message);
+        }
+      }
+    };
 
-Layouts instantly create visuals and allow you to skip manually arranging each asset.
+    engine = await CreativeEngine.init(config);
+    console.log('✓ Engine initialized');
+
+    // Create a scene with images to arrange in a collage
+    const scene = engine.scene.create();
+    const page = engine.block.create('page');
+    engine.block.appendChild(scene, page);
+
+    // Set page dimensions for the collage
+    engine.block.setWidth(page, 1080);
+    engine.block.setHeight(page, 1080);
+
+    // Add sample images to the page
+    const imageUrls = [
+      'https://img.ly/static/ubq_samples/imgly_logo.jpg',
+      'https://img.ly/static/ubq_samples/sample_1.jpg',
+      'https://img.ly/static/ubq_samples/sample_2.jpg',
+      'https://img.ly/static/ubq_samples/sample_3.jpg'
+    ];
+
+    for (let i = 0; i < imageUrls.length; i++) {
+      const graphic = engine.block.create('graphic');
+      const imageFill = engine.block.createFill('image');
+      engine.block.setString(
+        imageFill,
+        'fill/image/imageFileURI',
+        imageUrls[i]
+      );
+      engine.block.setFill(graphic, imageFill);
 
-## What You’ll Learn
+      // Position images in a simple grid (will be rearranged by layout)
+      engine.block.setPositionX(graphic, (i % 2) * 540);
+      engine.block.setPositionY(graphic, Math.floor(i / 2) * 540);
+      engine.block.setWidth(graphic, 540);
+      engine.block.setHeight(graphic, 540);
 
-In this guide, you will learn how to:
+      engine.block.appendChild(page, graphic);
+    }
 
-- Set up the layout panel in the CE.SDK UI.
-- Use a layout file for collages.
-- Use TypeScript to apply layouts in your custom UI.
+    console.log(`✓ Scene created with ${imageUrls.length} images`);
+
+    // Load a layout template that defines the collage structure
+    // The layout contains positioned placeholder blocks
+    const layoutUrl =
+      'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_collage_1.scene';
+
+    const layoutSceneString = await fetch(layoutUrl).then((res) => res.text());
+    const layoutBlocks = await engine.block.loadFromString(layoutSceneString);
+    const layoutPage = layoutBlocks[0];
+
+    console.log('✓ Layout template loaded');
+
+    // Collect image blocks from both pages
+    const sourceBlocks = getChildrenTree(engine, page);
+    const sourceImages = sourceBlocks.filter(
+      (id) => engine!.block.getKind(id) === 'image'
+    );
+    const sortedSourceImages = visuallySortBlocks(engine, sourceImages);
+
+    const layoutChildren = getChildrenTree(engine, layoutPage);
+    const layoutImages = layoutChildren.filter(
+      (id) => engine!.block.getKind(id) === 'image'
+    );
+    const sortedLayoutImages = visuallySortBlocks(engine, layoutImages);
+
+    console.log(
+      `✓ Found ${sortedSourceImages.length} source images, ${sortedLayoutImages.length} layout slots`
+    );
+
+    // Transfer image content from source to layout positions
+    const transferCount = Math.min(
+      sortedSourceImages.length,
+      sortedLayoutImages.length
+    );
+
+    for (let i = 0; i < transferCount; i++) {
+      const sourceBlock = sortedSourceImages[i];
+      const targetBlock = sortedLayoutImages[i];
+
+      // Get the source image fill
+      const sourceFill = engine.block.getFill(sourceBlock);
+      const targetFill = engine.block.getFill(targetBlock);
+
+      // Transfer the image URI
+      const imageUri = engine.block.getString(
+        sourceFill,
+        'fill/image/imageFileURI'
+      );
+      engine.block.setString(targetFill, 'fill/image/imageFileURI', imageUri);
+
+      // Transfer source sets if present
+      try {
+        const sourceSet = engine.block.getSourceSet(
+          sourceFill,
+          'fill/image/sourceSet'
+        );
+        if (sourceSet.length > 0) {
+          engine.block.setSourceSet(
+            targetFill,
+            'fill/image/sourceSet',
+            sourceSet
+          );
+        }
+      } catch {
+        // Source set not available, skip
+      }
+
+      // Reset crop to fill the new frame dimensions
+      engine.block.resetCrop(targetBlock);
+
+      // Transfer placeholder behavior if supported
+      if (engine.block.supportsPlaceholderBehavior(sourceBlock)) {
+        engine.block.setPlaceholderBehaviorEnabled(
+          targetBlock,
+          engine.block.isPlaceholderBehaviorEnabled(sourceBlock)
+        );
+      }
+    }
 
-## When to Use Layouts
+    console.log(`✓ Transferred ${transferCount} images to layout`);
 
-The CE.SDK **Layout** feature is ideal for:
+    // Transfer text content (if both scenes have text blocks)
+    const sourceTexts = sourceBlocks.filter(
+      (id) => engine!.block.getType(id) === '//ly.img.ubq/text'
+    );
+    const layoutTexts = layoutChildren.filter(
+      (id) => engine!.block.getType(id) === '//ly.img.ubq/text'
+    );
 
-- Photo collages
-- Grid layouts
-- Magazine spreads
-- Social media posts
+    const sortedSourceTexts = visuallySortBlocks(engine, sourceTexts);
+    const sortedLayoutTexts = visuallySortBlocks(engine, layoutTexts);
 
-## Difference Between Layouts and Templates
+    const textTransferCount = Math.min(
+      sortedSourceTexts.length,
+      sortedLayoutTexts.length
+    );
 
-Layouts are [custom assets](./import-media/concepts.md) that differ from templates:
+    for (let i = 0; i < textTransferCount; i++) {
+      const sourceText = sortedSourceTexts[i];
+      const targetText = sortedLayoutTexts[i];
 
-- **Templates:** Load **new assets** and replace the existing scene.
-- **Layouts:** Keep existing assets but change their arrangement on the page.
+      // Transfer text content
+      const text = engine.block.getString(sourceText, 'text/text');
+      engine.block.setString(targetText, 'text/text', text);
 
-Preserving assets while changing the layout **isn’t a native CE.SDK feature**. The following sections explain how to leverage the CE.SDK to do it in your app using JavaScript.
+      // Transfer font
+      const fontUri = engine.block.getString(sourceText, 'text/fontFileUri');
+      const typeface = engine.block.getTypeface(sourceText);
+      engine.block.setFont(targetText, fontUri, typeface);
 
-## How Collages Work
+      // Transfer text color
+      const textColor = engine.block.getColor(sourceText, 'fill/solid/color');
+      engine.block.setColor(targetText, 'fill/solid/color', textColor);
+    }
 
-When you choose a collage layout, the app needs to:
+    if (textTransferCount > 0) {
+      console.log(`✓ Transferred ${textTransferCount} text blocks`);
+    }
 
-1. Load a new layout file.
-2. Extract content from your current design.
-3. Map content to new layout positions.
-4. Preserve images and text in visual order.
+    // Export the final collage
+    // Use the layout page dimensions for the export
+    const layoutWidth = engine.block.getWidth(layoutPage);
+    const layoutHeight = engine.block.getHeight(layoutPage);
+
+    const blob = await engine.block.export(layoutPage, {
+      mimeType: 'image/png',
+      targetWidth: layoutWidth,
+      targetHeight: layoutHeight
+    });
+
+    const buffer = Buffer.from(await blob.arrayBuffer());
+    writeFileSync('collage-output.png', buffer);
+    console.log(
+      `✓ Exported collage to collage-output.png (${layoutWidth}x${layoutHeight})`
+    );
+
+    // Clean up temporary blocks
+    engine.block.destroy(page);
+    console.log('✓ Cleanup completed');
+
+    console.log('\n✓ Collage created successfully!');
+  } catch (error) {
+    console.error('Error:', error);
+    process.exit(1);
+  } finally {
+    // Always dispose the engine
+    engine?.dispose();
+    console.log('\n✓ Engine disposed');
+  }
+}
 
-You trigger this workflow when a user selects a layout from the **Layouts** panel in the CE.SDK UI.
+// Run the example
+run();
+```
 
-## Add a Layouts Panel to the CE.SDK UI
+This guide covers how to load layout templates, implement visual sorting to map content between layouts, transfer images and text while preserving properties, and export the final collage.
 
-The CE.SDK allows you to add [custom panels to the UI](./user-interface/customization/panel.md). To add a **Layouts** panel for collage selection, you need to create it and load custom assets to configure its appearance and behavior.
+## How Server-Side Collages Work
 
-For this action, you need:
+Server-side collage creation follows this workflow:
 
-1. A layout file defining the collage structure (use [this one](https://github.com/imgly/cesdk-web-examples/blob/main/showcase-layouts/src/components/case/CustomLayouts.json) to get started).
-2. Thumbnail images for preview (find a collection [here](https://github.com/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/showcase-layouts/public/cases/layouts)).
+1. **Create a scene with images** — Load or create blocks containing your source images
+2. **Load a layout template** — Fetch a scene file that defines the collage structure
+3. **Sort blocks visually** — Order blocks by position for consistent mapping
+4. **Transfer content** — Copy image URIs and text from source to layout positions
+5. **Export the result** — Generate the final collage image
 
-### 1. Add a Layouts Option to the CE.SDK Menu
+The layout template defines where images appear in the final output. By sorting blocks visually (top-to-bottom, left-to-right), content maps predictably between different layouts.
 
-To **customize the CE.SDK UI** and create a **Layouts** panel, use the CE.SDK UserInterfaceAPI. Add a Layout button with `ui.setComponentOrder({ in: 'ly.img.dock' }, order)`, using the following properties:
+## Initialize the Engine
 
-- `id`
-- `key`
-- `label`
-- `icon`
-- `entries`
+Start by initializing the headless engine.
 
-For example:
+```typescript highlight=highlight-setup
+    const config = {
+  baseURL: process.env.IMGLY_LOCAL_ASSETS_URL,
+      // license: process.env.CESDK_LICENSE,
+      logger: (message: string, logLevel?: string) => {
+        if (logLevel === 'ERROR' || logLevel === 'WARN') {
+          console.log(`[${logLevel}]`, message);
+        }
+      }
+    };
 
-```ts
-cesdk.ui.setComponentOrder({ in: 'ly.img.dock' }, [
-  {
-    id: 'ly.img.assetLibrary.dock',
-    key: 'layouts-dock-entry',
-    label: 'Layouts',
-    icon: '@imgly/Layout',
-    entries: ['layouts']
-  }
-]);
+    engine = await CreativeEngine.init(config);
+    console.log('✓ Engine initialized');
 ```
 
-<Picture src={addLayoutsToUI} style={{ width: '80%' }} alt="Default dock vs. custom dock with layout option." formats={['webp']} />
-
-### 2. Customize the Layouts Panel Appearance
-
-To configure how the **Layouts** panel looks and behaves, use the `ui.addAssetLibraryEntry()` helper with the following options:
+## Create a Scene with Images
+
+Create a scene containing the images you want to arrange in the collage. In production, you might load these from a database or API.
+
+```typescript highlight=highlight-create-scene
+    // Create a scene with images to arrange in a collage
+    const scene = engine.scene.create();
+    const page = engine.block.create('page');
+    engine.block.appendChild(scene, page);
+
+    // Set page dimensions for the collage
+    engine.block.setWidth(page, 1080);
+    engine.block.setHeight(page, 1080);
+
+    // Add sample images to the page
+    const imageUrls = [
+      'https://img.ly/static/ubq_samples/imgly_logo.jpg',
+      'https://img.ly/static/ubq_samples/sample_1.jpg',
+      'https://img.ly/static/ubq_samples/sample_2.jpg',
+      'https://img.ly/static/ubq_samples/sample_3.jpg'
+    ];
+
+    for (let i = 0; i < imageUrls.length; i++) {
+      const graphic = engine.block.create('graphic');
+      const imageFill = engine.block.createFill('image');
+      engine.block.setString(
+        imageFill,
+        'fill/image/imageFileURI',
+        imageUrls[i]
+      );
+      engine.block.setFill(graphic, imageFill);
 
-- `id`: Unique identifier for the panel.
-- `sourceIds`: Which assets to display.
-- `previewLength`: How many preview items to display in the panel.
-- `gridColumns`: How many columns to contain the previews in the panel.
-- `gridItemHeight`: The shape of each tile in the panel grid.
-- `previewBackgroundType`: How to fit the previews inside their tiles (cover/contain).
-- `gridBackgroundType`: How to display the panel background (cover/contain).
+      // Position images in a simple grid (will be rearranged by layout)
+      engine.block.setPositionX(graphic, (i % 2) * 540);
+      engine.block.setPositionY(graphic, Math.floor(i / 2) * 540);
+      engine.block.setWidth(graphic, 540);
+      engine.block.setHeight(graphic, 540);
 
-For example, the demo uses this configuration:
+      engine.block.appendChild(page, graphic);
+    }
 
-```jsx title="CustomCase.jsx"
-instance.ui.addAssetLibraryEntry({
-  id: 'ly.img.layouts', // Referenced in the dock entry in Step 1
-  sourceIds: ['ly.img.layouts'], // Points to our custom layout asset source
-  previewLength: 2, // Number of preview items int the compact panel
-  gridColumns: 2, // Organize tiles in 2 columns
-  gridItemHeight: 'square', // Square tiles
-  previewBackgroundType: 'contain', // Fit compact panel background
-  gridBackgroundType: 'contain' // Fit panel background
-});
+    console.log(`✓ Scene created with ${imageUrls.length} images`);
 ```
 
-<Picture src={panelLayout} style={{ width: '80%' }} alt="Default dock vs. custom dock with layout option." formats={['webp']} />
-
-To learn more about panel customization, check the [Panel Customization guide](./user-interface/customization/panel.md).
+## Load a Layout Template
 
-### 3. Load Custom Assets
+Load a layout scene file that defines the collage structure. Layout templates contain positioned image blocks that serve as placeholders.
 
-The demo uses a [helper function](https://github.com/imgly/cesdk-web-examples/blob/main/showcase-layouts/src/components/case/lib/loadAssetSourceFromContentJSON.ts) to load a custom layout asset source from a JSON file. This file defines the available layouts and their metadata. You can reuse this logic by defining both:
+```typescript highlight=highlight-load-layout
+    // Load a layout template that defines the collage structure
+    // The layout contains positioned placeholder blocks
+    const layoutUrl =
+      'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_collage_1.scene';
 
-- A `ContentJSON` object (like `CustomLayouts.json`)
-- A `baseURL` for your custom assets that replaces the `{{base_url}}`.
+    const layoutSceneString = await fetch(layoutUrl).then((res) => res.text());
+    const layoutBlocks = await engine.block.loadFromString(layoutSceneString);
+    const layoutPage = layoutBlocks[0];
 
-```jsx title="CustomCase.jsx"
-import { createApplyLayoutAsset } from './lib/createApplyLayoutAsset';
-import loadAssetSourceFromContentJSON from './lib/loadAssetSourceFromContentJSON';
-
-// ...
-const caseAssetPath = (path, caseId = 'layouts') =>
-  `${process.env.NEXT_PUBLIC_URL_HOSTNAME}${process.env.NEXT_PUBLIC_URL}/cases/${caseId}${path}`;
-
-// Call the helper to load the layout assets
-loadAssetSourceFromContentJSON(
-  instance.engine, // Pss the CE.SDK engine to load assets into
-  LAYOUT_ASSETS, // Pass the JSON bundle
-  caseAssetPath(''), // Base URL for assets
-  createApplyLayoutAsset(instance.engine) // Callback to createApplyLayoutAsset.js helper
-);
-await instance.loadFromURL(caseAssetPath('/custom-layouts.scene')); // Load the scene
-// ...
+    console.log('✓ Layout template loaded');
 ```
 
-In the previous example, the helper accepts an optional **applyAsset callback**, so:
-
-1. A user picks a layout from the library.
-2. The engine invokes the callback to apply it.
-3. The engine replaces the current page’s structure with the layout while keeping the user’s images/text.
-
-Asset preservation isn't a CE.SDK native feature. It’s handled in the `createApplyLayoutAsset.js` helper, which you can find in [the repository](https://github.com/imgly/cesdk-web-examples/blob/main/showcase-layouts/src/components/case/lib/createApplyLayoutAsset.js).
-
-## Apply the Collage
-
-When applying a collage, the following actions need to be implemented:
-
-1. Changing the structure of the design.
-2. Transferring the existing content to the new structure.
-3. Deleting the previous scene.
-
-You can find this workflow in the `createApplyLayoutAsset()` helper from the demo. Follow these steps to replicate it:
-
-### 1. Prepare and Allow changes
-
-- Allow block deletion with `editor.setGlobalScope('lifecycle/destroy', 'Allow')`.
-- Clear the selected blocks with `block.setSelected(block, false)`.
-
-```js title="createApplyLayoutAsset.js"
-const scopeBefore = engine.editor.getGlobalScope('lifecycle/destroy');
-engine.editor.setGlobalScope('lifecycle/destroy', 'Allow');
-const page = engine.scene.getCurrentPage();
-engine.block
-  .findAllSelected()
-  .forEach((block) => engine.block.setSelected(block, false));
+## Sort Blocks by Visual Position
+
+Visual sorting ensures consistent content mapping regardless of the order blocks were created. Blocks are sorted top-to-bottom, then left-to-right.
+
+```typescript highlight=highlight-visual-sort
+// Sort blocks by visual position (top-to-bottom, left-to-right)
+// This ensures consistent content mapping between layouts
+function visuallySortBlocks(
+  engine: CreativeEngine,
+  blocks: DesignBlockId[]
+): DesignBlockId[] {
+  return blocks
+    .map((block) => ({
+      block,
+      x: Math.round(engine.block.getPositionX(block)),
+      y: Math.round(engine.block.getPositionY(block))
+    }))
+    .sort((a, b) => {
+      if (a.y === b.y) return a.x - b.x;
+      return a.y - b.y;
+    })
+    .map((item) => item.block);
+}
 ```
 
-### 2. Load the New Layout
+## Collect Blocks from Both Scenes
 
-- Load the new layout with `block.loadFromString()`.
-- Return the first page from the loaded blocks as the layout page.
+Recursively collect all descendant blocks, then filter by type to separate images from other content.
 
-```js title="createApplyLayoutAsset.js"
-const sceneString = await fetch(asset.meta.uri).then((response) =>
-  response.text()
-);
-const blocks = await engine.block.loadFromString(sceneString);
-const layoutPage = blocks[0];
-```
+```typescript highlight=highlight-collect-blocks
+    // Collect image blocks from both pages
+    const sourceBlocks = getChildrenTree(engine, page);
+    const sourceImages = sourceBlocks.filter(
+      (id) => engine!.block.getKind(id) === 'image'
+    );
+    const sortedSourceImages = visuallySortBlocks(engine, sourceImages);
 
-### 3. Backup Current Page
+    const layoutChildren = getChildrenTree(engine, layoutPage);
+    const layoutImages = layoutChildren.filter(
+      (id) => engine!.block.getKind(id) === 'image'
+    );
+    const sortedLayoutImages = visuallySortBlocks(engine, layoutImages);
 
-- Duplicate the current page with `block.duplicate()` to keep a backup of the existing content.
-- The CE.SDK uses this backup to transfer images and text to the new layout.
-- Clear the current page structure by destroying all its children.
-
-```js title="createApplyLayoutAsset.js"
-const oldPage = engine.block.duplicate(page);
-engine.block.getChildren(page).forEach((child) => {
-  engine.block.destroy(child);
-});
-engine.block.getChildren(layoutPage).forEach((child) => {
-  engine.block.insertChild(page, child, engine.block.getChildren(page).length);
-});
+    console.log(
+      `✓ Found ${sortedSourceImages.length} source images, ${sortedLayoutImages.length} layout slots`
+    );
 ```
 
-### 4. Transfer Content
-
-Copy user text and images onto the new layout:
+## Transfer Image Content
 
-```js title="createApplyLayoutAsset.js"
-copyAssets(engine, oldPage, page);
-```
+Copy image URIs and source sets from source blocks to layout positions. Reset the crop on each target block so images fill their new frames.
 
-### 5. Sort Blocks Visually and Pair Content
+```typescript highlight=highlight-transfer-images
+    // Transfer image content from source to layout positions
+    const transferCount = Math.min(
+      sortedSourceImages.length,
+      sortedLayoutImages.length
+    );
 
-Grab text and image blocks from both pages in visual order (top to bottom, left to right):
+    for (let i = 0; i < transferCount; i++) {
+      const sourceBlock = sortedSourceImages[i];
+      const targetBlock = sortedLayoutImages[i];
 
-```js title="createApplyLayoutAsset.js"
-const fromChildren = visuallySortBlocks(
-  engine,
-  getChildrenTree(engine, fromPageId).flat()
-);
-const textsOnFromPage = fromChildren.filter((childId) =>
-  engine.block.getType(childId).includes('text')
-);
-const imagesOnFromPage = fromChildren.filter(
-  (childId) => engine.block.getKind(childId) === 'image'
-);
-// same for toPageId -> textsOnToPage, imagesOnToPage
-```
+      // Get the source image fill
+      const sourceFill = engine.block.getFill(sourceBlock);
+      const targetFill = engine.block.getFill(targetBlock);
 
-Then apply the content from the old page to the new layout by looping through the blocks:
-
-<Tabs>
-  <TabItem label="Step 1: Copy text content, font, color">
-    ```js title="createApplyLayoutAsset.js"
-
-    const fromText = engine.block.getString(fromBlock, 'text/text');
-    const fromFontFileUri = engine.block.getString(fromBlock, 'text/fontFileUri');
-    const fromTypeface = engine.block.getTypeface(fromBlock);
-    engine.block.setFont(toBlock, fromFontFileUri, fromTypeface);
-    const fromTextFillColor = engine.block.getColor(fromBlock, 'fill/solid/color');
-    engine.block.setString(toBlock, 'text/text', fromText);
-    engine.block.setColor(toBlock, 'fill/solid/color', fromTextFillColor);
-
-    ```
-
-  </TabItem>
-
-  <TabItem label="Step 2: Copy images and placeholder behavior">
-    ```js title="createApplyLayoutAsset.js"
-
-    const fromImageFill = engine.block.getFill(fromBlock);
-    const toImageFill = engine.block.getFill(toBlock);
-    const fromImageFileUri = engine.block.getString(fromImageFill, 'fill/image/imageFileURI');
-    engine.block.setString(toImageFill, 'fill/image/imageFileURI', fromImageFileUri);
-    const fromImageSourceSets = engine.block.getSourceSet(fromImageFill, 'fill/image/sourceSet');
-    engine.block.setSourceSet(toImageFill, 'fill/image/sourceSet', fromImageSourceSets);
-    if (engine.block.supportsPlaceholderBehavior(fromBlock)) {
-      engine.block.setPlaceholderBehaviorEnabled(
-        toBlock,
-        engine.block.isPlaceholderBehaviorEnabled(fromBlock)
+      // Transfer the image URI
+      const imageUri = engine.block.getString(
+        sourceFill,
+        'fill/image/imageFileURI'
       );
+      engine.block.setString(targetFill, 'fill/image/imageFileURI', imageUri);
+
+      // Transfer source sets if present
+      try {
+        const sourceSet = engine.block.getSourceSet(
+          sourceFill,
+          'fill/image/sourceSet'
+        );
+        if (sourceSet.length > 0) {
+          engine.block.setSourceSet(
+            targetFill,
+            'fill/image/sourceSet',
+            sourceSet
+          );
+        }
+      } catch {
+        // Source set not available, skip
+      }
+
+      // Reset crop to fill the new frame dimensions
+      engine.block.resetCrop(targetBlock);
+
+      // Transfer placeholder behavior if supported
+      if (engine.block.supportsPlaceholderBehavior(sourceBlock)) {
+        engine.block.setPlaceholderBehaviorEnabled(
+          targetBlock,
+          engine.block.isPlaceholderBehaviorEnabled(sourceBlock)
+        );
+      }
     }
-    engine.block.resetCrop(toBlock);
 
-    ```
-
-  </TabItem>
-</Tabs>
+    console.log(`✓ Transferred ${transferCount} images to layout`);
+```
 
-### 6. Cleanup and Restore State
+**Key methods:**
 
-Cleanup temporary blocks with `block.destroy()` and restore global scope:
+- `getFill()` and `setString()` — Transfer the image URI between fills
+- `getSourceSet()` and `setSourceSet()` — Preserve responsive image variants
+- `resetCrop()` — Adjust the image crop to fill the new frame dimensions
+- `supportsPlaceholderBehavior()` — Check and transfer placeholder settings
 
-```js title="createApplyLayoutAsset.js"
-engine.block.destroy(oldPage);
-engine.block.destroy(layoutPage);
-engine.editor.setGlobalScope('lifecycle/destroy', scopeBefore);
-if (config.addUndoStep) {
-  engine.editor.addUndoStep();
-}
-return page;
-```
+## Transfer Text Content
 
-This keeps the editor stable and predictable after the layout changes and prevents:
+If both scenes contain text blocks, transfer text content, fonts, and colors in visual order.
 
-- Stray selections.
-- Ghost placeholders.
-- Unused assets left at the scene.
+```typescript highlight=highlight-transfer-text
+    // Transfer text content (if both scenes have text blocks)
+    const sourceTexts = sourceBlocks.filter(
+      (id) => engine!.block.getType(id) === '//ly.img.ubq/text'
+    );
+    const layoutTexts = layoutChildren.filter(
+      (id) => engine!.block.getType(id) === '//ly.img.ubq/text'
+    );
 
-## Advanced Collage Techniques
+    const sortedSourceTexts = visuallySortBlocks(engine, sourceTexts);
+    const sortedLayoutTexts = visuallySortBlocks(engine, layoutTexts);
 
-<Tabs>
-  <TabItem label="Keep Placeholder Behavior">
-    The CE.SDK BlockAPI eases the transfer of [placeholder behavior](./create-templates/add-dynamic-content/placeholders.md) when moving images between blocks. You can use it to:
+    const textTransferCount = Math.min(
+      sortedSourceTexts.length,
+      sortedLayoutTexts.length
+    );
 
-    1. Checks if the block supports placeholder behavior with `supportsPlaceholderBehavior`.
-    2. Apply the same setting to the target image block with:
+    for (let i = 0; i < textTransferCount; i++) {
+      const sourceText = sortedSourceTexts[i];
+      const targetText = sortedLayoutTexts[i];
 
-    - `isPlaceholderBehaviorEnabled()`
-    - `setPlaceholderBehaviorEnabled()`
+      // Transfer text content
+      const text = engine.block.getString(sourceText, 'text/text');
+      engine.block.setString(targetText, 'text/text', text);
 
-    ```js title="createApplyLayoutAsset.js"
+      // Transfer font
+      const fontUri = engine.block.getString(sourceText, 'text/fontFileUri');
+      const typeface = engine.block.getTypeface(sourceText);
+      engine.block.setFont(targetText, fontUri, typeface);
 
-    if (engine.block.supportsPlaceholderBehavior(fromBlock)) {
-      engine.block.setPlaceholderBehaviorEnabled(
-        toBlock,
-        engine.block.isPlaceholderBehaviorEnabled(fromBlock),
-      );
+      // Transfer text color
+      const textColor = engine.block.getColor(sourceText, 'fill/solid/color');
+      engine.block.setColor(targetText, 'fill/solid/color', textColor);
     }
-    ```
 
-    This maintains the behavior of current placeholders after the layout swap.
+    if (textTransferCount > 0) {
+      console.log(`✓ Transferred ${textTransferCount} text blocks`);
+    }
+```
 
-  </TabItem>
+## Export the Collage
 
-  <TabItem label="Distribute Content Evenly">
-    To ensure the CE.SDK uses all the existing images when applying a layout, you can:
+Export the layout page with the transferred content. The output dimensions match the layout template.
 
-    1. Handle overflow when more images than slots:
+```typescript highlight=highlight-export
+    // Export the final collage
+    // Use the layout page dimensions for the export
+    const layoutWidth = engine.block.getWidth(layoutPage);
+    const layoutHeight = engine.block.getHeight(layoutPage);
 
-    ```js title="createApplyLayoutAsset.js"
+    const blob = await engine.block.export(layoutPage, {
+      mimeType: 'image/png',
+      targetWidth: layoutWidth,
+      targetHeight: layoutHeight
+    });
 
-    for (
-      let index = 0;
-      index < imagesOnToPage.length && index < imagesOnFromPage.length;
-      index++
-    ) { ... }
+    const buffer = Buffer.from(await blob.arrayBuffer());
+    writeFileSync('collage-output.png', buffer);
+    console.log(
+      `✓ Exported collage to collage-output.png (${layoutWidth}x${layoutHeight})`
+    );
+```
 
-    ```
+## Clean Up
 
-    2. Fill empty slots with defaults or placeholders:
+Destroy temporary blocks and dispose of the engine when finished.
 
-    ```js title="createApplyLayoutAsset.js"
+```typescript highlight=highlight-cleanup
+// Clean up temporary blocks
+engine.block.destroy(page);
+console.log('✓ Cleanup completed');
+```
 
-    // loop condition ends when sources run out, leaving remaining target slots unchanged
-    index < imagesOnToPage.length && index < imagesOnFromPage.length;
+## Handling Mismatched Slot Counts
 
-    ```
+When the source has more images than the layout has slots, extra images are ignored. When the layout has more slots, some remain empty or keep their placeholder content.
 
-    3. List content by importance or metadata:
+```typescript
+// Transfer only as many images as both sides support
+const transferCount = Math.min(
+  sortedSourceImages.length,
+  sortedLayoutImages.length
+);
+```
 
-    ```js title="createApplyLayoutAsset.js"
+For production use, consider:
 
-    const visuallySortBlocks = (engine, blocks) => {
-      const blocksWithCoordinates = blocks
-        .map((block) => ({
-          block,
-          coordinates: [
-            Math.round(engine.block.getPositionX(block)),
-            Math.round(engine.block.getPositionY(block))
-          ]
-        }))
-        .sort(({ coordinates: [X1, Y1] }, { coordinates: [X2, Y2] }) => {
-          if (Y1 === Y2) return X1 - X2;
-          return Y1 - Y2;
-        });
-      return blocksWithCoordinates.map(({ block }) => block);
-    };
+- Selecting layouts based on image count
+- Filling empty slots with placeholder images
+- Prioritizing images by metadata or user selection
 
-    ```
+## Troubleshooting
 
-  </TabItem>
+### Images Not Appearing in Layout
 
-  <TabItem label="Animate Layout Transitions">
-    For a better user experience, consider adding animations when applying layouts:
+Verify the layout template contains image blocks with the correct kind. Check that `engine.block.getKind(id)` returns `'image'` for your target blocks.
 
-    ```tsx title="LoadingSpinner.tsx"
-    const LoadingSpinner = () => {
-      return <div className={styles.spinner} data-cy={'loading-spinner'}></div>;
-    };
-    ```
+### Content in Wrong Positions
 
-    You can code more customizations to incorporate these effects into collage transitions:
+Visual sorting depends on block coordinates. If blocks have identical Y positions, they sort by X. Ensure layout templates have distinct positions for each slot.
 
-    - Fading
-    - Sliding
-    - Morphing
+### Source Sets Not Transferring
 
-  </TabItem>
-</Tabs>
+Not all image fills have source sets. Wrap the transfer in a try-catch to handle blocks without this property.
 
-## Optimize the Layout Workflow
+### Layout Template Not Loading
 
-For a better user experience when creating collages, consider these optimizations:
+Check that the layout URL is accessible from your server environment. In production, host layout templates on your own infrastructure or use a CDN.
 
-| Topic                | Strategies                                                                                                                                             |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **Asset Loading**    | ・ Lazy load thumbnails and cache scene files<br />・ Preload common layouts and minimize file sizes<br />・ Use CDN for efficient asset delivery      |
-| **Content Transfer** | ・ Batch block operations to reduce engine calls<br />・ Optimize sorting algorithms and memory usage<br />・ Handle large page structures efficiently |
-| **Visual Cues**      | ・ Show loading states and support undo/redo<br />・ Add error recovery and prevent accidental changes                                                 |
+## API Reference
 
-## Troubleshooting
+| Method | Category | Purpose |
+|--------|----------|---------|
+| `engine.scene.create()` | Scene | Create an empty scene |
+| `engine.block.create()` | Block | Create blocks of various types |
+| `engine.block.createFill()` | Fill | Create fill objects for blocks |
+| `engine.block.setFill()` | Fill | Assign a fill to a block |
+| `engine.block.getFill()` | Fill | Get the fill assigned to a block |
+| `engine.block.loadFromString()` | Import | Load blocks from a scene string |
+| `engine.block.getChildren()` | Hierarchy | Get direct children of a block |
+| `engine.block.appendChild()` | Hierarchy | Add a child to a block |
+| `engine.block.getKind()` | Property | Get the semantic kind of a block |
+| `engine.block.getType()` | Property | Get the type of a block |
+| `engine.block.getPositionX()` | Layout | Get X position of a block |
+| `engine.block.getPositionY()` | Layout | Get Y position of a block |
+| `engine.block.getString()` | Property | Get string property value |
+| `engine.block.setString()` | Property | Set string property value |
+| `engine.block.getSourceSet()` | Fill | Get image source set |
+| `engine.block.setSourceSet()` | Fill | Set image source set |
+| `engine.block.resetCrop()` | Crop | Reset crop to fill frame |
+| `engine.block.supportsPlaceholderBehavior()` | Placeholder | Check placeholder support |
+| `engine.block.isPlaceholderBehaviorEnabled()` | Placeholder | Check if placeholder is enabled |
+| `engine.block.setPlaceholderBehaviorEnabled()` | Placeholder | Enable/disable placeholder |
+| `engine.block.getTypeface()` | Text | Get typeface of a text block |
+| `engine.block.setFont()` | Text | Set font for a text block |
+| `engine.block.getColor()` | Property | Get color property value |
+| `engine.block.setColor()` | Property | Set color property value |
+| `engine.block.getWidth()` | Layout | Get width of a block |
+| `engine.block.getHeight()` | Layout | Get height of a block |
+| `engine.block.export()` | Export | Export a block to an image |
+| `engine.block.destroy()` | Lifecycle | Destroy a block |
+| `engine.dispose()` | Lifecycle | Clean up engine resources |
 
-| ❌ Issue                          | ✅ Solutions                                                                                                                                                           |
-| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Layout not applying               | ・ Verify asset source registration and callback connection<br />・ Check browser console for scene files or CORS errors<br />・ Check the validity of scene file URLs |
-| Content lost during layout change | ・ Debug visual sorting with console logs<br />・ Verify block type filtering is correct<br />・ Test with different content settings                                  |
-| Incorrect visual order            | ・ Adjust coordinate rounding tolerance in sorting<br />・ Flatten complex hierarchies before sorting<br />・ Test with well-defined layout structures                 |
-| Performance degradation           | ・ Optimize scene file sizes<br />・ Batch engine operations<br />・ Profile and optimize content transfer                                                             |
-| Undo not working                  | ・ Ensure `addUndoStep()` called after all changes complete<br />・ Verify undo configuration in engine setup                                                          |
+## Related Guides
 
-## Next Steps
+- [Apply Templates](./use-templates/apply-template.md) — Loading complete templates instead of transferring content
+- [Headless Mode](./concepts/headless-mode.md) — Server-side processing fundamentals
+- [Export Overview](./export-save-publish/export/overview.md) — Export options and formats
 
-Now that know how to create collages with layouts, explore these related guides to expand your CE.SDK knowledge:
 
-- [Apply Templates](./create-templates/overview.md) - Work with templates instead of layouts
-- [Create Custom Asset Sources](./import-media/asset-panel/basics.md) - Import custom assets
-- [Customize UI Panels](./user-interface/customization/panel.md) - Advanced UI customization
-- [Work with Images](./insert-media/images.md) - Manage image blocks and fills
-- [Scene Management](./open-the-editor/load-scene.md) - Load and save scenes
 
 ---
 
 ## 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