@imgly/codesign-mcp 0.1.0

package/assets/docs/guide/insert-media/videos.md

@@ -0,0 +1,308 @@
+> 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).
+
+**Navigation:** [Guides](./guides.md) > [Insert Media Assets](./insert-media.md) > [Insert Videos](./insert-media/videos.md)
+
+---
+
+Insert videos into your CE.SDK scenes using either the convenience API or manual block creation with video fills.
+
+![Insert Videos example showing the CE.SDK editor with video insertion buttons](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
+
+> **Reading time:** 8 minutes
+>
+> **Resources:**
+>
+> - [Download examples](https://github.com/imgly/cesdk-web-examples/archive/refs/tags/release-$UBQ_VERSION$.zip)
+> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-insert-media-videos-browser)
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-insert-media-videos-browser)
+> - [Live demo](https://img.ly/docs/cesdk/examples/guides-insert-media-videos-browser/)
+
+Videos in CE.SDK are graphic blocks with video fills. Two approaches exist: the `addVideo()` convenience method, and manual block creation with video fills.
+
+```typescript file=@cesdk_web_examples/guides-insert-media-videos-browser/browser.ts reference-only
+import type { EditorPlugin, EditorPluginContext } from '@cesdk/cesdk-js';
+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 packageJson from './package.json';
+
+/**
+ * CE.SDK Plugin: Insert Videos Guide
+ *
+ * Demonstrates inserting videos into a CE.SDK scene:
+ * - Using the addVideo() convenience API
+ * - Using graphic blocks with video fills
+ * - Configuring trim offset and trim length
+ */
+class Example implements EditorPlugin {
+  name = packageJson.name;
+
+  version = packageJson.version;
+
+  async initialize({ cesdk }: EditorPluginContext): Promise<void> {
+    if (cesdk == null) {
+      throw new Error('CE.SDK instance is required 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 }
+      }
+    });
+
+    const engine = cesdk.engine;
+
+    // Videos from the ly.img.video demo asset source
+    const surferVideoUrl =
+      'https://cdn.img.ly/assets/demo/v3/ly.img.video/videos/pexels-drone-footage-of-a-surfer-barrelling-a-wave-12715991.mp4';
+    const laptopVideoUrl =
+      'https://cdn.img.ly/assets/demo/v3/ly.img.video/videos/pexels-tony-schnagl-5528015.mp4';
+
+    const page = engine.scene.getCurrentPage();
+    if (page == null) return;
+
+    // Get page dimensions for responsive layout
+    const pageWidth = engine.block.getWidth(page);
+    const pageHeight = engine.block.getHeight(page);
+
+    // Layout: videos span width with margins, each takes half height
+    const margin = 40;
+    const gap = 20;
+    const videoWidth = pageWidth - margin * 2;
+    const videoHeight = (pageHeight - margin * 2 - gap) / 2;
+
+    const videoBlock = await engine.block.addVideo(
+      surferVideoUrl,
+      videoWidth,
+      videoHeight
+    );
+    engine.block.setPositionX(videoBlock, margin);
+    engine.block.setPositionY(videoBlock, margin);
+
+    const block = engine.block.create('graphic');
+    engine.block.setShape(block, engine.block.createShape('rect'));
+    const fill = engine.block.createFill('video');
+    engine.block.setString(fill, 'fill/video/fileURI', laptopVideoUrl);
+    engine.block.setFill(block, fill);
+
+    engine.block.setWidth(block, videoWidth);
+    engine.block.setHeight(block, videoHeight);
+    engine.block.setPositionX(block, margin);
+    engine.block.setPositionY(block, margin + videoHeight + gap);
+    engine.block.appendChild(page, block);
+
+    // Force load the first video's resource for thumbnails
+    const videoBlockFill = engine.block.getFill(videoBlock);
+    await engine.block.forceLoadAVResource(videoBlockFill);
+
+    await engine.block.forceLoadAVResource(fill);
+    engine.block.setTrimOffset(fill, 2.0);
+    engine.block.setTrimLength(fill, 5.0);
+
+    const duration = engine.block.getAVResourceTotalDuration(fill);
+    console.log(`Video duration: ${duration}s, playing 2-7s`);
+
+    // Set playback time to 1 second for hero image capture
+    engine.block.setPlaybackTime(page, 1.0);
+
+    // Wait a moment for thumbnails to generate
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+
+    // Enable zoom auto-fit to keep the page in view
+    engine.scene.enableZoomAutoFit(page, 'Both', 40, 40, 40, 40);
+
+    // Select the page for a cleaner hero image
+    engine.block.select(page);
+  }
+}
+
+export default Example;
+```
+
+This guide covers how to insert videos using the UI, add videos programmatically, and configure video properties like trim offset and length.
+
+## Insert Videos Using the UI
+
+Users can upload videos through the Upload menu in the asset panel or by dragging and dropping video files directly onto the canvas. CE.SDK supports MP4 (H.264) and WebM (VP8/VP9) formats.
+
+After inserting a video, users can move it by dragging, resize it with corner handles, trim it using timeline controls, and crop it to show specific portions.
+
+## Setup
+
+Enable video features and create a scene.
+
+```typescript highlight=highlight-setup
+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 }
+  }
+});
+```
+
+This creates a scene for the video composition.
+
+## Add Videos with addVideo()
+
+The `addVideo()` method creates a graphic block with video fill in a single call. This is the simplest approach.
+
+```typescript highlight=highlight-add-video-convenience
+const videoBlock = await engine.block.addVideo(
+  surferVideoUrl,
+  videoWidth,
+  videoHeight
+);
+engine.block.setPositionX(videoBlock, margin);
+engine.block.setPositionY(videoBlock, margin);
+```
+
+Pass the video URL, width, and height as parameters. The method returns the block ID for further manipulation like positioning.
+
+## Add Videos with Graphic Blocks
+
+For more control, manually create a graphic block and attach a video fill.
+
+```typescript highlight=highlight-add-video-manual
+const block = engine.block.create('graphic');
+engine.block.setShape(block, engine.block.createShape('rect'));
+const fill = engine.block.createFill('video');
+engine.block.setString(fill, 'fill/video/fileURI', laptopVideoUrl);
+engine.block.setFill(block, fill);
+```
+
+Create a graphic block, attach a rectangular shape, create a video fill with the source URI, and apply the fill to the block. This pattern mirrors image fills.
+
+## Configure Trim Settings
+
+Control which portion of a video plays by setting the trim offset and length. First load the video resource to access duration metadata.
+
+```typescript highlight=highlight-configure-trim
+await engine.block.forceLoadAVResource(fill);
+engine.block.setTrimOffset(fill, 2.0);
+engine.block.setTrimLength(fill, 5.0);
+```
+
+The `setTrimOffset()` method specifies where playback starts. A value of 2.0 skips the first two seconds. The `setTrimLength()` method defines how long the clip plays from that offset.
+
+> **Note:** Trim operations are applied to the fill, not the block. Use `getFill()` to get the fill ID first.
+
+## Supported Video Formats
+
+CE.SDK supports common web video formats:
+
+- **MP4 (H.264 codec)** — widest browser support, recommended for most use cases
+- **WebM (VP8/VP9 codec)** — open format with good compression
+
+For maximum compatibility, use MP4 with H.264 encoding.
+
+## Troubleshooting
+
+### Video Not Visible
+
+- Verify the file URI is correct and accessible
+- Ensure the video format is supported (MP4, WebM)
+- Check that the block is appended to the page with `appendChild()`
+- Confirm dimensions are set with `setWidth()` and `setHeight()`
+
+### Trim Not Working
+
+- Ensure you're calling trim methods on the fill, not the block
+- Call `forceLoadAVResource()` before setting trim values
+- Verify trim offset + trim length doesn't exceed total duration
+
+## API Reference
+
+| Method                                             | Description                        |
+| -------------------------------------------------- | ---------------------------------- |
+| `block.addVideo(url, width, height)`               | Create video block with video fill |
+| `block.create('graphic')`                          | Create graphic block container     |
+| `block.createShape('rect')`                        | Create rectangular shape           |
+| `block.setShape(block, shape)`                     | Apply shape to block               |
+| `block.createFill('video')`                        | Create video fill                  |
+| `block.setString(fill, 'fill/video/fileURI', url)` | Set video source URI               |
+| `block.setFill(block, fill)`                       | Apply fill to block                |
+| `block.forceLoadAVResource(fill)`                  | Load video metadata                |
+| `block.getAVResourceTotalDuration(fill)`           | Get video duration in seconds      |
+| `block.setTrimOffset(fill, seconds)`               | Set trim start point               |
+| `block.setTrimLength(fill, seconds)`               | Set trim duration                  |
+
+## Next Steps
+
+- [Create video projects](./create-video/overview.md) with timeline editing
+- [Apply filters and effects](./filters-and-effects/apply.md) to enhance appearance
+- [Export your design](./export-save-publish/export/overview.md) to various formats
+
+---
+
+## More Resources
+
+- **[Vanilla JS/TS Documentation Index](https://img.ly/docs/cesdk/js.md)** - Browse all Vanilla JS/TS 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

package/assets/docs/guide/insert-media.md

@@ -0,0 +1,24 @@
+> 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).
+
+**Navigation:** [Guides](./guides.md) > [Insert Media Assets](./insert-media.md)
+
+---
+
+---
+
+## Related Pages
+
+- [Overview](./overview.md) - Understand how insertion works, how inserted media behave within scenes, and how to control them via UI or code.
+- [Insert Images](./insert-media/images.md) - Documentation for Insert Images
+- [Insert Videos](./insert-media/videos.md) - Learn how to insert videos into CE.SDK scenes using the convenience API or manual block creation with video fills.
+- [Insert Audio](./insert-media/audio.md) - Add audio files to your video projects programmatically, configure timeline position, volume, and playback properties.
+- [Insert Shapes or Stickers](./insert-media/shapes-or-stickers.md) - Add shapes and stickers to your designs using CE.SDK. Create rectangles, ellipses, stars, polygons, lines, and custom vector paths programmatically or through the built-in UI.
+
+---
+
+## More Resources
+
+- **[Vanilla JS/TS Documentation Index](https://img.ly/docs/cesdk/js.md)** - Browse all Vanilla JS/TS 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

package/assets/docs/guide/key-capabilities.md

@@ -0,0 +1,24 @@
+> 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).
+
+**Navigation:** [Concepts](./concepts.md) > [Key Capabilities](./key-capabilities.md)
+
+---
+
+This guide gives you a high-level look at what CreativeEditor SDK (CE.SDK) can do—and how deeply it can integrate into your workflows. Whether you’re building a design editor into your product, enabling automation, or scaling personalized content creation, CE.SDK provides a flexible and future-ready foundation.
+
+[Launch Web Demo](https://img.ly/showcases/cesdk)
+
+It’s designed for developers, product teams, and technical decision-makers evaluating how CE.SDK fits their use case.
+
+- 100% client-side processing
+- Custom-built rendering engine for consistent cross-platform performance
+- Flexible enough for both low-code and fully custom implementations
+
+---
+
+## More Resources
+
+- **[Vanilla JS/TS Documentation Index](https://img.ly/docs/cesdk/js.md)** - Browse all Vanilla JS/TS 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

package/assets/docs/guide/key-concepts.md

@@ -0,0 +1,83 @@
+> 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).
+
+**Navigation:** [Concepts](./concepts.md) > [Key Concepts](./key-concepts.md)
+
+---
+
+CE.SDK is built on two distinct technical layers that work together seamlessly:
+
+- **User Interface** — Pre-built editors optimized for different use cases
+- **Engine Interface** — Core rendering and processing engine
+
+![The different layers CE.SDK is made of, see description below.](https://img.ly/docs/cesdk/layers.png)
+
+This intentional separation gives you powerful advantages:
+
+1. **Cross-platform consistency** – The engine is cross-compiled to native web, iOS, Android, and Node.js, ensuring identical output everywhere
+2. **Custom UI** – Build your own UI for simpler tools and workflows
+3. **Headless automation** – Run the engine independently for automations and batch processing, both client-side and server-side
+
+## Creative Engine
+
+The Creative Engine powers all core editing operations. It handles rendering, processing, and manipulation across images, layouts, text, video, audio, and vectors.
+
+**What the Engine Does:**
+
+- Maintains the scene file (your structured content)
+- Renders the canvas in real-time
+- Handles block positioning and resizing
+- Applies filters and effects to images
+- Manages text editing and typography
+- Controls templates with role-based permissions
+- Displays smart guides and snap lines
+
+Every engine capability is exposed through a comprehensive API, letting you build custom UIs, workflows, and automations.
+
+## Headless / Engine only
+
+Use the engine without any UI for powerful automation scenarios:
+
+**Client-side automation**
+Perfect for in-browser batch operations and dynamic content generation without server dependencies.
+
+**Server-side automation with Node.js**
+Use the [Node.JS SDK](./what-is-cesdk.md) for following scenarios:
+
+- **High-resolution processing** – Edit on the client with preview quality, then render server-side with full-resolution assets
+- **Bulk generation** – Create a large volume of design variations for variable data printing
+- **Non-blocking workflows** – Let users continue designing while exports process in the background
+
+**Server-side export with the CE.SDK Renderer**
+When exporting complex graphics and videos, the [CE.SDK Renderer](#broken-link-7f3e9a) can make use of GPU acceleration and video codecs on Linux server environments.
+
+**Plugin development**
+When building CE.SDK plugins, you get direct API access to manipulate canvas elements programmatically.
+
+## User Interface Components
+
+CE.SDK includes pre-built UI configurations optimized for different use cases:
+
+- **Photo editing** — Advanced image editing tools and filters
+- **Video editing** — Timeline-based video editing and effects
+- **Design editing** — Layout and graphic design tools (similar to Canva)
+- **2D product design** — Apparel, postcards, and custom product templates
+
+More configurations are coming based on customer needs.
+
+## UI Customization
+
+While UI configurations provide a solid foundation, you maintain control over the user experience:
+
+- Apply **custom color schemes** and branding to match your product
+- Add **custom asset libraries** with your own fonts, images, graphics, videos, and audio
+
+The plugin architecture lets you add custom buttons and panels throughout the interface, ensuring the editor feels native to your product.
+
+---
+
+## More Resources
+
+- **[Vanilla JS/TS Documentation Index](https://img.ly/docs/cesdk/js.md)** - Browse all Vanilla JS/TS 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

package/assets/docs/guide/licensing.md

@@ -0,0 +1,45 @@
+> 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).
+
+**Navigation:** [Get Started](./get-started/overview.md) > [Licensing](./licensing.md)
+
+---
+
+Thanks for your interest in CreativeEditor SDK (CE.SDK).
+
+We offer flexible commercial licensing options to support teams and projects of all sizes. Whether you're building a new product or scaling an existing one, our goal is to provide the best creative editing experience—backed by a licensing model that aligns with your needs.
+
+Get in touch with us through our [contact sales form](https://img.ly/forms/contact-sales).
+
+## Commercial Licensing
+
+CE.SDK is offered through a subscription-based commercial model. This allows us to:
+
+- Deliver ongoing updates and performance improvements
+- Ensure compatibility with new browsers and devices
+- Provide dedicated technical support
+- Build long-term partnerships with our customers
+
+## How Licensing Works
+
+CE.SDK licenses are tied to a single commercial product instance, verified by the hostname for web apps and bundle/app ID for mobile apps.
+
+Licensing typically uses remote validation and includes lightweight event tracking. It’s possible to disable tracking or use offline-compatible options. To explore these options, [contact our sales team](https://img.ly/forms/contact-sales).
+
+## Trial License Key
+
+Trial licenses are available for evaluation and testing and are valid for **30 days**. They provide full access to CE.SDK’s features so you can explore its capabilities in your environment.
+
+If you need more time to evaluate, [contact our sales team](https://img.ly/forms/contact-sales).
+
+## Testing and Production
+
+Paid license keys can be used across development, staging, and production environments. Multiple domains or app identifiers can be added to support this setup.
+
+---
+
+## More Resources
+
+- **[Vanilla JS/TS Documentation Index](https://img.ly/docs/cesdk/js.md)** - Browse all Vanilla JS/TS 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

package/assets/docs/guide/llms-txt.md

@@ -0,0 +1,53 @@
+> 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).
+
+**Navigation:** [Get Started](./get-started/overview.md) > [Build with AI](./get-started/build-with-ai.md) > [LLMs.txt](./llms-txt.md)
+
+---
+
+> **Note:** You can also connect your AI assistant directly to our documentation using our [MCP Server](./get-started/mcp-server.md). This enables real-time search and retrieval without downloading large files.
+
+Our documentation is now available in LLMs.txt format, optimized for AI reasoning engines. To better support platform-specific development, we've created separate documentation files for each platform.
+
+For developers, this means you can now access documentation tailored to your specific platform, whether it's iOS, Android, Web, or any other supported platform. This approach allows for a more focused and efficient use of AI tools in your development workflow.
+
+[Download](<https://img.ly/docs/cesdk/getFullUrl(`/${props.platform.slug}/llms-full.txt`)>)
+
+These documentation files are substantial in size, with token counts exceeding the context windows of many AI models. This guide explains how to download and effectively use these platform-specific documentation files with AI tools to accelerate your development process.
+
+## What are LLMs.txt files?
+
+LLMs.txt is an emerging standard for making documentation AI-friendly. Unlike traditional documentation formats, LLMs.txt:
+
+- Presents content in a clean, markdown-based format
+- Eliminates extraneous HTML, CSS, and JavaScript
+- Optimizes content for AI context windows
+- Provides a comprehensive view of documentation in a single file
+
+By using our platform-specific LLMs.txt files, you'll ensure that AI tools have the most relevant and complete context for helping with your development tasks.
+
+## Markdown Content Negotiation
+
+Our documentation pages also serve clean markdown directly when requested with the `Accept: text/markdown` HTTP header. AI agents and tools that support content negotiation can fetch any documentation page and receive a markdown response instead of HTML — no separate download required.
+
+```bash
+curl -H "Accept: text/markdown" https://img.ly/docs/cesdk/react/get-started/overview/
+```
+
+This means AI tools like web-browsing agents can access individual pages in a format optimized for their context windows without needing the full LLMs.txt bundle.
+
+## Handling Large Documentation Files
+
+Due to the size of our documentation files (upward of 500 000 tokens) most AI tools will face context window limitations. Standard models typically have context windows ranging from 8,000 to 200,000 tokens, making it challenging to process our complete documentation in a single session.
+
+### Using Large Documentation Files
+
+To work with our complete documentation files, use an AI model with a large context window. Many current models support 200,000+ tokens, and some support over 1 million tokens. Check your model's context window limits when loading the full documentation file.
+
+---
+
+## More Resources
+
+- **[Vanilla JS/TS Documentation Index](https://img.ly/docs/cesdk/js.md)** - Browse all Vanilla JS/TS 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

package/assets/docs/guide/open-the-editor/blank-canvas.md

@@ -0,0 +1,124 @@
+> 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).
+
+**Navigation:** [Guides](./guides.md) > [Open the Editor](./open-the-editor.md) > [Start With Blank Canvas](./open-the-editor/blank-canvas.md)
+
+---
+
+Create a new scene from scratch to build designs with complete control over canvas dimensions and initial content.
+
+![Start With Blank Canvas example showing an empty page in the editor](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
+
+> **Reading time:** 5 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-open-the-editor-blank-canvas-browser)
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-open-the-editor-blank-canvas-browser)
+> - [Live demo](https://img.ly/docs/cesdk/examples/guides-open-the-editor-blank-canvas-browser/)
+
+Starting from a blank canvas lets you build new designs without pre-existing content. The `engine.scene.create()` method creates an empty scene with its own camera, ready for adding pages and content. This differs from loading templates or images, which start with existing content.
+
+> **Other Ways to Create Scenes:** You can also start with existing content:\* [Create From Image](./open-the-editor/from-image.md) — Start with an image as the base
+>
+> - [Load a Scene](./open-the-editor/load-scene.md) — Resume editing a previously saved design
+
+```typescript file=@cesdk_web_examples/guides-open-the-editor-blank-canvas-browser/browser.ts reference-only
+import type { EditorPlugin, EditorPluginContext } from '@cesdk/cesdk-js';
+
+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 for this plugin');
+    }
+
+    await cesdk.addPlugin(new DesignEditorConfig());
+    const engine = cesdk.engine;
+
+    // ========================================
+    // Create an Empty Scene
+    // ========================================
+    // Create a new empty scene with a page of specific dimensions
+    engine.scene.create('VerticalStack', {
+      page: { size: { width: 800, height: 600 } }
+    });
+
+    // Find the page that was automatically created
+    const pages = engine.block.findByType('page');
+    const page = pages[0];
+
+    // ========================================
+    // Enable Auto-Fit Zoom
+    // ========================================
+    // Enable auto-fit zoom to keep the page visible when resizing
+    // This continuously adjusts the zoom level to fit the page horizontally
+    engine.scene.zoomToBlock(page);
+    engine.scene.enableZoomAutoFit(page, 'Horizontal', 40, 40);
+  }
+}
+
+export default Example;
+```
+
+This guide covers how to create an empty scene with custom page dimensions and configure the viewport for editing.
+
+## Create an Empty Scene
+
+We call `engine.scene.create()` to create a new design scene. We pass the layout type and options parameter to specify page dimensions. The scene includes a page automatically when we provide size options.
+
+```typescript highlight-create-scene
+// Create a new empty scene with a page of specific dimensions
+engine.scene.create('VerticalStack', {
+  page: { size: { width: 800, height: 600 } }
+});
+```
+
+The first parameter specifies the scene layout. Use `'Free'` for independent page positioning, `'VerticalStack'` or `'HorizontalStack'` for aligned layouts. The options object configures the initial page with a size in design units.
+
+## Enable Auto-Fit Zoom
+
+For interactive editing, we enable auto-fit zoom to keep the page visible when the viewport resizes. This provides a responsive editing experience where the canvas automatically adjusts to the available space.
+
+```typescript highlight-zoom
+// Enable auto-fit zoom to keep the page visible when resizing
+// This continuously adjusts the zoom level to fit the page horizontally
+engine.scene.zoomToBlock(page);
+engine.scene.enableZoomAutoFit(page, 'Horizontal', 40, 40);
+```
+
+The `enableZoomAutoFit()` method continuously adjusts the zoom level to fit the specified block. Use `'Horizontal'` to fit the width, `'Vertical'` to fit the height, or `'Both'` to fit both dimensions. The padding parameters add space around the content.
+
+For one-time zoom adjustments, use `zoomToBlock()` instead. The editor UI also provides built-in zoom controls that users can access through the canvas toolbar.
+
+## API Reference
+
+| Method                                                                     | Description                                             |
+| -------------------------------------------------------------------------- | ------------------------------------------------------- |
+| `engine.scene.create(layout, options)`                                     | Creates an empty scene with optional page configuration |
+| `engine.block.findByType('page')`                                          | Finds all pages in the current scene                    |
+| `engine.scene.enableZoomAutoFit(block, axis, paddingBefore, paddingAfter)` | Continuously adjusts zoom to fit a block                |
+| `engine.scene.zoomToBlock(block, options)`                                 | One-time zoom adjustment to frame a block               |
+| `engine.scene.disableZoomAutoFit(block)`                                   | Disables auto-fit zoom                                  |
+
+## Next Steps
+
+Now that you have created a design from a blank canvas, explore related topics:
+
+- [Save](./export-save-publish/save.md) — Persist your design to a file or backend service
+- [Blocks](./concepts/blocks.md) — Learn about scene hierarchy and block relationships
+- [Create From Image](./open-the-editor/from-image.md) — Start with an existing image instead of a blank canvas
+
+---
+
+## More Resources
+
+- **[Vanilla JS/TS Documentation Index](https://img.ly/docs/cesdk/js.md)** - Browse all Vanilla JS/TS 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