@imgly/codesign-mcp 0.1.5 → 0.1.6

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

@@ -1,396 +1,594 @@
-> 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) > [Design a Layout](./create-composition/layout.md)
 
 ---
 
-Create structured compositions using stack layouts that automatically arrange pages vertically or horizontally with consistent spacing.
-
-![Design a Layout](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
+Create automatic stack layouts in CE.SDK that arrange pages vertically or horizontally with consistent spacing. Build structured compositions like collages, catalogs, or carousels without manually positioning each element.
 
 > **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-create-composition-layout-browser)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-create-composition-layout-browser)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-create-composition-layout-browser/)
-
-Stack layouts arrange pages automatically with consistent spacing. Vertical stacks arrange pages top-to-bottom, while horizontal stacks arrange them left-to-right. This eliminates manual positioning for compositions like photo collages, product catalogs, or social media carousels.
-
-```typescript file=@cesdk_web_examples/guides-create-composition-layout-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';
-
-class Example implements EditorPlugin {
-  name = packageJson.name;
-  version = packageJson.version;
-
-  async initialize({ cesdk }: EditorPluginContext): Promise<void> {
-    if (!cesdk) 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;
-
-    // Create a scene with vertical stack layout
-    // Pages arrange top-to-bottom automatically
-    engine.scene.create('VerticalStack');
-
-    // Get the stack container created with the scene
-    const [stack] = engine.block.findByType('stack');
-
-    // Create two pages that will stack vertically
-    const page1 = engine.block.create('page');
-    engine.block.setWidth(page1, 400);
-    engine.block.setHeight(page1, 300);
-    engine.block.appendChild(stack, page1);
-
-    const page2 = engine.block.create('page');
-    engine.block.setWidth(page2, 400);
-    engine.block.setHeight(page2, 300);
-    engine.block.appendChild(stack, page2);
-
-    // Configure spacing between stacked pages
-    engine.block.setFloat(stack, 'stack/spacing', 20);
-    engine.block.setBool(stack, 'stack/spacingInScreenspace', true);
-
-    // Add image content to page 1
-    const imageUri = 'https://img.ly/static/ubq_samples/sample_1.jpg';
-    const block1 = await engine.block.addImage(imageUri, {
-      size: { width: 350, height: 250 }
-    });
-    engine.block.setPositionX(block1, 25);
-    engine.block.setPositionY(block1, 25);
-    engine.block.appendChild(page1, block1);
-
-    // Add a colored rectangle to page 2
-    const block2 = engine.block.create('graphic');
-    const shape2 = engine.block.createShape('rect');
-    engine.block.setShape(block2, shape2);
-    engine.block.setWidth(block2, 350);
-    engine.block.setHeight(block2, 250);
-    engine.block.setPositionX(block2, 25);
-    engine.block.setPositionY(block2, 25);
-    const fill2 = engine.block.createFill('color');
-    engine.block.setColor(fill2, 'fill/color/value', {
-      r: 0.3,
-      g: 0.6,
-      b: 0.9,
-      a: 1.0
-    });
-    engine.block.setFill(block2, fill2);
-    engine.block.appendChild(page2, block2);
-
-    // Switch to horizontal stack layout
-    // Pages now arrange left-to-right
-    engine.scene.setLayout('HorizontalStack');
-
-    // Verify the layout type
-    const currentLayout = engine.scene.getLayout();
-    console.log('Current layout:', currentLayout);
-
-    // Add a new page to the existing stack
-    // The page automatically appears at the end
-    const page3 = engine.block.create('page');
-    engine.block.setWidth(page3, 400);
-    engine.block.setHeight(page3, 300);
-    engine.block.appendChild(stack, page3);
-
-    // Add content to the new page
-    const block3 = engine.block.create('graphic');
-    const shape3 = engine.block.createShape('rect');
-    engine.block.setShape(block3, shape3);
-    engine.block.setWidth(block3, 350);
-    engine.block.setHeight(block3, 250);
-    engine.block.setPositionX(block3, 25);
-    engine.block.setPositionY(block3, 25);
-    const fill3 = engine.block.createFill('color');
-    engine.block.setColor(fill3, 'fill/color/value', {
-      r: 0.9,
-      g: 0.5,
-      b: 0.3,
-      a: 1.0
-    });
-    engine.block.setFill(block3, fill3);
-    engine.block.appendChild(page3, block3);
+>
+> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-create-composition-layout-server-js)
+>
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-create-composition-layout-server-js)
+
+CE.SDK provides stack layouts that automatically arrange pages with consistent spacing. Vertical stacks arrange pages top-to-bottom, horizontal stacks arrange left-to-right. This eliminates manual positioning for compositions like photo collages, product catalogs, social media carousels, and magazine layouts.
+
+```typescript file=@cesdk_web_examples/guides-create-composition-layout-server-js/server-js.ts reference-only
+import CreativeEngine from '@cesdk/node';
+import { config } from 'dotenv';
+import { writeFileSync, mkdirSync, existsSync } from 'fs';
+
+// Load environment variables
+config();
+
+/**
+ * CE.SDK Server Guide: Design a Layout
+ *
+ * Demonstrates:
+ * - Creating vertical stack layouts (top-to-bottom arrangement)
+ * - Creating horizontal stack layouts (left-to-right arrangement)
+ * - Adding blocks to stacks for automatic positioning
+ * - Configuring spacing between stacked blocks
+ * - Reordering blocks within stacks
+ * - Switching between stack and free layouts
+ * - Building a practical photo collage example
+ */
+
+// Initialize CE.SDK engine in headless mode
+const engine = await CreativeEngine.init({
+  baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
+  // license: process.env.CESDK_LICENSE, // Optional (trial mode available)
+});
 
-    // Reorder pages using insertChild
-    // Move page3 to the first position
-    engine.block.insertChild(stack, page3, 0);
+try {
+  // ===== VERTICAL STACK LAYOUT =====
+  console.log('--- Vertical Stack Layout ---');
+
+  // Create a scene with vertical stack layout
+  // Pages and blocks will arrange top-to-bottom automatically
+  const verticalScene = engine.scene.create('VerticalStack');
+  console.log('Created VerticalStack scene:', verticalScene);
+
+  // Get the stack container to add pages
+  const [stack] = engine.block.findByType('stack');
+
+  // Create first page
+  const page1 = engine.block.create('page');
+  engine.block.setWidth(page1, 400);
+  engine.block.setHeight(page1, 300);
+  engine.block.appendChild(stack, page1);
+
+  // Create second page - appears below page1
+  const page2 = engine.block.create('page');
+  engine.block.setWidth(page2, 400);
+  engine.block.setHeight(page2, 300);
+  engine.block.appendChild(stack, page2);
+
+  // Configure spacing between stacked pages (in screen space pixels)
+  engine.block.setFloat(stack, 'stack/spacing', 20);
+  engine.block.setBool(stack, 'stack/spacingInScreenspace', true);
+
+  const spacing = engine.block.getFloat(stack, 'stack/spacing');
+  console.log(`Stack spacing: ${spacing}px`);
+
+  // ===== HORIZONTAL STACK LAYOUT =====
+  console.log('\n--- Horizontal Stack Layout ---');
+
+  // Switch to horizontal stack layout
+  // Pages will now arrange left-to-right
+  engine.scene.setLayout('HorizontalStack');
+  console.log('Changed to HorizontalStack layout');
+
+  // Verify the layout change
+  const currentLayout = engine.scene.getLayout();
+  console.log('Current layout:', currentLayout);
+
+  // Pages are automatically rearranged horizontally
+  // Useful for carousels, timelines, or horizontal galleries
+
+  // ===== ADD BLOCKS TO PAGES =====
+  console.log('\n--- Adding Blocks to Pages ---');
+
+  // Add graphic blocks to each page
+  // Blocks must have a shape and fill to be visible
+
+  // Sample image URL for demonstrations
+  const imageUri = 'https://img.ly/static/ubq_samples/sample_1.jpg';
+
+  // Add an image block to page 1
+  const block1 = await engine.block.addImage(imageUri, {
+    size: { width: 350, height: 250 }
+  });
+  engine.block.setPositionX(block1, 25);
+  engine.block.setPositionY(block1, 25);
+  engine.block.appendChild(page1, block1);
+  console.log('Added image block to page 1');
+
+  // Add a colored rectangle to page 2
+  const block2 = engine.block.create('graphic');
+  const shape2 = engine.block.createShape('rect');
+  engine.block.setShape(block2, shape2);
+  engine.block.setWidth(block2, 350);
+  engine.block.setHeight(block2, 250);
+  engine.block.setPositionX(block2, 25);
+  engine.block.setPositionY(block2, 25);
+  const fill2 = engine.block.createFill('color');
+  engine.block.setColor(fill2, 'fill/color/value', {
+    r: 0.3,
+    g: 0.6,
+    b: 0.9,
+    a: 1.0
+  });
+  engine.block.setFill(block2, fill2);
+  engine.block.appendChild(page2, block2);
+  console.log('Added colored block to page 2');
+
+  // ===== ADD NEW PAGE TO EXISTING STACK =====
+  console.log('\n--- Adding Page to Existing Stack ---');
+
+  // Add a new page to the existing stack layout
+  // The page automatically appears at the end of the stack
+  const page3 = engine.block.create('page');
+  engine.block.setWidth(page3, 400);
+  engine.block.setHeight(page3, 300);
+  engine.block.appendChild(stack, page3);
+  console.log('Added page 3 to stack');
+
+  // Add content to page 3
+  const block3 = engine.block.create('graphic');
+  const shape3 = engine.block.createShape('rect');
+  engine.block.setShape(block3, shape3);
+  engine.block.setWidth(block3, 350);
+  engine.block.setHeight(block3, 250);
+  engine.block.setPositionX(block3, 25);
+  engine.block.setPositionY(block3, 25);
+  const fill3 = engine.block.createFill('color');
+  engine.block.setColor(fill3, 'fill/color/value', {
+    r: 0.9,
+    g: 0.5,
+    b: 0.3,
+    a: 1.0
+  });
+  engine.block.setFill(block3, fill3);
+  engine.block.appendChild(page3, block3);
+
+  // Count pages in stack
+  const pages = engine.block.getChildren(stack);
+  console.log(`Stack now has ${pages.length} pages`);
+
+  // ===== REORDER PAGES IN STACK =====
+  console.log('\n--- Reordering Pages ---');
+
+  // Reorder pages using insertChild
+  // Move page3 to the first position (index 0)
+  engine.block.insertChild(stack, page3, 0);
+  console.log('Moved page 3 to first position');
+
+  // Verify the new order by listing children
+  const reorderedPages = engine.block.getChildren(stack);
+  console.log('Page order after reordering:', reorderedPages);
+
+  // ===== CHANGE STACK SPACING =====
+  console.log('\n--- Changing Stack Spacing ---');
+
+  // Update spacing between stacked pages
+  engine.block.setFloat(stack, 'stack/spacing', 40);
+  const newSpacing = engine.block.getFloat(stack, 'stack/spacing');
+  console.log(`Updated stack spacing to: ${newSpacing}px`);
+
+  // Spacing updates immediately - pages reposition automatically
+
+  // ===== SWITCH TO FREE LAYOUT =====
+  console.log('\n--- Switching to Free Layout ---');
+
+  // Check current layout type
+  const layoutBefore = engine.scene.getLayout();
+  console.log('Current layout:', layoutBefore);
+
+  // Convert to free layout for manual positioning
+  engine.scene.setLayout('Free');
+  console.log('Switched to Free layout');
+
+  // In free layout, pages keep their positions but stop auto-arranging
+  // Now you can position pages manually
+  const [firstPage] = engine.block.findByType('page');
+  engine.block.setPositionX(firstPage, 50);
+  engine.block.setPositionY(firstPage, 50);
+  console.log('Manually positioned first page');
+
+  // Verify layout change
+  const layoutAfter = engine.scene.getLayout();
+  console.log('Layout after switch:', layoutAfter);
+
+  // ===== PHOTO COLLAGE EXAMPLE =====
+  console.log('\n--- Photo Collage Example ---');
+
+  // Create a new vertical stack scene for a photo collage
+  engine.scene.create('VerticalStack', {
+    page: { size: { width: 600, height: 200 } }
+  });
+
+  // Get the new stack
+  const [collageStack] = engine.block.findByType('stack');
+
+  // Set tight spacing for collage effect
+  engine.block.setFloat(collageStack, 'stack/spacing', 10);
+  engine.block.setBool(collageStack, 'stack/spacingInScreenspace', true);
+
+  // Get the first page created with the scene
+  const [collagePage1] = engine.block.findByType('page');
+
+  // Create additional pages for the collage
+  const collagePage2 = engine.block.create('page');
+  engine.block.setWidth(collagePage2, 600);
+  engine.block.setHeight(collagePage2, 200);
+  engine.block.appendChild(collageStack, collagePage2);
+
+  const collagePage3 = engine.block.create('page');
+  engine.block.setWidth(collagePage3, 600);
+  engine.block.setHeight(collagePage3, 200);
+  engine.block.appendChild(collageStack, collagePage3);
+
+  // Add images to each collage page
+  const imageUrls = [
+    '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'
+  ];
+
+  const collagePages = [collagePage1, collagePage2, collagePage3];
+
+  for (let i = 0; i < collagePages.length; i++) {
+    const photoBlock = await engine.block.addImage(imageUrls[i], {
+      size: { width: 580, height: 180 }
+    });
+    engine.block.setPositionX(photoBlock, 10);
+    engine.block.setPositionY(photoBlock, 10);
+    engine.block.appendChild(collagePages[i], photoBlock);
+  }
 
-    // Verify the new order
-    const pageOrder = engine.block.getChildren(stack);
-    console.log('Page order after reordering:', pageOrder);
+  console.log('Created photo collage with 3 images');
 
-    // Update spacing between stacked pages
-    engine.block.setFloat(stack, 'stack/spacing', 40);
+  // Export the collage result to PNG
+  const outputDir = './output';
+  if (!existsSync(outputDir)) {
+    mkdirSync(outputDir, { recursive: true });
+  }
 
-    // Verify the spacing value
-    const updatedSpacing = engine.block.getFloat(stack, 'stack/spacing');
-    console.log('Updated spacing:', updatedSpacing);
+  const blob = await engine.block.export(collagePage1, {
+    mimeType: 'image/png'
+  });
+  const buffer = Buffer.from(await blob.arrayBuffer());
+  writeFileSync(`${outputDir}/layout-collage.png`, buffer);
 
-    // Zoom to show all pages in the stack
-    await engine.scene.zoomToBlock(stack, { padding: 50 });
-  }
+  console.log('\nExported collage to output/layout-collage.png');
+} finally {
+  // Always dispose the engine to free resources
+  engine.dispose();
 }
-
-export default Example;
 ```
 
-This guide covers how to:
+This guide covers how to create vertical and horizontal stack layouts, add pages to stacks, configure spacing, reorder pages, and switch between automatic and manual positioning modes.
+
+## Setting Up the Engine
+
+We initialize the headless CE.SDK engine for server-side layout operations.
 
-- Create vertical and horizontal stack layouts
-- Add pages and blocks to stacks
-- Configure spacing between stacked pages
-- Reorder pages within a stack
-- Switch between stack and free layouts
+```typescript highlight=highlight-setup
+// Initialize CE.SDK engine in headless mode
+const engine = await CreativeEngine.init({
+  baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
+  // license: process.env.CESDK_LICENSE, // Optional (trial mode available)
+});
+```
 
 ## Create a Vertical Stack Layout
 
-Vertical stacks arrange pages from top to bottom. Create a scene with `VerticalStack` layout, then add pages to the stack container.
+Vertical stack layouts arrange pages from top to bottom. When you add pages to the stack, they automatically position below each other with the configured spacing.
 
 ```typescript highlight=highlight-vertical-stack
-// Create a scene with vertical stack layout
-// Pages arrange top-to-bottom automatically
-engine.scene.create('VerticalStack');
-
-// Get the stack container created with the scene
-const [stack] = engine.block.findByType('stack');
-
-// Create two pages that will stack vertically
-const page1 = engine.block.create('page');
-engine.block.setWidth(page1, 400);
-engine.block.setHeight(page1, 300);
-engine.block.appendChild(stack, page1);
-
-const page2 = engine.block.create('page');
-engine.block.setWidth(page2, 400);
-engine.block.setHeight(page2, 300);
-engine.block.appendChild(stack, page2);
-
-// Configure spacing between stacked pages
-engine.block.setFloat(stack, 'stack/spacing', 20);
-engine.block.setBool(stack, 'stack/spacingInScreenspace', true);
+  // Create a scene with vertical stack layout
+  // Pages and blocks will arrange top-to-bottom automatically
+  const verticalScene = engine.scene.create('VerticalStack');
+  console.log('Created VerticalStack scene:', verticalScene);
+
+  // Get the stack container to add pages
+  const [stack] = engine.block.findByType('stack');
+
+  // Create first page
+  const page1 = engine.block.create('page');
+  engine.block.setWidth(page1, 400);
+  engine.block.setHeight(page1, 300);
+  engine.block.appendChild(stack, page1);
+
+  // Create second page - appears below page1
+  const page2 = engine.block.create('page');
+  engine.block.setWidth(page2, 400);
+  engine.block.setHeight(page2, 300);
+  engine.block.appendChild(stack, page2);
+
+  // Configure spacing between stacked pages (in screen space pixels)
+  engine.block.setFloat(stack, 'stack/spacing', 20);
+  engine.block.setBool(stack, 'stack/spacingInScreenspace', true);
+
+  const spacing = engine.block.getFloat(stack, 'stack/spacing');
+  console.log(`Stack spacing: ${spacing}px`);
 ```
 
-When you create a scene with `VerticalStack` layout, CE.SDK automatically creates a stack container. Pages added to this container are positioned vertically with the configured spacing. The `spacingInScreenspace` property ensures spacing remains consistent regardless of zoom level.
+Pages added with `appendChild` appear at the bottom of the stack. The `stack/spacing` property controls the gap between pages, and `stack/spacingInScreenspace` determines whether spacing is in screen pixels or design units.
 
-## Add Blocks to Pages
+## Create a Horizontal Stack Layout
 
-Each page can contain multiple blocks. Create blocks with shapes and fills, position them within the page, then append them to the page.
+Horizontal stack layouts arrange pages from left to right. Switch between layout types using `engine.scene.setLayout()`.
 
-```typescript highlight=highlight-add-blocks
-// Add image content to page 1
-const imageUri = 'https://img.ly/static/ubq_samples/sample_1.jpg';
-const block1 = await engine.block.addImage(imageUri, {
-  size: { width: 350, height: 250 }
-});
-engine.block.setPositionX(block1, 25);
-engine.block.setPositionY(block1, 25);
-engine.block.appendChild(page1, block1);
-
-// Add a colored rectangle to page 2
-const block2 = engine.block.create('graphic');
-const shape2 = engine.block.createShape('rect');
-engine.block.setShape(block2, shape2);
-engine.block.setWidth(block2, 350);
-engine.block.setHeight(block2, 250);
-engine.block.setPositionX(block2, 25);
-engine.block.setPositionY(block2, 25);
-const fill2 = engine.block.createFill('color');
-engine.block.setColor(fill2, 'fill/color/value', {
-  r: 0.3,
-  g: 0.6,
-  b: 0.9,
-  a: 1.0
-});
-engine.block.setFill(block2, fill2);
-engine.block.appendChild(page2, block2);
-```
+```typescript highlight=highlight-horizontal-stack
+  // Switch to horizontal stack layout
+  // Pages will now arrange left-to-right
+  engine.scene.setLayout('HorizontalStack');
+  console.log('Changed to HorizontalStack layout');
 
-Blocks require a shape and fill to be visible. Use `addImage()` for image content, or create graphic blocks with custom shapes and color fills. Position blocks within their parent page using `setPositionX()` and `setPositionY()`.
+  // Verify the layout change
+  const currentLayout = engine.scene.getLayout();
+  console.log('Current layout:', currentLayout);
 
-## Switch to Horizontal Layout
+  // Pages are automatically rearranged horizontally
+  // Useful for carousels, timelines, or horizontal galleries
+```
 
-Change the layout direction at any time using `setLayout()`. Horizontal stacks arrange pages left-to-right instead of top-to-bottom.
+Horizontal layouts are useful for carousels, timelines, or horizontal galleries. The same spacing configuration applies—pages automatically reposition when you change the layout type.
 
-```typescript highlight=highlight-horizontal-stack
-// Switch to horizontal stack layout
-// Pages now arrange left-to-right
-engine.scene.setLayout('HorizontalStack');
+## Add Blocks to Pages
 
-// Verify the layout type
-const currentLayout = engine.scene.getLayout();
-console.log('Current layout:', currentLayout);
+Once you have pages in your stack, add graphic blocks to display content. Each block needs a shape and fill to be visible.
+
+```typescript highlight=highlight-add-blocks
+  // Add graphic blocks to each page
+  // Blocks must have a shape and fill to be visible
+
+  // Sample image URL for demonstrations
+  const imageUri = 'https://img.ly/static/ubq_samples/sample_1.jpg';
+
+  // Add an image block to page 1
+  const block1 = await engine.block.addImage(imageUri, {
+    size: { width: 350, height: 250 }
+  });
+  engine.block.setPositionX(block1, 25);
+  engine.block.setPositionY(block1, 25);
+  engine.block.appendChild(page1, block1);
+  console.log('Added image block to page 1');
+
+  // Add a colored rectangle to page 2
+  const block2 = engine.block.create('graphic');
+  const shape2 = engine.block.createShape('rect');
+  engine.block.setShape(block2, shape2);
+  engine.block.setWidth(block2, 350);
+  engine.block.setHeight(block2, 250);
+  engine.block.setPositionX(block2, 25);
+  engine.block.setPositionY(block2, 25);
+  const fill2 = engine.block.createFill('color');
+  engine.block.setColor(fill2, 'fill/color/value', {
+    r: 0.3,
+    g: 0.6,
+    b: 0.9,
+    a: 1.0
+  });
+  engine.block.setFill(block2, fill2);
+  engine.block.appendChild(page2, block2);
+  console.log('Added colored block to page 2');
 ```
 
-Horizontal layouts work well for carousels, timelines, and horizontal galleries. Existing pages automatically reposition when you change the layout type.
+Position blocks within their parent page using `setPositionX()` and `setPositionY()`. The block's position is relative to the page's top-left corner.
 
-## Add Pages to Existing Stacks
+## Add Pages to an Existing Stack
 
-Add new pages to an existing stack at any time. Pages automatically appear at the end of the stack with proper spacing.
+After creating a composition, you can add more pages to the stack. New pages automatically appear at the end.
 
 ```typescript highlight=highlight-add-page
-// Add a new page to the existing stack
-// The page automatically appears at the end
-const page3 = engine.block.create('page');
-engine.block.setWidth(page3, 400);
-engine.block.setHeight(page3, 300);
-engine.block.appendChild(stack, page3);
-
-// Add content to the new page
-const block3 = engine.block.create('graphic');
-const shape3 = engine.block.createShape('rect');
-engine.block.setShape(block3, shape3);
-engine.block.setWidth(block3, 350);
-engine.block.setHeight(block3, 250);
-engine.block.setPositionX(block3, 25);
-engine.block.setPositionY(block3, 25);
-const fill3 = engine.block.createFill('color');
-engine.block.setColor(fill3, 'fill/color/value', {
-  r: 0.9,
-  g: 0.5,
-  b: 0.3,
-  a: 1.0
-});
-engine.block.setFill(block3, fill3);
-engine.block.appendChild(page3, block3);
+  // Add a new page to the existing stack layout
+  // The page automatically appears at the end of the stack
+  const page3 = engine.block.create('page');
+  engine.block.setWidth(page3, 400);
+  engine.block.setHeight(page3, 300);
+  engine.block.appendChild(stack, page3);
+  console.log('Added page 3 to stack');
+
+  // Add content to page 3
+  const block3 = engine.block.create('graphic');
+  const shape3 = engine.block.createShape('rect');
+  engine.block.setShape(block3, shape3);
+  engine.block.setWidth(block3, 350);
+  engine.block.setHeight(block3, 250);
+  engine.block.setPositionX(block3, 25);
+  engine.block.setPositionY(block3, 25);
+  const fill3 = engine.block.createFill('color');
+  engine.block.setColor(fill3, 'fill/color/value', {
+    r: 0.9,
+    g: 0.5,
+    b: 0.3,
+    a: 1.0
+  });
+  engine.block.setFill(block3, fill3);
+  engine.block.appendChild(page3, block3);
+
+  // Count pages in stack
+  const pages = engine.block.getChildren(stack);
+  console.log(`Stack now has ${pages.length} pages`);
 ```
 
-The stack container manages positioning automatically. You can add content to the new page before or after appending it to the stack.
+Use `getChildren()` to see all pages in the stack. The insertion order determines the visual order in the layout.
 
-## Reorder Pages
+## Reorder Pages in the Stack
 
-Change page order using `insertChild()` to place a page at a specific index within the stack.
+Change the position of pages using `insertChild()`. This lets you move pages to any position in the stack.
 
 ```typescript highlight=highlight-reorder
-// Reorder pages using insertChild
-// Move page3 to the first position
-engine.block.insertChild(stack, page3, 0);
-
-// Verify the new order
-const pageOrder = engine.block.getChildren(stack);
-console.log('Page order after reordering:', pageOrder);
+  // Reorder pages using insertChild
+  // Move page3 to the first position (index 0)
+  engine.block.insertChild(stack, page3, 0);
+  console.log('Moved page 3 to first position');
+
+  // Verify the new order by listing children
+  const reorderedPages = engine.block.getChildren(stack);
+  console.log('Page order after reordering:', reorderedPages);
 ```
 
-Removing a page from its current position and reinserting it at index 0 moves it to the first position. All other pages shift to accommodate the change.
+The second parameter specifies the target index. Index 0 places the page first, and higher indices move it further down (or right in horizontal layouts).
 
 ## Change Stack Spacing
 
-Adjust spacing between pages using the `stack/spacing` property on the stack block.
+Adjust the spacing between pages at any time. Changes apply immediately and pages reposition automatically.
 
 ```typescript highlight=highlight-spacing
-// Update spacing between stacked pages
-engine.block.setFloat(stack, 'stack/spacing', 40);
+  // Update spacing between stacked pages
+  engine.block.setFloat(stack, 'stack/spacing', 40);
+  const newSpacing = engine.block.getFloat(stack, 'stack/spacing');
+  console.log(`Updated stack spacing to: ${newSpacing}px`);
 
-// Verify the spacing value
-const updatedSpacing = engine.block.getFloat(stack, 'stack/spacing');
-console.log('Updated spacing:', updatedSpacing);
+  // Spacing updates immediately - pages reposition automatically
 ```
 
-Spacing updates immediately and pages reposition automatically. Use `getFloat()` to verify the current spacing value.
+Use `getFloat()` to read the current spacing value. Larger spacing creates more separation between pages; zero spacing creates a seamless grid.
 
 ## Switch to Free Layout
 
-For manual positioning, switch to `Free` layout. Pages keep their positions but stop auto-arranging.
+Stack layouts automatically position pages. For manual control, switch to Free layout.
+
+```typescript highlight=highlight-free-layout
+  // Check current layout type
+  const layoutBefore = engine.scene.getLayout();
+  console.log('Current layout:', layoutBefore);
 
-```typescript
-// Check current layout type
-const layout = engine.scene.getLayout();
+  // Convert to free layout for manual positioning
+  engine.scene.setLayout('Free');
+  console.log('Switched to Free layout');
 
-// Convert to free layout for manual positioning
-engine.scene.setLayout('Free');
+  // In free layout, pages keep their positions but stop auto-arranging
+  // Now you can position pages manually
+  const [firstPage] = engine.block.findByType('page');
+  engine.block.setPositionX(firstPage, 50);
+  engine.block.setPositionY(firstPage, 50);
+  console.log('Manually positioned first page');
 
-// Now position pages manually
-const [page] = engine.block.findByType('page');
-engine.block.setPositionX(page, 100);
-engine.block.setPositionY(page, 200);
+  // Verify layout change
+  const layoutAfter = engine.scene.getLayout();
+  console.log('Layout after switch:', layoutAfter);
 ```
 
-Free layout gives full control over page positions. Use this when you need precise positioning that stack layouts cannot provide.
+In Free layout, pages keep their current positions but stop auto-arranging. You can then use `setPositionX()` and `setPositionY()` to position pages manually.
+
+## Build a Photo Collage
+
+This practical example creates a vertical photo collage with three images and tight spacing.
+
+```typescript highlight=highlight-collage
+  // Create a new vertical stack scene for a photo collage
+  engine.scene.create('VerticalStack', {
+    page: { size: { width: 600, height: 200 } }
+  });
+
+  // Get the new stack
+  const [collageStack] = engine.block.findByType('stack');
+
+  // Set tight spacing for collage effect
+  engine.block.setFloat(collageStack, 'stack/spacing', 10);
+  engine.block.setBool(collageStack, 'stack/spacingInScreenspace', true);
+
+  // Get the first page created with the scene
+  const [collagePage1] = engine.block.findByType('page');
+
+  // Create additional pages for the collage
+  const collagePage2 = engine.block.create('page');
+  engine.block.setWidth(collagePage2, 600);
+  engine.block.setHeight(collagePage2, 200);
+  engine.block.appendChild(collageStack, collagePage2);
+
+  const collagePage3 = engine.block.create('page');
+  engine.block.setWidth(collagePage3, 600);
+  engine.block.setHeight(collagePage3, 200);
+  engine.block.appendChild(collageStack, collagePage3);
+
+  // Add images to each collage page
+  const imageUrls = [
+    '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'
+  ];
+
+  const collagePages = [collagePage1, collagePage2, collagePage3];
+
+  for (let i = 0; i < collagePages.length; i++) {
+    const photoBlock = await engine.block.addImage(imageUrls[i], {
+      size: { width: 580, height: 180 }
+    });
+    engine.block.setPositionX(photoBlock, 10);
+    engine.block.setPositionY(photoBlock, 10);
+    engine.block.appendChild(collagePages[i], photoBlock);
+  }
+
+  console.log('Created photo collage with 3 images');
+```
+
+The collage uses a vertical stack with 10px spacing. Each page contains an image that fills most of the page area, creating a cohesive photo strip effect.
+
+## Exporting the Result
+
+After building the layout, export pages as images to verify the composition.
+
+```typescript highlight=highlight-export
+  // Export the collage result to PNG
+  const outputDir = './output';
+  if (!existsSync(outputDir)) {
+    mkdirSync(outputDir, { recursive: true });
+  }
+
+  const blob = await engine.block.export(collagePage1, {
+    mimeType: 'image/png'
+  });
+  const buffer = Buffer.from(await blob.arrayBuffer());
+  writeFileSync(`${outputDir}/layout-collage.png`, buffer);
+
+  console.log('\nExported collage to output/layout-collage.png');
+```
 
 ## Troubleshooting
 
-**Pages not arranging automatically** — Verify the scene layout type is `VerticalStack` or `HorizontalStack` using `getLayout()`.
+**Pages not arranging automatically**: Verify the scene layout type is `VerticalStack` or `HorizontalStack` using `engine.scene.getLayout()`.
 
-**Spacing not applying** — Check that you're setting spacing on the stack block, not the scene. Use `findByType('stack')` to get the stack container.
+**Spacing not applying**: Check the spacing value with `engine.block.getFloat(stack, 'stack/spacing')`. Ensure you're setting spacing on the stack block, not the scene.
 
-**Pages overlapping** — Ensure pages are direct children of the stack container. Nested pages won't auto-arrange properly.
+**Pages overlapping**: Ensure pages are direct children of the stack block. Use `engine.block.findByType('stack')` to get the correct parent.
 
-**Can't position manually** — Stack layouts override manual positions. Switch to `Free` layout for manual control.
+**Can't position pages manually**: Stack layouts override manual positions. Switch to `Free` layout with `engine.scene.setLayout('Free')`.
 
-**Wrong stacking order** — Child order determines position. Use `insertChild()` to move pages to specific positions.
+**Wrong page order**: Child order determines visual position. Use `insertChild(stack, page, index)` to move pages to specific positions.
 
 ## API Reference
 
-| Method                                              | Description                                                                             |
-| --------------------------------------------------- | --------------------------------------------------------------------------------------- |
-| `engine.scene.create(layout)`                       | Create a scene with specified layout (`'Free'`, `'VerticalStack'`, `'HorizontalStack'`) |
-| `engine.scene.setLayout(layout)`                    | Change the layout type of the current scene                                             |
-| `engine.scene.getLayout()`                          | Get the current layout type                                                             |
-| `engine.block.findByType('stack')`                  | Find the stack container block                                                          |
-| `engine.block.setFloat(id, 'stack/spacing', value)` | Set spacing between stacked pages                                                       |
-| `engine.block.getFloat(id, 'stack/spacing')`        | Get current spacing value                                                               |
-| `engine.block.appendChild(parent, child)`           | Add a page to the stack                                                                 |
-| `engine.block.insertChild(parent, child, index)`    | Insert a page at a specific position                                                    |
-| `engine.block.getChildren(id)`                      | Get child blocks in order                                                               |
-
-## Next Steps
-
-- [Auto-resize](./automation/auto-resize.md) — Make blocks fit parent containers
-- [Manual Positioning](./edit-image/transform/move.md) — Position blocks in free layouts
-- [Layer Hierarchies](./create-composition/layer-management.md) — Organize blocks in hierarchical structures
-- [Create a Collage](./create-composition/collage.md) — Build photo collages with templates
+| Method | Description |
+| --- | --- |
+| `engine.scene.create(layout, options)` | Create a scene with specified layout type |
+| `engine.scene.getLayout()` | Get the current scene layout type |
+| `engine.scene.setLayout(layout)` | Change the scene layout type |
+| `engine.block.findByType('stack')` | Find the stack container block |
+| `engine.block.setFloat(id, 'stack/spacing', value)` | Set spacing between stacked pages |
+| `engine.block.getFloat(id, 'stack/spacing')` | Get current spacing value |
+| `engine.block.setBool(id, 'stack/spacingInScreenspace', value)` | Set whether spacing is in screen pixels |
+| `engine.block.appendChild(parent, child)` | Add page to stack (positions automatically) |
+| `engine.block.insertChild(parent, child, index)` | Insert page at specific position in stack |
+| `engine.block.getChildren(id)` | Get all child pages of a stack |
+
+
 
 ---
 
 ## 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