@imgly/codesign-mcp 0.1.0

package/assets/docs/guide/import-media/default-assets.md

@@ -0,0 +1,381 @@
+> 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) > [Import Media Assets](./import-media.md) > [Using Default Assets](./import-media/default-assets.md)
+
+---
+
+```typescript file=@cesdk_web_examples/guides-import-media-default-assets-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: Using Default Assets Guide
+ *
+ * Demonstrates loading all asset sources from IMG.LY's CDN using
+ * addLocalAssetSourceFromJSONURI and creating a scene with
+ * a star shape, sticker, and image.
+ */
+class Example implements EditorPlugin {
+  name = packageJson.name;
+
+  version = packageJson.version;
+
+  async initialize({ cesdk, engine }: EditorPluginContext): Promise<void> {
+    if (!cesdk) {
+      throw new Error('CE.SDK instance is required for this plugin');
+    }
+
+    await cesdk.addPlugin(new DesignEditorConfig());
+
+    // Versioned CDN URLs using the SDK package (recommended)
+    // For production, self-host these assets - see the Serve Assets guide
+    const PACKAGE_BASE = `https://cdn.img.ly/packages/imgly/cesdk-js/${cesdk.version}/assets`;
+    const DEFAULT_ASSETS_URL = `${PACKAGE_BASE}/v4/`;
+    const DEMO_ASSETS_URL = `${PACKAGE_BASE}/demo/v3/`;
+
+    // Load default asset sources (core editor components)
+    await engine.asset.addLocalAssetSourceFromJSONURI(
+      `${DEFAULT_ASSETS_URL}ly.img.sticker/content.json`
+    );
+    await engine.asset.addLocalAssetSourceFromJSONURI(
+      `${DEFAULT_ASSETS_URL}ly.img.vector.shape/content.json`
+    );
+    await engine.asset.addLocalAssetSourceFromJSONURI(
+      `${DEFAULT_ASSETS_URL}ly.img.color.palette/content.json`
+    );
+    await engine.asset.addLocalAssetSourceFromJSONURI(
+      `${DEFAULT_ASSETS_URL}ly.img.filter/content.json`
+    );
+    await engine.asset.addLocalAssetSourceFromJSONURI(
+      `${DEFAULT_ASSETS_URL}ly.img.effect/content.json`
+    );
+    await engine.asset.addLocalAssetSourceFromJSONURI(
+      `${DEFAULT_ASSETS_URL}ly.img.blur/content.json`
+    );
+    await engine.asset.addLocalAssetSourceFromJSONURI(
+      `${DEFAULT_ASSETS_URL}ly.img.typeface/content.json`
+    );
+    await engine.asset.addLocalAssetSourceFromJSONURI(
+      `${DEFAULT_ASSETS_URL}ly.img.crop.presets/content.json`
+    );
+    await engine.asset.addLocalAssetSourceFromJSONURI(
+      `${DEFAULT_ASSETS_URL}ly.img.page.presets/content.json`
+    );
+
+    // Load demo asset sources (sample content for testing)
+    await engine.asset.addLocalAssetSourceFromJSONURI(
+      `${DEMO_ASSETS_URL}ly.img.image/content.json`
+    );
+    await engine.asset.addLocalAssetSourceFromJSONURI(
+      `${DEMO_ASSETS_URL}ly.img.video/content.json`
+    );
+    await engine.asset.addLocalAssetSourceFromJSONURI(
+      `${DEMO_ASSETS_URL}ly.img.audio/content.json`
+    );
+    await engine.asset.addLocalAssetSourceFromJSONURI(
+      `${DEMO_ASSETS_URL}ly.img.templates/content.json`
+    );
+    await engine.asset.addLocalAssetSourceFromJSONURI(
+      `${DEMO_ASSETS_URL}ly.img.text.components/content.json`
+    );
+
+    // Update asset library entries to show the loaded sources in the UI
+    cesdk.ui.updateAssetLibraryEntry('ly.img.sticker', {
+      sourceIds: ({ currentIds }) => [
+        ...new Set([...currentIds, 'ly.img.sticker'])
+      ]
+    });
+    cesdk.ui.updateAssetLibraryEntry('ly.img.vector.shape', {
+      sourceIds: ({ currentIds }) => [
+        ...new Set([...currentIds, 'ly.img.vector.shape'])
+      ]
+    });
+    cesdk.ui.updateAssetLibraryEntry('ly.img.color.palette', {
+      sourceIds: ({ currentIds }) => [
+        ...new Set([...currentIds, 'ly.img.color.palette'])
+      ]
+    });
+    cesdk.ui.updateAssetLibraryEntry('ly.img.filter', {
+      sourceIds: ({ currentIds }) => [
+        ...new Set([...currentIds, 'ly.img.filter'])
+      ]
+    });
+    cesdk.ui.updateAssetLibraryEntry('ly.img.effect', {
+      sourceIds: ({ currentIds }) => [
+        ...new Set([...currentIds, 'ly.img.effect'])
+      ]
+    });
+    cesdk.ui.updateAssetLibraryEntry('ly.img.blur', {
+      sourceIds: ({ currentIds }) => [
+        ...new Set([...currentIds, 'ly.img.blur'])
+      ]
+    });
+    cesdk.ui.updateAssetLibraryEntry('ly.img.typeface', {
+      sourceIds: ({ currentIds }) => [
+        ...new Set([...currentIds, 'ly.img.typeface'])
+      ]
+    });
+    cesdk.ui.updateAssetLibraryEntry('ly.img.crop.presets', {
+      sourceIds: ({ currentIds }) => [
+        ...new Set([...currentIds, 'ly.img.crop.presets'])
+      ]
+    });
+    cesdk.ui.updateAssetLibraryEntry('ly.img.page.presets', {
+      sourceIds: ({ currentIds }) => [
+        ...new Set([...currentIds, 'ly.img.page.presets'])
+      ]
+    });
+    cesdk.ui.updateAssetLibraryEntry('ly.img.image', {
+      sourceIds: ({ currentIds }) => [
+        ...new Set([...currentIds, 'ly.img.image'])
+      ]
+    });
+    cesdk.ui.updateAssetLibraryEntry('ly.img.video', {
+      sourceIds: ({ currentIds }) => [
+        ...new Set([...currentIds, 'ly.img.video'])
+      ]
+    });
+    cesdk.ui.updateAssetLibraryEntry('ly.img.audio', {
+      sourceIds: ({ currentIds }) => [
+        ...new Set([...currentIds, 'ly.img.audio'])
+      ]
+    });
+    cesdk.ui.updateAssetLibraryEntry('ly.img.templates', {
+      sourceIds: ({ currentIds }) => [
+        ...new Set([...currentIds, 'ly.img.templates'])
+      ]
+    });
+    cesdk.ui.updateAssetLibraryEntry('ly.img.text.components', {
+      sourceIds: ({ currentIds }) => [
+        ...new Set([...currentIds, 'ly.img.text.components'])
+      ]
+    });
+
+    // Create the design scene
+    await cesdk.actions.run('scene.create', {
+      page: {
+        sourceId: 'ly.img.page.presets',
+        assetId: 'ly.img.page.presets.print.iso.a6.landscape'
+      }
+    });
+
+    // Get the page to add content to
+    const pages = engine.block.findByType('page');
+    const page = pages[0];
+    if (page == null) return;
+
+    const pageWidth = engine.block.getWidth(page);
+    const pageHeight = engine.block.getHeight(page);
+
+    // Define the three assets to add: star shape, sticker, and image
+    const assetsToAdd = [
+      {
+        sourceId: 'ly.img.vector.shape',
+        assetId: '//ly.img.ubq/shapes/star/filled'
+      },
+      {
+        sourceId: 'ly.img.sticker',
+        assetId: '//ly.img.cesdk.stickers.emoticons/alien'
+      },
+      {
+        sourceId: 'ly.img.image',
+        assetId: 'ly.img.cesdk.images.samples/sample.1'
+      }
+    ];
+
+    // Calculate layout for 3 centered blocks
+    const blockSize = Math.min(pageWidth, pageHeight) * 0.2;
+    const spacing = blockSize * 0.3;
+    const totalWidth =
+      assetsToAdd.length * blockSize + (assetsToAdd.length - 1) * spacing;
+    const startX = (pageWidth - totalWidth) / 2;
+    const centerY = (pageHeight - blockSize) / 2;
+
+    // Create and position each block
+    for (let i = 0; i < assetsToAdd.length; i++) {
+      const { sourceId, assetId } = assetsToAdd[i];
+      const asset = await engine.asset.fetchAsset(sourceId, assetId);
+
+      if (asset != null) {
+        const block = await engine.asset.apply(sourceId, asset);
+
+        if (block != null) {
+          engine.block.setWidth(block, blockSize);
+          engine.block.setHeight(block, blockSize);
+          engine.block.setPositionX(block, startX + i * (blockSize + spacing));
+          engine.block.setPositionY(block, centerY);
+        }
+      }
+    }
+
+    // Clear selection for cleaner visual
+    for (const block of engine.block.findAllSelected()) {
+      engine.block.setSelected(block, false);
+    }
+
+    // Open the Elements panel to showcase all loaded asset sources
+    cesdk.ui.openPanel('//ly.img.panel/assetLibrary', {
+      payload: {
+        entries: ['ly.img.image', 'ly.img.vector.shape', 'ly.img.sticker']
+      }
+    });
+  }
+}
+
+export default Example;
+```
+
+Load all asset sources from IMG.LY's CDN to populate your CE.SDK editor with shapes, stickers, filters, effects, fonts, images, and other media using the Asset API.
+
+![Using Default Assets example showing the CE.SDK editor with a star shape, sticker, and image centered on the canvas](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-import-media-default-assets-browser)
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-import-media-default-assets-browser)
+> - [Live demo](https://img.ly/docs/cesdk/examples/guides-import-media-default-assets-browser/)
+
+CE.SDK provides built-in asset sources for shapes, stickers, filters, effects, fonts, and sample media. This guide demonstrates loading all available asset sources from IMG.LY's CDN and applying them to create a scene with a star shape, a sticker, and an image.
+
+> **Production Deployment:** The IMG.LY CDN is for development and prototyping only. For production, download and self-host assets from your own server. See the [Serve Assets](./serve-assets.md) guide for instructions.
+
+## What Are Default and Demo Assets?
+
+IMG.LY provides two categories of asset sources hosted on the IMG.LY CDN for development and prototyping:
+
+**Default Assets** are core editor components:
+
+| Source ID              | Description                     |
+| ---------------------- | ------------------------------- |
+| `ly.img.sticker`       | Emojis, emoticons, decorations  |
+| `ly.img.vector.shape`  | Shapes: stars, arrows, polygons |
+| `ly.img.color.palette` | Default color palette           |
+| `ly.img.filter`        | Color filters (LUT and duotone) |
+| `ly.img.effect`        | Visual effects                  |
+| `ly.img.blur`          | Blur effects                    |
+| `ly.img.typeface`      | Font families                   |
+| `ly.img.crop.presets`  | Crop presets                    |
+| `ly.img.page.presets`  | Page size presets               |
+
+**Demo Assets** are sample content for development:
+
+| Source ID                | Description                |
+| ------------------------ | -------------------------- |
+| `ly.img.image`           | Sample images              |
+| `ly.img.video`           | Sample videos              |
+| `ly.img.audio`           | Sample audio tracks        |
+| `ly.img.templates`       | Design and video templates |
+| `ly.img.text.components` | Text component presets     |
+
+## Loading Assets from URL
+
+Use `addLocalAssetSourceFromJSONURI()` to load an asset source directly from a JSON URL:
+
+```typescript
+const baseURL = `https://cdn.img.ly/packages/imgly/cesdk-js/${cesdk.version}/assets/v4/`;
+await engine.asset.addLocalAssetSourceFromJSONURI(
+  `${baseURL}ly.img.vector.shape/content.json`
+);
+```
+
+## Versioned CDN URLs
+
+Use the SDK version to construct versioned CDN URLs. This ensures assets are compatible with your SDK version. For production deployments, see the [Serve Assets](./serve-assets.md) guide to self-host assets.
+
+```typescript highlight-cdn-urls
+// Versioned CDN URLs using the SDK package (recommended)
+// For production, self-host these assets - see the Serve Assets guide
+const PACKAGE_BASE = `https://cdn.img.ly/packages/imgly/cesdk-js/${cesdk.version}/assets`;
+const DEFAULT_ASSETS_URL = `${PACKAGE_BASE}/v4/`;
+const DEMO_ASSETS_URL = `${PACKAGE_BASE}/demo/v3/`;
+```
+
+## Loading Default Asset Sources
+
+Load a default asset source from the CDN. Repeat this pattern for each source you need:
+
+```typescript highlight-load-default-assets
+// Load default asset sources (core editor components)
+await engine.asset.addLocalAssetSourceFromJSONURI(
+  `${DEFAULT_ASSETS_URL}ly.img.sticker/content.json`
+);
+```
+
+## Loading Demo Asset Sources
+
+Load a demo asset source from the CDN. Repeat this pattern for each source you need:
+
+```typescript highlight-load-demo-assets
+// Load demo asset sources (sample content for testing)
+await engine.asset.addLocalAssetSourceFromJSONURI(
+  `${DEMO_ASSETS_URL}ly.img.image/content.json`
+);
+```
+
+## Updating the Asset Library
+
+After loading asset sources, update the asset library entries to display them in the UI. Repeat this pattern for each source:
+
+```typescript highlight-update-library
+// Update asset library entries to show the loaded sources in the UI
+cesdk.ui.updateAssetLibraryEntry('ly.img.sticker', {
+  sourceIds: ({ currentIds }) => [...new Set([...currentIds, 'ly.img.sticker'])]
+});
+```
+
+## Filtering Assets with Matcher
+
+Use the `matcher` option to load only specific assets from a source:
+
+```typescript
+const baseURL = `https://cdn.img.ly/packages/imgly/cesdk-js/${cesdk.version}/assets/v4/`;
+
+// Load only star and arrow shapes
+await engine.asset.addLocalAssetSourceFromJSONURI(
+  `${baseURL}ly.img.vector.shape/content.json`,
+  { matcher: ['*star*', '*arrow*'] }
+);
+
+// Load only emoji stickers
+await engine.asset.addLocalAssetSourceFromJSONURI(
+  `${baseURL}ly.img.sticker/content.json`,
+  { matcher: ['*emoji*'] }
+);
+```
+
+An asset is included if it matches ANY pattern in the array. Patterns support `*` wildcards.
+
+## API Reference
+
+| Method                                                              | Description                          |
+| ------------------------------------------------------------------- | ------------------------------------ |
+| `engine.asset.addLocalAssetSourceFromJSONURI(contentURI, options?)` | Load an asset source from a JSON URL |
+
+**Parameters for `addLocalAssetSourceFromJSONURI`:**
+
+| Parameter         | Type       | Description                                 |
+| ----------------- | ---------- | ------------------------------------------- |
+| `contentURI`      | `string`   | Full URL to the content.json file           |
+| `options.matcher` | `string[]` | Optional wildcard patterns to filter assets |
+
+**Returns:** `Promise<string>` — The asset source ID from the JSON
+
+## Next Steps
+
+- [Serve Assets](./serve-assets.md) — Self-host assets for production deployments
+- [Customize Asset Library](./import-media/asset-panel/customize.md) — Configure the asset library UI and entries
+- [Asset Library Basics](./import-media/asset-panel/basics.md) — Understand asset library structure and concepts
+- [Import From Remote Source](./import-media/from-remote-source.md) — Load assets from external URLs
+
+---
+
+## 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