@imgly/codesign-mcp 0.1.0

package/assets/docs/guide/concepts/scenes.md

@@ -0,0 +1,443 @@
+> 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) > [Scenes](./concepts/scenes.md)
+
+---
+
+Scenes are the root container for all designs in CE.SDK. They hold pages,
+blocks, and the camera that controls what you see in the canvas—and the engine
+manages only one active scene at a time.
+
+![Scenes example showing a two-page design with different shapes on each page](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
+
+> **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-concepts-scenes-browser)
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-concepts-scenes-browser)
+> - [Live demo](https://img.ly/docs/cesdk/examples/guides-concepts-scenes-browser/)
+
+Every design you create starts with a scene. Scenes contain pages, and pages contain the visible design elements—text, images, shapes, and other blocks. Understanding how scenes work is essential for building, saving, and restoring user designs.
+
+```typescript file=@cesdk_web_examples/guides-concepts-scenes-browser/browser.ts reference-only
+import type { EditorPlugin, EditorPluginContext } from '@cesdk/cesdk-js';
+
+import { DesignEditorConfig } from './design-editor/plugin';
+import packageJson from './package.json';
+
+/**
+ * CE.SDK Plugin: Scenes Guide
+ *
+ * Demonstrates the complete scene lifecycle in CE.SDK:
+ * - Creating scenes with different layouts
+ * - Managing pages within scenes
+ * - Configuring scene properties
+ * - Saving and loading scenes
+ * - Camera control and zoom
+ */
+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 a new design scene with VerticalStack layout
+    // The layout controls how pages are arranged in the canvas
+    engine.scene.create('VerticalStack');
+
+    // Get the stack container and add spacing between pages
+    const stack = engine.block.findByType('stack')[0];
+    engine.block.setFloat(stack, 'stack/spacing', 20);
+    engine.block.setBool(stack, 'stack/spacingInScreenspace', true);
+
+    // Create the first page
+    const page1 = engine.block.create('page');
+    engine.block.setWidth(page1, 800);
+    engine.block.setHeight(page1, 600);
+    engine.block.appendChild(stack, page1);
+
+    // Create a second page
+    const page2 = engine.block.create('page');
+    engine.block.setWidth(page2, 800);
+    engine.block.setHeight(page2, 600);
+    engine.block.appendChild(stack, page2);
+
+    // Add a shape to the first page
+    const graphic1 = engine.block.create('graphic');
+    engine.block.setShape(graphic1, engine.block.createShape('rect'));
+    const fill1 = engine.block.createFill('color');
+    engine.block.setColor(fill1, 'fill/color/value', {
+      r: 0.2,
+      g: 0.4,
+      b: 0.9,
+      a: 1
+    });
+    engine.block.setFill(graphic1, fill1);
+    engine.block.setWidth(graphic1, 400);
+    engine.block.setHeight(graphic1, 300);
+    engine.block.setPositionX(graphic1, 200);
+    engine.block.setPositionY(graphic1, 150);
+    engine.block.appendChild(page1, graphic1);
+
+    // Add a different shape to the second page
+    const graphic2 = engine.block.create('graphic');
+    engine.block.setShape(graphic2, engine.block.createShape('ellipse'));
+    const fill2 = engine.block.createFill('color');
+    engine.block.setColor(fill2, 'fill/color/value', {
+      r: 0.9,
+      g: 0.3,
+      b: 0.2,
+      a: 1
+    });
+    engine.block.setFill(graphic2, fill2);
+    engine.block.setWidth(graphic2, 350);
+    engine.block.setHeight(graphic2, 350);
+    engine.block.setPositionX(graphic2, 225);
+    engine.block.setPositionY(graphic2, 125);
+    engine.block.appendChild(page2, graphic2);
+
+    // Query scene properties
+    const currentUnit = engine.scene.getDesignUnit();
+    // eslint-disable-next-line no-console
+    console.log('Scene design unit:', currentUnit);
+
+    // Get the scene layout
+    const layout = engine.scene.getLayout();
+    // eslint-disable-next-line no-console
+    console.log('Scene layout:', layout);
+
+    // Access pages within the scene
+    const pages = engine.scene.getPages();
+    // eslint-disable-next-line no-console
+    console.log('Number of pages:', pages.length);
+
+    // Get the current page (nearest to viewport center)
+    const currentPage = engine.scene.getCurrentPage();
+    // eslint-disable-next-line no-console
+    console.log('Current page ID:', currentPage);
+
+    // Zoom to show all pages in the scene
+    const scene = engine.scene.get();
+    if (scene) {
+      await engine.scene.zoomToBlock(scene, { padding: 50 });
+    }
+
+    // Get the current zoom level
+    const zoomLevel = engine.scene.getZoomLevel();
+    // eslint-disable-next-line no-console
+    console.log('Current zoom level:', zoomLevel);
+
+    // Save the scene to a string for persistence
+    const sceneString = await engine.scene.saveToString();
+    // eslint-disable-next-line no-console
+    console.log('Scene saved successfully. String length:', sceneString.length);
+
+    // Demonstrate loading the scene from the saved string
+    // This replaces the current scene with the saved version
+    await engine.scene.loadFromString(sceneString);
+    // eslint-disable-next-line no-console
+    console.log('Scene loaded from saved string');
+
+    // Zoom to show all loaded pages
+    const loadedScene = engine.scene.get();
+    if (loadedScene) {
+      await engine.scene.zoomToBlock(loadedScene, { padding: 50 });
+    }
+
+    // eslint-disable-next-line no-console
+    console.log('Scenes guide initialized successfully.');
+  }
+}
+
+export default Example;
+```
+
+This guide covers how to create scenes from scratch, manage pages within scenes, configure scene properties, save and load designs, and control the camera's zoom and position.
+
+## Scene Hierarchy
+
+Scenes form the root of CE.SDK's design structure. The hierarchy works as follows:
+
+- **Scene** — The root container holding all design content
+- **Pages** — Direct children of scenes, arranged according to the scene's layout
+- **Blocks** — Design elements (text, images, shapes) that belong to pages
+
+Only blocks attached to pages within the active scene are rendered in the canvas. Use `engine.scene.get()` to retrieve the current scene and `engine.scene.getPages()` to access its pages.
+
+## Creating Scenes
+
+### Creating an Empty Scene
+
+Use `engine.scene.create()` to create a new design scene with a configurable page layout. The layout parameter controls how pages are arranged in the canvas.
+
+```typescript highlight-create-scene
+// Create a new design scene with VerticalStack layout
+// The layout controls how pages are arranged in the canvas
+engine.scene.create('VerticalStack');
+
+// Get the stack container and add spacing between pages
+const stack = engine.block.findByType('stack')[0];
+engine.block.setFloat(stack, 'stack/spacing', 20);
+engine.block.setBool(stack, 'stack/spacingInScreenspace', true);
+```
+
+Available layouts include:
+
+- `VerticalStack` — Pages stacked vertically
+- `HorizontalStack` — Pages arranged horizontally
+- `DepthStack` — Pages layered on top of each other
+- `Free` — Manual positioning
+
+### Adding Pages
+
+After creating a scene, add pages using `engine.block.create('page')`. Configure the page dimensions and append it to the scene's stack container.
+
+```typescript highlight-create-page
+// Create the first page
+const page1 = engine.block.create('page');
+engine.block.setWidth(page1, 800);
+engine.block.setHeight(page1, 600);
+engine.block.appendChild(stack, page1);
+
+// Create a second page
+const page2 = engine.block.create('page');
+engine.block.setWidth(page2, 800);
+engine.block.setHeight(page2, 600);
+engine.block.appendChild(stack, page2);
+```
+
+### Adding Blocks
+
+With pages in place, add design elements like shapes, text, or images. Create a graphic block, configure its shape and fill, then append it to a page.
+
+```typescript highlight-create-block
+// Add a shape to the first page
+const graphic1 = engine.block.create('graphic');
+engine.block.setShape(graphic1, engine.block.createShape('rect'));
+const fill1 = engine.block.createFill('color');
+engine.block.setColor(fill1, 'fill/color/value', {
+  r: 0.2,
+  g: 0.4,
+  b: 0.9,
+  a: 1
+});
+engine.block.setFill(graphic1, fill1);
+engine.block.setWidth(graphic1, 400);
+engine.block.setHeight(graphic1, 300);
+engine.block.setPositionX(graphic1, 200);
+engine.block.setPositionY(graphic1, 150);
+engine.block.appendChild(page1, graphic1);
+
+// Add a different shape to the second page
+const graphic2 = engine.block.create('graphic');
+engine.block.setShape(graphic2, engine.block.createShape('ellipse'));
+const fill2 = engine.block.createFill('color');
+engine.block.setColor(fill2, 'fill/color/value', {
+  r: 0.9,
+  g: 0.3,
+  b: 0.2,
+  a: 1
+});
+engine.block.setFill(graphic2, fill2);
+engine.block.setWidth(graphic2, 350);
+engine.block.setHeight(graphic2, 350);
+engine.block.setPositionX(graphic2, 225);
+engine.block.setPositionY(graphic2, 125);
+engine.block.appendChild(page2, graphic2);
+```
+
+## Scene Properties
+
+### Design Units
+
+Query or configure how measurements are interpreted using `engine.scene.getDesignUnit()` and `engine.scene.setDesignUnit()`. This is useful for print workflows where precise physical dimensions matter.
+
+```typescript highlight-scene-properties
+// Query scene properties
+const currentUnit = engine.scene.getDesignUnit();
+// eslint-disable-next-line no-console
+console.log('Scene design unit:', currentUnit);
+
+// Get the scene layout
+const layout = engine.scene.getLayout();
+// eslint-disable-next-line no-console
+console.log('Scene layout:', layout);
+```
+
+Supported units are `'Pixel'`, `'Millimeter'`, and `'Inch'`. For more details, see the [Design Units](./concepts/design-units.md) guide.
+
+### Scene Layout
+
+Control how pages are arranged using `engine.scene.getLayout()` and `engine.scene.setLayout()`. The layout affects how users navigate between pages in multi-page designs.
+
+## Page Navigation
+
+Access pages within your scene using these methods:
+
+```typescript highlight-page-navigation
+// Access pages within the scene
+const pages = engine.scene.getPages();
+// eslint-disable-next-line no-console
+console.log('Number of pages:', pages.length);
+
+// Get the current page (nearest to viewport center)
+const currentPage = engine.scene.getCurrentPage();
+// eslint-disable-next-line no-console
+console.log('Current page ID:', currentPage);
+```
+
+The `getCurrentPage()` method returns the page nearest to the viewport center—useful for determining which page the user is currently viewing.
+
+## Camera and Zoom
+
+### Zoom to Block
+
+Use `engine.scene.zoomToBlock()` to frame a specific block in the viewport with padding. Pass the scene block to show all pages:
+
+```typescript highlight-camera-zoom
+// Zoom to show all pages in the scene
+const scene = engine.scene.get();
+if (scene) {
+  await engine.scene.zoomToBlock(scene, { padding: 50 });
+}
+
+// Get the current zoom level
+const zoomLevel = engine.scene.getZoomLevel();
+// eslint-disable-next-line no-console
+console.log('Current zoom level:', zoomLevel);
+```
+
+### Zoom Level
+
+Get and set the zoom level directly with `engine.scene.getZoomLevel()` and `engine.scene.setZoomLevel()`. A zoom level of 1.0 means one design unit equals one screen pixel.
+
+### Auto-Fit Zoom
+
+For continuous auto-framing, use `engine.scene.enableZoomAutoFit()` to automatically keep a block centered as the viewport resizes.
+
+## Saving Scenes
+
+### Saving to String
+
+Use `engine.scene.saveToString()` to serialize the current scene. This captures the complete scene structure—pages, blocks, and their properties—as a string you can store.
+
+```typescript highlight-save-scene
+// Save the scene to a string for persistence
+const sceneString = await engine.scene.saveToString();
+// eslint-disable-next-line no-console
+console.log('Scene saved successfully. String length:', sceneString.length);
+```
+
+The serialized string references external assets by URL rather than embedding them. For complete portability including assets, use `engine.scene.saveToArchive()`.
+
+## Loading Scenes
+
+### Loading from String
+
+Use `engine.scene.loadFromString()` to restore a scene from a saved string:
+
+```typescript highlight-load-scene
+// Demonstrate loading the scene from the saved string
+// This replaces the current scene with the saved version
+await engine.scene.loadFromString(sceneString);
+// eslint-disable-next-line no-console
+console.log('Scene loaded from saved string');
+
+// Zoom to show all loaded pages
+const loadedScene = engine.scene.get();
+if (loadedScene) {
+  await engine.scene.zoomToBlock(loadedScene, { padding: 50 });
+}
+```
+
+Loading a new scene replaces any existing scene. The engine only holds one active scene at a time.
+
+### Loading from URL
+
+Use `engine.scene.loadFromURL()` to load a scene directly from a remote location:
+
+```typescript
+await engine.scene.loadFromURL('https://example.com/design.scene');
+```
+
+## Troubleshooting
+
+### Blocks Not Visible
+
+Ensure blocks are attached to pages, and pages are attached to the scene. Orphaned blocks that aren't part of the scene hierarchy won't render.
+
+### Scene Not Loading
+
+Check that the scene URL or string is valid. If assets fail to load, consider using the `waitForResources` option to ensure everything loads before rendering.
+
+### Zoom Not Working
+
+Verify the scene has a valid camera. Some UI configurations may override programmatic zoom controls.
+
+## Scene Type
+
+Represents the scene and its global properties.
+
+This section describes the properties available for the **Scene Type** (`//ly.img.ubq/scene`) block type.
+
+| Property                       | Type     | Default      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| ------------------------------ | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `alwaysOnBottom`               | `Bool`   | `false`      | If true, this element's global sorting order is automatically adjusted to be lower than all other siblings.                                                                                                                                                                                                                                                                                                                                                               |
+| `alwaysOnTop`                  | `Bool`   | `false`      | If true, this element's global sorting order is automatically adjusted to be higher than all other siblings.                                                                                                                                                                                                                                                                                                                                                              |
+| `blend/mode`                   | `Enum`   | `"Normal"`   | The blend mode to use when compositing the block., Possible values: `"PassThrough"`, `"Normal"`, `"Darken"`, `"Multiply"`, `"ColorBurn"`, `"LinearBurn"`, `"DarkenColor"`, `"Lighten"`, `"Screen"`, `"ColorDodge"`, `"LinearDodge"`, `"LightenColor"`, `"Overlay"`, `"SoftLight"`, `"HardLight"`, `"VividLight"`, `"LinearLight"`, `"PinLight"`, `"HardMix"`, `"Difference"`, `"Exclusion"`, `"Subtract"`, `"Divide"`, `"Hue"`, `"Saturation"`, `"Color"`, `"Luminosity"` |
+| `clipped`                      | `Bool`   | `false`      | This component is used to identify elements whose contents and children should be clipped to their bounds.                                                                                                                                                                                                                                                                                                                                                                |
+| `contentFill/mode`             | `Enum`   | `"Cover"`    | Defines how content should be resized to fit its container (e.g., Crop, Cover, Contain)., Possible values: `"Crop"`, `"Cover"`, `"Contain"`                                                                                                                                                                                                                                                                                                                               |
+| `flip/horizontal`              | `Bool`   | `"-"`        | Whether the block is flipped horizontally.                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `flip/vertical`                | `Bool`   | `"-"`        | Whether the block is flipped vertically.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `globalBoundingBox/height`     | `Float`  | `"-"`        | The height of the block's axis-aligned bounding box in world coordinates., _(read-only)_                                                                                                                                                                                                                                                                                                                                                                                  |
+| `globalBoundingBox/width`      | `Float`  | `"-"`        | The width of the block's axis-aligned bounding box in world coordinates., _(read-only)_                                                                                                                                                                                                                                                                                                                                                                                   |
+| `globalBoundingBox/x`          | `Float`  | `"-"`        | The x-coordinate of the block's axis-aligned bounding box in world coordinates., _(read-only)_                                                                                                                                                                                                                                                                                                                                                                            |
+| `globalBoundingBox/y`          | `Float`  | `"-"`        | The y-coordinate of the block's axis-aligned bounding box in world coordinates., _(read-only)_                                                                                                                                                                                                                                                                                                                                                                            |
+| `height`                       | `Float`  | `0`          | The height of the block's frame.                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `height/mode`                  | `Enum`   | `"Auto"`     | A mode describing how the height dimension may be interpreted (Absolute, Percent, Auto)., Possible values: `"Absolute"`, `"Percent"`, `"Auto"`                                                                                                                                                                                                                                                                                                                            |
+| `highlightEnabled`             | `Bool`   | `true`       | Show highlighting when selected or hovered                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `lastFrame/height`             | `Float`  | `"-"`        | The height of the block's frame from the previous layout pass., _(read-only)_                                                                                                                                                                                                                                                                                                                                                                                             |
+| `lastFrame/width`              | `Float`  | `"-"`        | The width of the block's frame from the previous layout pass., _(read-only)_                                                                                                                                                                                                                                                                                                                                                                                              |
+| `lastFrame/x`                  | `Float`  | `"-"`        | The x-coordinate of the block's frame from the previous layout pass., _(read-only)_                                                                                                                                                                                                                                                                                                                                                                                       |
+| `lastFrame/y`                  | `Float`  | `"-"`        | The y-coordinate of the block's frame from the previous layout pass., _(read-only)_                                                                                                                                                                                                                                                                                                                                                                                       |
+| `placeholder/enabled`          | `Bool`   | `false`      | Whether the placeholder behavior is enabled or not.                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `playback/playing`             | `Bool`   | `false`      | A tag that can be set on elements for their playback time to be progressed.                                                                                                                                                                                                                                                                                                                                                                                               |
+| `playback/soloPlaybackEnabled` | `Bool`   | `false`      | A tag for blocks where playback should progress while the scene is paused.                                                                                                                                                                                                                                                                                                                                                                                                |
+| `playback/time`                | `Double` | `0`          | The current playback time of the block contents in seconds.                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `position/x`                   | `Float`  | `0`          | The x-coordinate of the block's origin.                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `position/x/mode`              | `Enum`   | `"Absolute"` | A mode describing how the x-position may be interpreted., Possible values: `"Absolute"`, `"Percent"`, `"Auto"`                                                                                                                                                                                                                                                                                                                                                            |
+| `position/y`                   | `Float`  | `0`          | The y-coordinate of the block's origin.                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `position/y/mode`              | `Enum`   | `"Absolute"` | A mode describing how the y-position may be interpreted., Possible values: `"Absolute"`, `"Percent"`, `"Auto"`                                                                                                                                                                                                                                                                                                                                                            |
+| `rotation`                     | `Float`  | `0`          | The rotation of the block in radians.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `scene/aspectRatioLock`        | `Bool`   | `true`       | Whether the ratio of the pageDimensions' width and height should remain constant when changing either dimension.                                                                                                                                                                                                                                                                                                                                                          |
+| `scene/designUnit`             | `Enum`   | `"Pixel"`    | The unit type in which the page values (size, distances, etc.) are defined., Possible values: `"Pixel"`, `"Millimeter"`, `"Inch"`                                                                                                                                                                                                                                                                                                                                         |
+| `scene/dpi`                    | `Float`  | `300`        | The DPI value to use when exporting and when converting between pixels and inches or millimeter units.                                                                                                                                                                                                                                                                                                                                                                    |
+| `scene/layout`                 | `Enum`   | `"Free"`     | A value describing how the scene's children are laid out., Possible values: `"Free"`, `"VerticalStack"`, `"HorizontalStack"`, `"DepthStack"`                                                                                                                                                                                                                                                                                                                              |
+| `scene/mode`                   | `Enum`   | `"Video"`    | The mode of this scene and all elements inside of it., _(read-only)_, Possible values: `"Design"`, `"Video"`                                                                                                                                                                                                                                                                                                                                                              |
+| `scene/pageDimensions/height`  | `Float`  | `1`          | The height of all pages in this scene.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `scene/pageDimensions/width`   | `Float`  | `1`          | The width of all pages in this scene.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `scene/pageFormatId`           | `String` | `""`         | The identifier of the page format configuration that was most recently selected for the pages in this scene.                                                                                                                                                                                                                                                                                                                                                              |
+| `scene/pixelScaleFactor`       | `Float`  | `1`          | A scale factor that is applied to the final export resolution if the design unit is Pixel.                                                                                                                                                                                                                                                                                                                                                                                |
+| `selected`                     | `Bool`   | `false`      | Indicates if the block is currently selected.                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `transformLocked`              | `Bool`   | `false`      | DesignBlocks with this tag can't be transformed (moved, rotated, scaled, cropped, or flipped).                                                                                                                                                                                                                                                                                                                                                                            |
+| `visible`                      | `Bool`   | `true`       | If the block is visible in the editor.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `width`                        | `Float`  | `0`          | The width of the block's frame.                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `width/mode`                   | `Enum`   | `"Auto"`     | A mode describing how the width dimension may be interpreted (Absolute, Percent, Auto)., Possible values: `"Absolute"`, `"Percent"`, `"Auto"`                                                                                                                                                                                                                                                                                                                             |
+
+---
+
+## 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/concepts/templating.md

@@ -0,0 +1,194 @@
+> 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) > [Templating](./concepts/templating.md)
+
+---
+
+Templates transform static designs into dynamic, data-driven content. They combine reusable layouts with variable text and placeholder media, enabling personalization at scale.
+
+![Templating example showing a personalized postcard design](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-concepts-templating-browser)
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-concepts-templating-browser)
+> - [Live demo](https://img.ly/docs/cesdk/examples/guides-concepts-templating-browser/)
+
+A template is a regular CE.SDK scene that contains **variable tokens** in text and **placeholder blocks** for media. When you load a template, you can populate the variables with data and swap placeholder content—producing personalized designs without modifying the underlying layout.
+
+```typescript file=@cesdk_web_examples/guides-concepts-templating-browser/browser.ts reference-only
+import type { EditorPlugin, EditorPluginContext } from '@cesdk/cesdk-js';
+
+import { DesignEditorConfig } from './design-editor/plugin';
+import packageJson from './package.json';
+
+/**
+ * CE.SDK Plugin: Templating Concepts
+ *
+ * Demonstrates the core template concepts in CE.SDK:
+ * - Loading a template from URL
+ * - Discovering and setting variables
+ * - Discovering placeholders
+ */
+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;
+
+    // Load a postcard template from URL
+    // Templates are scenes containing variable tokens and placeholder blocks
+    const templateUrl =
+      'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_postcard_1.scene';
+    await engine.scene.loadFromURL(templateUrl);
+
+    // Zoom to show the full page in the viewport
+    const page = engine.scene.getCurrentPage();
+    if (page) {
+      await engine.scene.zoomToBlock(page, { padding: 40 });
+    }
+
+    // Discover what variables this template expects
+    // Variables are named slots that can be populated with data
+    const variableNames = engine.variable.findAll();
+    // eslint-disable-next-line no-console
+    console.log('Template variables:', variableNames);
+
+    // Set variable values to personalize the template
+    // These values replace {{variableName}} tokens in text blocks
+    engine.variable.setString('Name', 'Jane');
+    engine.variable.setString('Greeting', 'Wish you were here!');
+    // eslint-disable-next-line no-console
+    console.log('Variables set successfully.');
+
+    // Discover placeholder blocks in the template
+    // Placeholders mark content slots for user or automation replacement
+    const placeholders = engine.block.findAllPlaceholders();
+    // eslint-disable-next-line no-console
+    console.log('Template placeholders:', placeholders.length);
+
+    // eslint-disable-next-line no-console
+    console.log('Templating guide completed successfully.');
+  }
+}
+
+export default Example;
+```
+
+This guide explains the core concepts. For implementation details, see the guides linked in each section.
+
+## What Makes a Template
+
+Any CE.SDK scene can become a template by adding dynamic elements:
+
+| Element                 | Purpose                   | Example                      |
+| ----------------------- | ------------------------- | ---------------------------- |
+| **Variables**           | Dynamic text replacement  | `Hello, {{firstName}}!`      |
+| **Placeholders**        | Swappable media slots     | Profile photo, product image |
+| **Editing Constraints** | Protected design elements | Locked logo, fixed layout    |
+
+Templates separate **design** (created once by designers) from **content** (populated at runtime with data). This enables workflows like batch generation, form-based customization, and user personalization.
+
+## Variables
+
+Variables enable dynamic text without modifying the design structure. Text blocks contain `{{variableName}}` tokens that CE.SDK resolves at render time.
+
+```typescript highlight-set-variables
+// Set variable values to personalize the template
+// These values replace {{variableName}} tokens in text blocks
+engine.variable.setString('Name', 'Jane');
+engine.variable.setString('Greeting', 'Wish you were here!');
+// eslint-disable-next-line no-console
+console.log('Variables set successfully.');
+```
+
+**How variables work:**
+
+- Define variables with `engine.variable.setString('name', 'value')`
+- Reference them in text: `Welcome, {{name}}!`
+- CE.SDK automatically updates all text blocks using that variable
+- Tokens are case-sensitive; unmatched tokens render as literal text
+
+Variables are scene-scoped and persist when you save the template. Use `engine.variable.findAll()` to discover what variables a template expects.
+
+[Learn more about text variables →](./create-templates/add-dynamic-content/text-variables.md)
+
+## Placeholders
+
+Placeholders mark blocks as content slots that users or automation can replace. When you enable placeholder behavior on an image block, it displays an overlay pattern and replacement button in the editor.
+
+**How placeholders work:**
+
+- Enable with `engine.block.setPlaceholderEnabled(block, true)`
+- Add visual UI with `engine.block.setPlaceholderBehaviorEnabled(fill, true)`
+- Users in Adopter mode can select and replace placeholder content
+- Other design elements remain locked
+
+Use `engine.block.findAllPlaceholders()` to discover all placeholder blocks in a loaded template.
+
+[Learn more about placeholders →](./create-templates/add-dynamic-content/placeholders.md)
+
+## Template Workflows
+
+Templates support several common workflows:
+
+### Form-Based Customization
+
+Load a template, present a form for variable values, and let users customize text while the design stays consistent. The editor UI handles placeholder replacement through drag-and-drop.
+
+### Batch Generation
+
+Load a template programmatically, iterate through data records, set variables for each record, and export personalized designs. This powers use cases like certificates, badges, and personalized marketing.
+
+### Design Systems
+
+Create template libraries where designers maintain approved layouts and end users customize within defined boundaries using variables and placeholders.
+
+## Loading and Applying Templates
+
+CE.SDK provides two approaches for working with templates:
+
+**Load a template** with `engine.scene.loadFromURL()` to replace the current scene entirely, including page dimensions:
+
+```typescript highlight-load-template
+// Load a postcard template from URL
+// Templates are scenes containing variable tokens and placeholder blocks
+const templateUrl =
+  'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_postcard_1.scene';
+await engine.scene.loadFromURL(templateUrl);
+
+// Zoom to show the full page in the viewport
+const page = engine.scene.getCurrentPage();
+if (page) {
+  await engine.scene.zoomToBlock(page, { padding: 40 });
+}
+```
+
+**Apply a template** with `engine.scene.applyTemplateFromURL()` to merge template content into an existing scene while preserving current page dimensions.
+
+[Learn more about importing templates →](./create-templates/import.md)
+
+## Creating Templates
+
+Build templates by adding variable tokens to text blocks and configuring placeholder behavior on media blocks. Save with `engine.scene.saveToString()` or `engine.scene.saveToArchive()`.
+
+[Learn more about creating templates →](./create-templates/from-scratch.md)
+
+---
+
+## 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