@imgly/codesign-mcp 0.1.5 → 0.1.6

package/assets/docs/guide/fills/video.md

@@ -1,641 +1,489 @@
-> 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) > [Fills](./fills.md) > [Video](./fills/video.md)
 
 ---
 
-Apply motion content to design elements by filling shapes, backgrounds, and
-text with videos using CE.SDK's video fill system.
+Video fills let you fill shapes and graphics with video content. Unlike video blocks which represent standalone video elements, video fills apply video as a visual property to existing blocks — similar to how you might fill a shape with an image or color.
 
-![CE.SDK video fills example showing a 3x3 grid with video content applied to different blocks including rectangles, ellipse, and opacity variations](https://img.ly/docs/cesdk/./assets/browser.hero.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/tree/release-$UBQ_VERSION$/guides-fills-video-browser)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-fills-video-browser)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-fills-video-browser/)
-
-Understanding the distinction between **video fills** and **video blocks** is essential. Video fills are fill objects that can be applied to any block supporting fills—shapes, text, backgrounds—to paint them with video content. Video blocks, created with `addVideo()`, are dedicated time-based blocks with full editing capabilities like trimming and duration control. Video fills focus on applying video as a visual treatment, while video blocks provide complete video editing functionality.
-
-```typescript file=@cesdk_web_examples/guides-fills-video-browser/browser.ts reference-only
-import type {
-  CreativeEngine,
-  EditorPlugin,
-  EditorPluginContext
-} from '@cesdk/cesdk-js';
-import packageJson from './package.json';
-
-import {
-  BlurAssetSource,
-  CaptionPresetsAssetSource,
-  ColorPaletteAssetSource,
-  CropPresetsAssetSource,
-  DemoAssetSources,
-  EffectsAssetSource,
-  FiltersAssetSource,
-  PagePresetsAssetSource,
-  StickerAssetSource,
-  TextAssetSource,
-  TextComponentAssetSource,
-  TypefaceAssetSource,
-  UploadAssetSources,
-  VectorShapeAssetSource
-} from '@cesdk/cesdk-js/plugins';
-import { VideoEditorConfig } from './video-editor/plugin';
-import { calculateGridLayout } from './utils';
-
-/**
- * CE.SDK Plugin: Video Fills Guide
- *
- * Demonstrates video fills in CE.SDK:
- * - Creating video fills
- * - Setting video sources (single URI and source sets)
- * - Applying video fills to blocks
- * - Content fill modes (Cover, Contain)
- * - Loading video resources
- * - Getting video thumbnails
- * - Different use cases (backgrounds, shapes, text)
- */
-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 for this plugin');
-    }
-
-    await cesdk.addPlugin(new VideoEditorConfig());
-
-    // Add asset source plugins
-    await cesdk.addPlugin(new BlurAssetSource());
-    await cesdk.addPlugin(new CaptionPresetsAssetSource());
-    await cesdk.addPlugin(new ColorPaletteAssetSource());
-    await cesdk.addPlugin(new CropPresetsAssetSource());
-    await cesdk.addPlugin(
-      new UploadAssetSources({
-        include: [
-          'ly.img.image.upload',
-          'ly.img.video.upload',
-          'ly.img.audio.upload'
-        ]
-      })
-    );
-    await cesdk.addPlugin(
-      new DemoAssetSources({
-        include: [
-          'ly.img.templates.video.*',
-          'ly.img.image.*',
-          'ly.img.audio.*',
-          'ly.img.video.*'
-        ]
-      })
-    );
-    await cesdk.addPlugin(new EffectsAssetSource());
-    await cesdk.addPlugin(new FiltersAssetSource());
-    await cesdk.addPlugin(
-      new PagePresetsAssetSource({
-        include: [
-          'ly.img.page.presets.instagram.*',
-          'ly.img.page.presets.facebook.*',
-          'ly.img.page.presets.x.*',
-          'ly.img.page.presets.linkedin.*',
-          'ly.img.page.presets.pinterest.*',
-          'ly.img.page.presets.tiktok.*',
-          'ly.img.page.presets.youtube.*',
-          'ly.img.page.presets.video.*'
-        ]
-      })
-    );
-    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());
-
-    await cesdk.actions.run('scene.create', {
-      layout: 'DepthStack',
-      page: {
-        sourceId: 'ly.img.page.presets',
-        assetId: 'ly.img.page.presets.instagram.story',
-        color: { r: 0, g: 0, b: 0, a: 1 }
-      }
-    });
+>
+> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-fills-video-server-js)
+>
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-fills-video-server-js)
 
-    const engine = cesdk.engine as CreativeEngine;
-    const pages = engine.block.findByType('page');
-    const page = pages.length > 0 ? pages[0] : engine.scene.get();
+## Context: Video Fills vs Video Blocks
 
-    // Calculate responsive grid layout based on page dimensions
-    const pageWidth = engine.block.getWidth(page);
-    const pageHeight = engine.block.getHeight(page);
-    const layout = calculateGridLayout(pageWidth, pageHeight, 8);
-    const { blockWidth, blockHeight, getPosition } = layout;
+**Video fills** apply video as a fill property to graphic blocks. This is useful when you want to use video as a texture within shapes, mask video to specific areas, or create video-filled design elements. Video fills attach to graphic blocks via the fill API.
 
-    // Use a sample video URL from demo assets
-    const videoUri = 'https://img.ly/static/ubq_video_samples/bbb.mp4';
+**Video blocks** are standalone elements that represent video content directly on the canvas. They're created with `engine.block.create('video')` and represent complete video clips.
+
+## Reference Example
 
-    // Create a sample block to demonstrate fill support checking
-    const sampleBlock = engine.block.create('graphic');
-    engine.block.setShape(sampleBlock, engine.block.createShape('rect'));
+The following code demonstrates the complete video fills API. Below, each section is explained in detail.
 
-    // Check if the block supports fills
-    const supportsFills = engine.block.supportsFill(sampleBlock);
-    // eslint-disable-next-line no-console
-    console.log('Block supports fills:', supportsFills); // true for graphic blocks
+```typescript file=@cesdk_web_examples/guides-fills-video-server-js/server-js.ts reference-only
+import CreativeEngine from '@cesdk/node';
+import { config } from 'dotenv';
 
-    // Pattern #1: Demonstrate Individual Before Combined
-    // Create a basic video fill demonstration
+config();
+
+async function main() {
+  const engine = await CreativeEngine.init({
+    baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
+    // license: process.env.CESDK_LICENSE,
+  });
+
+  try {
+    // Create a scene with a page
+    const scene = engine.scene.create('DepthStack');
+    const page = engine.block.create('page');
+    engine.block.setWidth(page, 800);
+    engine.block.setHeight(page, 600);
+    engine.block.appendChild(scene, page);
+
+    // Check if block supports fills before accessing fill APIs
+    const testBlock = engine.block.create('graphic');
+    const canHaveFill = engine.block.supportsFill(testBlock);
+    console.log('Block supports fills:', canHaveFill);
+
+    engine.block.destroy(testBlock);
+
+    const videoUri = 'https://img.ly/static/ubq_video_samples/bbb.mp4';
+
+    // ===== Section 1: Create Video Fill =====
+    // Create a graphic block with a video fill
     const basicBlock = engine.block.create('graphic');
     engine.block.setShape(basicBlock, engine.block.createShape('rect'));
-    engine.block.setWidth(basicBlock, blockWidth);
-    engine.block.setHeight(basicBlock, blockHeight);
-    engine.block.appendChild(page, basicBlock);
+    engine.block.setWidth(basicBlock, 200);
+    engine.block.setHeight(basicBlock, 150);
 
     // Create a video fill
-    const basicVideoFill = engine.block.createFill('video');
+    const videoFill = engine.block.createFill('video');
     // or using full type name: engine.block.createFill('//ly.img.ubq/fill/video');
 
     // Set the video source URI
-    engine.block.setString(basicVideoFill, 'fill/video/fileURI', videoUri);
+    engine.block.setString(videoFill, 'fill/video/fileURI', videoUri);
 
     // Apply the fill to the block
-    engine.block.setFill(basicBlock, basicVideoFill);
+    engine.block.setFill(basicBlock, videoFill);
+    engine.block.appendChild(page, basicBlock);
 
     // Get and verify the current fill
     const fillId = engine.block.getFill(basicBlock);
     const fillType = engine.block.getType(fillId);
-    // eslint-disable-next-line no-console
     console.log('Fill type:', fillType); // '//ly.img.ubq/fill/video'
 
-    // Pattern #2: Content fill mode - Cover
-    // Cover mode fills entire block, may crop video to fit
+    // ===== Section 2: Content Fill Modes =====
+    // Cover mode: Fill entire block, may crop video
     const coverBlock = engine.block.create('graphic');
     engine.block.setShape(coverBlock, engine.block.createShape('rect'));
-    engine.block.setWidth(coverBlock, blockWidth);
-    engine.block.setHeight(coverBlock, blockHeight);
-    engine.block.appendChild(page, coverBlock);
+    engine.block.setWidth(coverBlock, 200);
+    engine.block.setHeight(coverBlock, 150);
 
     const coverVideoFill = engine.block.createFill('video');
     engine.block.setString(coverVideoFill, 'fill/video/fileURI', videoUri);
     engine.block.setFill(coverBlock, coverVideoFill);
+    engine.block.appendChild(page, coverBlock);
 
     // Set content fill mode to Cover
     engine.block.setEnum(coverBlock, 'contentFill/mode', 'Cover');
 
     // Get current fill mode
     const coverMode = engine.block.getEnum(coverBlock, 'contentFill/mode');
-    // eslint-disable-next-line no-console
     console.log('Cover block fill mode:', coverMode); // 'Cover'
 
-    // Content fill mode - Contain
-    // Contain mode fits entire video, may leave empty space
+    // Contain mode: Fit entire video, may leave empty space
     const containBlock = engine.block.create('graphic');
     engine.block.setShape(containBlock, engine.block.createShape('rect'));
-    engine.block.setWidth(containBlock, blockWidth);
-    engine.block.setHeight(containBlock, blockHeight);
-    engine.block.appendChild(page, containBlock);
+    engine.block.setWidth(containBlock, 200);
+    engine.block.setHeight(containBlock, 150);
 
     const containVideoFill = engine.block.createFill('video');
     engine.block.setString(containVideoFill, 'fill/video/fileURI', videoUri);
     engine.block.setFill(containBlock, containVideoFill);
+    engine.block.appendChild(page, containBlock);
 
     // Set content fill mode to Contain
     engine.block.setEnum(containBlock, 'contentFill/mode', 'Contain');
 
+    // Get current fill mode
+    const currentMode = engine.block.getEnum(containBlock, 'contentFill/mode');
+    console.log('Current fill mode:', currentMode);
+
+    // ===== Section 3: Force Load Video Resource =====
     // Force load video resource to access metadata
-    const resourceBlock = engine.block.create('graphic');
-    engine.block.setShape(resourceBlock, engine.block.createShape('rect'));
-    engine.block.setWidth(resourceBlock, blockWidth);
-    engine.block.setHeight(resourceBlock, blockHeight);
-    engine.block.appendChild(page, resourceBlock);
+    const metadataBlock = engine.block.create('graphic');
+    engine.block.setShape(metadataBlock, engine.block.createShape('rect'));
+    engine.block.setWidth(metadataBlock, 200);
+    engine.block.setHeight(metadataBlock, 150);
 
-    const resourceVideoFill = engine.block.createFill('video');
-    engine.block.setString(resourceVideoFill, 'fill/video/fileURI', videoUri);
-    engine.block.setFill(resourceBlock, resourceVideoFill);
+    const metadataVideoFill = engine.block.createFill('video');
+    engine.block.setString(metadataVideoFill, 'fill/video/fileURI', videoUri);
+    engine.block.setFill(metadataBlock, metadataVideoFill);
+    engine.block.appendChild(page, metadataBlock);
 
     // Force load the video resource before accessing metadata
-    await engine.block.forceLoadAVResource(resourceVideoFill);
+    await engine.block.forceLoadAVResource(metadataVideoFill);
 
     // Now we can access video metadata
     const totalDuration = engine.block.getDouble(
-      resourceVideoFill,
+      metadataVideoFill,
       'fill/video/totalDuration'
     );
-    // eslint-disable-next-line no-console
     console.log('Video total duration:', totalDuration, 'seconds');
 
-    // Use case: Video as shape fill - Ellipse
+    // ===== Section 4: Video as Shape Fill =====
+    // Fill a shape with video content
     const ellipseBlock = engine.block.create('graphic');
     const ellipseShape = engine.block.createShape('//ly.img.ubq/shape/ellipse');
     engine.block.setShape(ellipseBlock, ellipseShape);
-    engine.block.setWidth(ellipseBlock, blockWidth);
-    engine.block.setHeight(ellipseBlock, blockHeight);
-    engine.block.appendChild(page, ellipseBlock);
+    engine.block.setWidth(ellipseBlock, 200);
+    engine.block.setHeight(ellipseBlock, 150);
 
     const ellipseVideoFill = engine.block.createFill('video');
     engine.block.setString(ellipseVideoFill, 'fill/video/fileURI', videoUri);
     engine.block.setFill(ellipseBlock, ellipseVideoFill);
+    engine.block.appendChild(page, ellipseBlock);
 
-    // Advanced: Video fill with opacity
+    // ===== Section 5: Opacity =====
+    // Control opacity for transparency effects
     const opacityBlock = engine.block.create('graphic');
     engine.block.setShape(opacityBlock, engine.block.createShape('rect'));
-    engine.block.setWidth(opacityBlock, blockWidth);
-    engine.block.setHeight(opacityBlock, blockHeight);
-    engine.block.appendChild(page, opacityBlock);
+    engine.block.setWidth(opacityBlock, 200);
+    engine.block.setHeight(opacityBlock, 150);
 
     const opacityVideoFill = engine.block.createFill('video');
     engine.block.setString(opacityVideoFill, 'fill/video/fileURI', videoUri);
     engine.block.setFill(opacityBlock, opacityVideoFill);
+    engine.block.appendChild(page, opacityBlock);
 
     // Set block opacity to 70%
     engine.block.setFloat(opacityBlock, 'opacity', 0.7);
 
-    // Advanced: Share one video fill between multiple blocks
+    // ===== Section 6: Shared Video Fill =====
+    // Share one video fill between multiple blocks for memory efficiency
     const sharedFill = engine.block.createFill('video');
     engine.block.setString(sharedFill, 'fill/video/fileURI', videoUri);
 
     // First block using shared fill
     const sharedBlock1 = engine.block.create('graphic');
     engine.block.setShape(sharedBlock1, engine.block.createShape('rect'));
-    engine.block.setWidth(sharedBlock1, blockWidth);
-    engine.block.setHeight(sharedBlock1, blockHeight);
-    engine.block.appendChild(page, sharedBlock1);
+    engine.block.setWidth(sharedBlock1, 200);
+    engine.block.setHeight(sharedBlock1, 150);
     engine.block.setFill(sharedBlock1, sharedFill);
+    engine.block.appendChild(page, sharedBlock1);
 
     // Second block using the same shared fill
     const sharedBlock2 = engine.block.create('graphic');
     engine.block.setShape(sharedBlock2, engine.block.createShape('rect'));
-    engine.block.setWidth(sharedBlock2, blockWidth * 0.8); // Slightly smaller
-    engine.block.setHeight(sharedBlock2, blockHeight * 0.8);
-    engine.block.appendChild(page, sharedBlock2);
+    engine.block.setWidth(sharedBlock2, 160);
+    engine.block.setHeight(sharedBlock2, 120);
     engine.block.setFill(sharedBlock2, sharedFill);
+    engine.block.appendChild(page, sharedBlock2);
 
-    // eslint-disable-next-line no-console
-    console.log(
-      'Shared fill - Two blocks using the same video fill instance for memory efficiency'
-    );
+    console.log('Shared fill - Two blocks using the same video fill instance');
 
     // ===== Position all blocks in grid layout =====
     const blocks = [
       basicBlock, // Position 0
       coverBlock, // Position 1
       containBlock, // Position 2
-      resourceBlock, // Position 3
+      metadataBlock, // Position 3
       ellipseBlock, // Position 4
       opacityBlock, // Position 5
       sharedBlock1, // Position 6
       sharedBlock2 // Position 7
     ];
 
+    // Position blocks in a grid layout
+    const cols = 4;
+    const spacing = 10;
+    const margin = 50;
+    const blockWidth = 200;
+    const blockHeight = 150;
+
     blocks.forEach((block, index) => {
-      const pos = getPosition(index);
-      engine.block.setPositionX(block, pos.x);
-      engine.block.setPositionY(block, pos.y);
+      const col = index % cols;
+      const row = Math.floor(index / cols);
+      engine.block.setPositionX(block, margin + col * (blockWidth + spacing));
+      engine.block.setPositionY(block, margin + row * (blockHeight + spacing));
     });
 
-    // Select the first block so users can see the fill in action
-    engine.block.setSelected(basicBlock, true);
-
-    // Set playback time to 2 seconds to show video content
-    engine.block.setPlaybackTime(page, 2);
-
-    // Start playback automatically
-    try {
-      engine.block.setPlaying(page, true);
-      // eslint-disable-next-line no-console
-      console.log(
-        'Video fills guide initialized. Playback started. Demonstrating various video fill techniques across the grid.'
-      );
-    } catch (error) {
-      // eslint-disable-next-line no-console
-      console.log(
-        'Video fills guide initialized. Click play to start video playback (browser autoplay restriction).'
-      );
-    }
+    console.log('Video fills demonstration complete.');
+    console.log('Created', blocks.length, 'blocks with video fills.');
+
+  } finally {
+    engine.dispose();
   }
 }
 
-export default Example;
+main().catch(console.error);
 ```
 
-This guide covers how to create video fills, apply them to blocks, configure fill modes, and work with video resources programmatically.
-
 ## Understanding Video Fills
 
-### What is a Video Fill?
-
-A video fill is a fill object that paints a design block with video content. Like color and image fills, video fills are part of CE.SDK's broader fill system.
-
-Video fills are identified by the type `'//ly.img.ubq/fill/video'` or the short form `'video'`. They contain properties for the video source, positioning, scaling, and playback behavior.
-
-### Video Fill vs Video Blocks
-
-**Video fills** are fill objects created with `createFill('video')` and applied to blocks with `setFill()`. You can use them to fill shapes with video content, create video backgrounds, or add video textures to text.
-
-**Video blocks** are created with the convenience method `addVideo()` and come pre-configured with time-based properties including trim support, duration, and playback time. Use video blocks when you need features like trimming, duration adjustment, and precise playback control.
+Video fills work in any scene. Create a scene and add a page to get started.
 
-For this guide, we focus on video fills—applying video content as a fill to design elements. For video editing workflows, see the [Trim Video guide](./edit-video/trim.md).
-
-## Checking Video Fill Support
+```typescript highlight=highlight-create-scene
+// Create a scene with a page
+const scene = engine.scene.create('DepthStack');
+const page = engine.block.create('page');
+engine.block.setWidth(page, 800);
+engine.block.setHeight(page, 600);
+engine.block.appendChild(scene, page);
+```
 
-Before applying video fills, verify that blocks support fills.
+Before working with fills, verify that the block supports fills.
 
-```typescript highlight-check-fill-support
-// Create a sample block to demonstrate fill support checking
-const sampleBlock = engine.block.create('graphic');
-engine.block.setShape(sampleBlock, engine.block.createShape('rect'));
+```typescript highlight=highlight-check-fill-support
+    // Check if block supports fills before accessing fill APIs
+    const testBlock = engine.block.create('graphic');
+    const canHaveFill = engine.block.supportsFill(testBlock);
+    console.log('Block supports fills:', canHaveFill);
 
-// Check if the block supports fills
-const supportsFills = engine.block.supportsFill(sampleBlock);
-// eslint-disable-next-line no-console
-console.log('Block supports fills:', supportsFills); // true for graphic blocks
+    engine.block.destroy(testBlock);
 ```
 
-Graphic blocks, shapes, and text blocks typically support fills. Pages and scenes don't. Always check `supportsFill()` before attempting to apply video fills to prevent errors.
-
-## Creating Video Fills
-
-### Creating Video Fills
+## Creating a Video Fill
 
-Creating a video fill involves three steps: create the fill object, set the video source, and apply it to a block.
+Create a video fill and apply it to a graphic block:
 
-```typescript highlight-create-video-fill
-// Pattern #1: Demonstrate Individual Before Combined
-// Create a basic video fill demonstration
-const basicBlock = engine.block.create('graphic');
-engine.block.setShape(basicBlock, engine.block.createShape('rect'));
-engine.block.setWidth(basicBlock, blockWidth);
-engine.block.setHeight(basicBlock, blockHeight);
-engine.block.appendChild(page, basicBlock);
+```typescript highlight=highlight-create-video-fill
+    // Create a graphic block with a video fill
+    const basicBlock = engine.block.create('graphic');
+    engine.block.setShape(basicBlock, engine.block.createShape('rect'));
+    engine.block.setWidth(basicBlock, 200);
+    engine.block.setHeight(basicBlock, 150);
 
-// Create a video fill
-const basicVideoFill = engine.block.createFill('video');
-// or using full type name: engine.block.createFill('//ly.img.ubq/fill/video');
+    // Create a video fill
+    const videoFill = engine.block.createFill('video');
+    // or using full type name: engine.block.createFill('//ly.img.ubq/fill/video');
 
-// Set the video source URI
-engine.block.setString(basicVideoFill, 'fill/video/fileURI', videoUri);
+    // Set the video source URI
+    engine.block.setString(videoFill, 'fill/video/fileURI', videoUri);
 
-// Apply the fill to the block
-engine.block.setFill(basicBlock, basicVideoFill);
+    // Apply the fill to the block
+    engine.block.setFill(basicBlock, videoFill);
+    engine.block.appendChild(page, basicBlock);
 ```
 
-The video fill exists independently until you attach it to a block. This allows you to configure the fill completely before applying it. Once applied, the fill paints the block with the video content.
-
-### Getting Current Fill Information
+Retrieve the fill from a block and verify its type:
 
-We can retrieve the current fill from a block and inspect its type to verify it's a video fill.
-
-```typescript highlight-get-current-fill
+```typescript highlight=highlight-get-current-fill
 // Get and verify the current fill
 const fillId = engine.block.getFill(basicBlock);
 const fillType = engine.block.getType(fillId);
-// eslint-disable-next-line no-console
 console.log('Fill type:', fillType); // '//ly.img.ubq/fill/video'
 ```
 
-This is useful when building UIs that need to adapt based on the current fill type or when implementing undo/redo functionality that tracks fill changes.
-
 ## Content Fill Modes
 
-Content fill modes control how video scales and positions within blocks. The two primary modes are Cover and Contain, each suited to different use cases.
+Content fill modes control how video content is positioned within the block bounds.
 
 ### Cover Mode
 
-Cover mode fills the entire block with video while maintaining the video's aspect ratio. If the aspect ratios don't match, CE.SDK crops portions of the video to ensure no empty space appears in the block.
+Cover mode scales the video to completely fill the block area. Parts of the video may be cropped if the aspect ratios differ.
 
-```typescript highlight-fill-mode-cover
-// Pattern #2: Content fill mode - Cover
-// Cover mode fills entire block, may crop video to fit
-const coverBlock = engine.block.create('graphic');
-engine.block.setShape(coverBlock, engine.block.createShape('rect'));
-engine.block.setWidth(coverBlock, blockWidth);
-engine.block.setHeight(coverBlock, blockHeight);
-engine.block.appendChild(page, coverBlock);
+```typescript highlight=highlight-fill-mode-cover
+    // Cover mode: Fill entire block, may crop video
+    const coverBlock = engine.block.create('graphic');
+    engine.block.setShape(coverBlock, engine.block.createShape('rect'));
+    engine.block.setWidth(coverBlock, 200);
+    engine.block.setHeight(coverBlock, 150);
 
-const coverVideoFill = engine.block.createFill('video');
-engine.block.setString(coverVideoFill, 'fill/video/fileURI', videoUri);
-engine.block.setFill(coverBlock, coverVideoFill);
+    const coverVideoFill = engine.block.createFill('video');
+    engine.block.setString(coverVideoFill, 'fill/video/fileURI', videoUri);
+    engine.block.setFill(coverBlock, coverVideoFill);
+    engine.block.appendChild(page, coverBlock);
 
-// Set content fill mode to Cover
-engine.block.setEnum(coverBlock, 'contentFill/mode', 'Cover');
+    // Set content fill mode to Cover
+    engine.block.setEnum(coverBlock, 'contentFill/mode', 'Cover');
 
-// Get current fill mode
-const coverMode = engine.block.getEnum(coverBlock, 'contentFill/mode');
-// eslint-disable-next-line no-console
-console.log('Cover block fill mode:', coverMode); // 'Cover'
+    // Get current fill mode
+    const coverMode = engine.block.getEnum(coverBlock, 'contentFill/mode');
+    console.log('Cover block fill mode:', coverMode); // 'Cover'
 ```
 
-Use Cover mode for background videos, full-frame video content, and situations where visual consistency matters more than showing the entire video. It guarantees no empty space but may crop content.
-
 ### Contain Mode
 
-Contain mode fits the entire video within the block while maintaining aspect ratio. If aspect ratios don't match, CE.SDK adds empty space to preserve the full video visibility.
+Contain mode scales the video to fit entirely within the block bounds. The complete video is visible, but empty space may appear if aspect ratios differ.
 
-```typescript highlight-fill-mode-contain
-// Content fill mode - Contain
-// Contain mode fits entire video, may leave empty space
-const containBlock = engine.block.create('graphic');
-engine.block.setShape(containBlock, engine.block.createShape('rect'));
-engine.block.setWidth(containBlock, blockWidth);
-engine.block.setHeight(containBlock, blockHeight);
-engine.block.appendChild(page, containBlock);
+```typescript highlight=highlight-fill-mode-contain
+    // Contain mode: Fit entire video, may leave empty space
+    const containBlock = engine.block.create('graphic');
+    engine.block.setShape(containBlock, engine.block.createShape('rect'));
+    engine.block.setWidth(containBlock, 200);
+    engine.block.setHeight(containBlock, 150);
 
-const containVideoFill = engine.block.createFill('video');
-engine.block.setString(containVideoFill, 'fill/video/fileURI', videoUri);
-engine.block.setFill(containBlock, containVideoFill);
+    const containVideoFill = engine.block.createFill('video');
+    engine.block.setString(containVideoFill, 'fill/video/fileURI', videoUri);
+    engine.block.setFill(containBlock, containVideoFill);
+    engine.block.appendChild(page, containBlock);
 
-// Set content fill mode to Contain
-engine.block.setEnum(containBlock, 'contentFill/mode', 'Contain');
+    // Set content fill mode to Contain
+    engine.block.setEnum(containBlock, 'contentFill/mode', 'Contain');
 ```
 
-Use Contain mode when the entire video must remain visible—presentations, product demos, or content where cropping would lose important information. Empty space is acceptable to preserve complete visibility.
-
-## Loading Video Resources
+### Getting the Current Mode
 
-Before accessing video metadata like duration or dimensions, you must force load the video resource. This ensures CE.SDK has downloaded the necessary information.
-
-```typescript highlight-force-load-resource
-// Force load video resource to access metadata
-const resourceBlock = engine.block.create('graphic');
-engine.block.setShape(resourceBlock, engine.block.createShape('rect'));
-engine.block.setWidth(resourceBlock, blockWidth);
-engine.block.setHeight(resourceBlock, blockHeight);
-engine.block.appendChild(page, resourceBlock);
-
-const resourceVideoFill = engine.block.createFill('video');
-engine.block.setString(resourceVideoFill, 'fill/video/fileURI', videoUri);
-engine.block.setFill(resourceBlock, resourceVideoFill);
-
-// Force load the video resource before accessing metadata
-await engine.block.forceLoadAVResource(resourceVideoFill);
-
-// Now we can access video metadata
-const totalDuration = engine.block.getDouble(
-  resourceVideoFill,
-  'fill/video/totalDuration'
-);
-// eslint-disable-next-line no-console
-console.log('Video total duration:', totalDuration, 'seconds');
+```typescript highlight=highlight-get-fill-mode
+// Get current fill mode
+const currentMode = engine.block.getEnum(containBlock, 'contentFill/mode');
+console.log('Current fill mode:', currentMode);
 ```
 
-Skipping this step causes errors when trying to access metadata. Videos load asynchronously, so `forceLoadAVResource` ensures the metadata is available before you query it.
+The available modes are:
 
-Once loaded, you can access properties like `fill/video/totalDuration` to get the video length in seconds. This information helps you build UI previews or validate user input.
+- `'Crop'` — Default mode, uses crop scale to position content
+- `'Cover'` — Fill entire area, may crop content
+- `'Contain'` — Show all content, may leave empty space
 
-## Common Use Cases
+## Loading Video Resources
 
-### Video as Shape Fill
+Video metadata like duration is only available after the resource loads. Use `forceLoadAVResource()` to ensure the video is loaded before accessing metadata.
 
-Video fills aren't limited to rectangles. You can fill any shape with video content.
+```typescript highlight=highlight-force-load-resource
+    // Force load video resource to access metadata
+    const metadataBlock = engine.block.create('graphic');
+    engine.block.setShape(metadataBlock, engine.block.createShape('rect'));
+    engine.block.setWidth(metadataBlock, 200);
+    engine.block.setHeight(metadataBlock, 150);
 
-```typescript highlight-video-shape-fill
-// Use case: Video as shape fill - Ellipse
-const ellipseBlock = engine.block.create('graphic');
-const ellipseShape = engine.block.createShape('//ly.img.ubq/shape/ellipse');
-engine.block.setShape(ellipseBlock, ellipseShape);
-engine.block.setWidth(ellipseBlock, blockWidth);
-engine.block.setHeight(ellipseBlock, blockHeight);
-engine.block.appendChild(page, ellipseBlock);
+    const metadataVideoFill = engine.block.createFill('video');
+    engine.block.setString(metadataVideoFill, 'fill/video/fileURI', videoUri);
+    engine.block.setFill(metadataBlock, metadataVideoFill);
+    engine.block.appendChild(page, metadataBlock);
 
-const ellipseVideoFill = engine.block.createFill('video');
-engine.block.setString(ellipseVideoFill, 'fill/video/fileURI', videoUri);
-engine.block.setFill(ellipseBlock, ellipseVideoFill);
-```
+    // Force load the video resource before accessing metadata
+    await engine.block.forceLoadAVResource(metadataVideoFill);
 
-Ellipse shapes, polygons, stars, and custom paths all support video fills. The video content fills the shape boundary, masking the video.
+    // Now we can access video metadata
+    const totalDuration = engine.block.getDouble(
+      metadataVideoFill,
+      'fill/video/totalDuration'
+    );
+    console.log('Video total duration:', totalDuration, 'seconds');
+```
 
-### Video with Opacity
+## Common Use Cases
 
-Control the transparency of video-filled blocks to create overlay effects or blend video content with backgrounds.
+### Video in Shapes
 
-```typescript highlight-opacity
-// Advanced: Video fill with opacity
-const opacityBlock = engine.block.create('graphic');
-engine.block.setShape(opacityBlock, engine.block.createShape('rect'));
-engine.block.setWidth(opacityBlock, blockWidth);
-engine.block.setHeight(opacityBlock, blockHeight);
-engine.block.appendChild(page, opacityBlock);
+Fill any shape with video content:
 
-const opacityVideoFill = engine.block.createFill('video');
-engine.block.setString(opacityVideoFill, 'fill/video/fileURI', videoUri);
-engine.block.setFill(opacityBlock, opacityVideoFill);
+```typescript highlight=highlight-video-shape-fill
+    // Fill a shape with video content
+    const ellipseBlock = engine.block.create('graphic');
+    const ellipseShape = engine.block.createShape('//ly.img.ubq/shape/ellipse');
+    engine.block.setShape(ellipseBlock, ellipseShape);
+    engine.block.setWidth(ellipseBlock, 200);
+    engine.block.setHeight(ellipseBlock, 150);
 
-// Set block opacity to 70%
-engine.block.setFloat(opacityBlock, 'opacity', 0.7);
+    const ellipseVideoFill = engine.block.createFill('video');
+    engine.block.setString(ellipseVideoFill, 'fill/video/fileURI', videoUri);
+    engine.block.setFill(ellipseBlock, ellipseVideoFill);
+    engine.block.appendChild(page, ellipseBlock);
 ```
 
-Opacity affects the entire block, including its video fill. This technique creates semi-transparent video overlays, watermarks, or layered compositions where video content blends with other elements.
+### Opacity Control
 
-## Additional Techniques
+Adjust block opacity for transparency effects:
+
+```typescript highlight=highlight-opacity
+    // Control opacity for transparency effects
+    const opacityBlock = engine.block.create('graphic');
+    engine.block.setShape(opacityBlock, engine.block.createShape('rect'));
+    engine.block.setWidth(opacityBlock, 200);
+    engine.block.setHeight(opacityBlock, 150);
+
+    const opacityVideoFill = engine.block.createFill('video');
+    engine.block.setString(opacityVideoFill, 'fill/video/fileURI', videoUri);
+    engine.block.setFill(opacityBlock, opacityVideoFill);
+    engine.block.appendChild(page, opacityBlock);
 
-### Sharing Video Fills
-
-Memory efficiency improves when multiple blocks share a single video fill instance. Changes to the shared fill affect all blocks using it.
-
-```typescript highlight-shared-fill
-// Advanced: Share one video fill between multiple blocks
-const sharedFill = engine.block.createFill('video');
-engine.block.setString(sharedFill, 'fill/video/fileURI', videoUri);
-
-// First block using shared fill
-const sharedBlock1 = engine.block.create('graphic');
-engine.block.setShape(sharedBlock1, engine.block.createShape('rect'));
-engine.block.setWidth(sharedBlock1, blockWidth);
-engine.block.setHeight(sharedBlock1, blockHeight);
-engine.block.appendChild(page, sharedBlock1);
-engine.block.setFill(sharedBlock1, sharedFill);
-
-// Second block using the same shared fill
-const sharedBlock2 = engine.block.create('graphic');
-engine.block.setShape(sharedBlock2, engine.block.createShape('rect'));
-engine.block.setWidth(sharedBlock2, blockWidth * 0.8); // Slightly smaller
-engine.block.setHeight(sharedBlock2, blockHeight * 0.8);
-engine.block.appendChild(page, sharedBlock2);
-engine.block.setFill(sharedBlock2, sharedFill);
-
-// eslint-disable-next-line no-console
-console.log(
-  'Shared fill - Two blocks using the same video fill instance for memory efficiency'
-);
+    // Set block opacity to 70%
+    engine.block.setFloat(opacityBlock, 'opacity', 0.7);
 ```
 
-This pattern reduces memory usage when the same video appears multiple times in a composition. It's particularly useful for repeated elements like watermarks or background patterns.
+## Additional Techniques
 
-Shared fills play back synchronized—all blocks display the same frame at the same time during playback. This ensures visual consistency across multiple elements.
+### Shared Video Fills
 
-## Troubleshooting
+Multiple blocks can share the same fill instance, which improves memory efficiency when displaying the same video in multiple locations.
 
-### Video Not Visible
+```typescript highlight=highlight-shared-fill
+    // Share one video fill between multiple blocks for memory efficiency
+    const sharedFill = engine.block.createFill('video');
+    engine.block.setString(sharedFill, 'fill/video/fileURI', videoUri);
 
-If your video fill doesn't appear, check several common causes. Verify the fill is enabled with `isFillEnabled(block)`. Ensure the video URL is accessible—CORS restrictions on web platforms can block video loading. Confirm the block has valid dimensions (width and height greater than zero) and exists in the scene hierarchy.
+    // First block using shared fill
+    const sharedBlock1 = engine.block.create('graphic');
+    engine.block.setShape(sharedBlock1, engine.block.createShape('rect'));
+    engine.block.setWidth(sharedBlock1, 200);
+    engine.block.setHeight(sharedBlock1, 150);
+    engine.block.setFill(sharedBlock1, sharedFill);
+    engine.block.appendChild(page, sharedBlock1);
 
-Check that the video format is supported on your platform. MP4 with H.264 encoding works reliably across platforms, while other codecs may have limited support.
+    // Second block using the same shared fill
+    const sharedBlock2 = engine.block.create('graphic');
+    engine.block.setShape(sharedBlock2, engine.block.createShape('rect'));
+    engine.block.setWidth(sharedBlock2, 160);
+    engine.block.setHeight(sharedBlock2, 120);
+    engine.block.setFill(sharedBlock2, sharedFill);
+    engine.block.appendChild(page, sharedBlock2);
 
-### Cannot Create Video Fill
+    console.log('Shared fill - Two blocks using the same video fill instance');
+```
 
-If creating a video fill throws an error, verify the block supports fills using `engine.block.supportsFill(block)` and that the block is part of a valid scene hierarchy.
+## Cleanup
 
-### Video Not Loading
+Always dispose of the engine when finished to release resources.
 
-When videos fail to load, verify network connectivity for remote URLs. Check CORS headers—web browsers enforce cross-origin restrictions that can block video access. Validate the URI format uses `https://` for remote videos or appropriate schemes for local files.
+```typescript highlight=highlight-cleanup
+} finally {
+  engine.dispose();
+}
+```
 
-Test with a known working video URL to isolate whether the issue is with your specific video or a broader configuration problem. Check the browser console for detailed error messages.
+## Troubleshooting
 
-### Memory Leaks
+### Video Fill Not Displaying
 
-Always destroy replaced fills to prevent memory leaks. When changing a block's fill, retrieve the old fill with `getFill()`, assign the new fill with `setFill()`, then destroy the old fill with `destroy()`.
+If video fills don't appear:
 
-Don't create fills without attaching them to blocks—unattached fills remain in memory indefinitely. Clean up shared fills when no blocks reference them anymore.
+1. Ensure the video URI is accessible and valid
+2. Check that the block has a shape assigned before setting the fill
+3. Confirm the block has been appended to the page
 
-### Performance Issues
+### Metadata Not Available
 
-Video playback is resource-intensive. Use appropriately sized videos—avoid massive files that strain decoding hardware. Consider lower resolutions for editing with high-resolution sources reserved for export.
+If `fill/video/totalDuration` returns unexpected values:
 
-Limit the number of simultaneously playing videos, especially on mobile devices. Too many concurrent video decodes overwhelm device capabilities. Compress videos before use to reduce file sizes and improve loading times.
+1. Call `engine.block.forceLoadAVResource()` before accessing metadata
+2. Await the promise to ensure loading completes
+3. Verify the video file exists and is accessible
 
 ## API Reference
 
-| Method                                    | Description                      |
-| ----------------------------------------- | -------------------------------- |
-| `createFill('video')`                     | Create a new video fill object   |
-| `setFill(block, fill)`                    | Assign fill to a block           |
-| `getFill(block)`                          | Get the fill ID from a block     |
-| `setString(fill, property, value)`        | Set video URI property           |
-| `getString(fill, property)`               | Get current video URI            |
-| `setSourceSet(fill, property, sources)`   | Set responsive video sources     |
-| `getSourceSet(fill, property)`            | Get current source set           |
-| `setEnum(block, property, value)`         | Set content fill mode            |
-| `getEnum(block, property)`                | Get current fill mode            |
-| `setFillEnabled(block, enabled)`          | Enable or disable fill rendering |
-| `isFillEnabled(block)`                    | Check if fill is enabled         |
-| `supportsFill(block)`                     | Check if block supports fills    |
-| `forceLoadAVResource(fill)`               | Force load video metadata        |
-| `getVideoFillThumbnail(fill, height)`     | Get single thumbnail frame       |
-| `adjustCropToFillFrame(block, fillIndex)` | Adjust crop to fill frame        |
-
-### Video Fill Properties
-
-| Property                   | Type         | Description                                 |
-| -------------------------- | ------------ | ------------------------------------------- |
-| `fill/video/fileURI`       | String       | Single video URI (URL, data URI, file path) |
-| `fill/video/sourceSet`     | SourceSet\[] | Array of responsive video sources           |
-| `fill/video/totalDuration` | Double       | Total duration of video in seconds          |
-
-### Content Fill Properties
-
-| Property           | Type | Values             | Description                   |
-| ------------------ | ---- | ------------------ | ----------------------------- |
-| `contentFill/mode` | Enum | 'Cover', 'Contain' | How video scales within block |
+| Property                   | Type     | Description                            |
+| -------------------------- | -------- | -------------------------------------- |
+| `fill/video/fileURI`       | `string` | URI of the video file                  |
+| `fill/video/totalDuration` | `double` | Total duration of the video in seconds |
+| `contentFill/mode`         | `enum`   | Fill mode: 'Crop', 'Cover', 'Contain'  |
+| `opacity`                  | `float`  | Block opacity from 0.0 to 1.0          |
+
+
 
 ---
 
 ## 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