@cesdk/cesdk-js 1.62.0-nightly.20251010 → 1.63.0-nightly.20251014

package/index.d.ts

@@ -46,12 +46,11 @@ import { BlurTypeShorthand } from '@cesdk/engine';
 import { BooleanOperation } from '@cesdk/engine';
 import { Buffer } from '@cesdk/engine';
 import { Canvas } from '@cesdk/engine';
-import { _ChannelSync } from '@cesdk/engine';
 import { checkVideoExportSupport } from '@cesdk/engine';
 import { checkVideoSupport } from '@cesdk/engine';
 import { CMYK } from '@cesdk/engine';
 import { CMYKColor } from '@cesdk/engine';
-import { Color } from '@cesdk/engine';
+import type { Color } from '@cesdk/engine';
 import { ColorSpace } from '@cesdk/engine';
 import { CompleteAssetResult } from '@cesdk/engine';
 import { ContentFillMode } from '@cesdk/engine';
@@ -90,7 +89,6 @@ import { GradientstopRGBA } from '@cesdk/engine';
 import { HexColorString } from '@cesdk/engine';
 import { HistoryId } from '@cesdk/engine';
 import { HorizontalBlockAlignment } from '@cesdk/engine';
-import { HorizontalTextAlignment } from '@cesdk/engine';
 import { HTMLCreativeEngineCanvasElement } from '@cesdk/engine';
 import type { i18n } from 'i18next';
 import { ImageMimeType } from '@cesdk/engine';
@@ -102,13 +100,10 @@ import { ObjectType } from '@cesdk/engine';
 import { ObjectTypeLonghand } from '@cesdk/engine';
 import { ObjectTypeShorthand } from '@cesdk/engine';
 import { OffscreenCanvas as OffscreenCanvas_2 } from '@cesdk/engine';
-import { PageDuration } from '@cesdk/engine';
 import { PaletteColor } from '@cesdk/engine';
 import { PositionMode } from '@cesdk/engine';
 import { PropertyType } from '@cesdk/engine';
 import { Range as Range_2 } from '@cesdk/engine';
-import { _ReadOnlyChannelSync } from '@cesdk/engine';
-import { _ReadWriteChannelSync } from '@cesdk/engine';
 import { RGBA } from '@cesdk/engine';
 import { RGBAColor } from '@cesdk/engine';
 import { RGBColor } from '@cesdk/engine';
@@ -132,7 +127,6 @@ import { Size2 } from '@cesdk/engine';
 import { SizeMode } from '@cesdk/engine';
 import { SortingOrder } from '@cesdk/engine';
 import { Source } from '@cesdk/engine';
-import { _Source } from '@cesdk/engine';
 import { SplitOptions } from '@cesdk/engine';
 import { SpotColor } from '@cesdk/engine';
 import { StrokeCornerGeometry } from '@cesdk/engine';
@@ -147,9 +141,7 @@ import { TransientResource } from '@cesdk/engine';
 import { Typeface } from '@cesdk/engine';
 import { TypefaceDefinition } from '@cesdk/engine';
 import { VariableAPI } from '@cesdk/engine';
-import { Vec2 } from '@cesdk/engine';
 import { VerticalBlockAlignment } from '@cesdk/engine';
-import { VerticalTextAlignment } from '@cesdk/engine';
 import { VideoExportOptions } from '@cesdk/engine';
 import { VideoMimeType } from '@cesdk/engine';
 import { XYWH } from '@cesdk/engine';
@@ -315,6 +307,24 @@ export { AssetColorProperty }
 
 export { AssetDefinition }
 
+/**
+ * @public
+ * Asset library entry IDs that can be used with asset library APIs.
+ * Includes built-in entry IDs registered by the SDK, and allows custom entry IDs.
+ */
+export declare type AssetEntryId = 'ly.img.colors' | 'ly.img.typefaces' | 'ly.img.pagePresets' | 'ly.img.cropPresets' | 'ly.img.library.captionPresets' | 'ly.img.animations' | 'ly.img.textAnimations' | (string & {});
+
+/**
+ * @public
+ * Context provided to the sourceIds callback function.
+ * - `cesdk`: The CreativeEditorSDK instance.
+ * - `engine`: The CreativeEngine instance.
+ */
+declare interface AssetEntrySourceIdsContext {
+    cesdk: CreativeEditorSDK;
+    engine: CreativeEngine_2;
+}
+
 export { AssetEnumProperty }
 
 export { AssetFixedAspectRatio }
@@ -364,7 +374,7 @@ export declare interface AssetLibraryEntry extends AssetLibraryEntryData, AssetL
  * @public
  * Interface representing the data configuration for an asset library entry.
  * - `id`: The unique identifier for the asset library entry.
- * - `sourceIds`: An array of source IDs associated with the asset library entry.
+ * - `sourceIds`: An array of source IDs associated with the asset library entry, or a function that returns an array of source IDs.
  * - `sceneMode`: Optional configuration for the scene mode, which can be a `SceneMode`, 'All', or a function returning a `SceneMode` or 'All'.
  * - `excludeGroups`: Optional array of group IDs to exclude from the asset library entry.
  * - `includeGroups`: Optional array of group IDs to include in the asset library entry.
@@ -374,7 +384,7 @@ export declare interface AssetLibraryEntry extends AssetLibraryEntryData, AssetL
  */
 declare interface AssetLibraryEntryData {
     id: string;
-    sourceIds: string[];
+    sourceIds: string[] | ((context: AssetEntrySourceIdsContext) => string[]);
     /**
      * Marks for what scene mode this entry is fitting. Not setting this
      * will make the entry available for all scene modes.
@@ -2489,6 +2499,27 @@ declare class CreativeEditorSDK {
 
 
 
+    /**
+     * Registers a callback function to be executed when resetEditor is called.
+     *
+     * @param callback - Function to be called with the cesdk instance when reset occurs
+     * @returns Function to remove the callback from the registry
+     *
+     * @example
+     * ```typescript
+     * const removeCallback = cesdk.onReset((cesdk) => {
+     *   console.log('Editor is being reset');
+     *   // Custom cleanup/reinitialization logic
+     * });
+     *
+     * // Later, to remove the callback:
+     * removeCallback();
+     * ```
+     *
+     * @category Configuration
+     * @public
+     */
+    onReset(callback: (cesdk: CreativeEditorSDK) => void): () => void;
     /**
      * Convenience function to register a set of our default asset sources.
      *
@@ -2615,6 +2646,23 @@ declare class CreativeEditorSDK {
      * ```
      */
     getBaseURL(): string;
+    /**
+     * Resets the editor to a clean state by disabling all features, clearing UI configurations,
+     * and removing asset sources.
+     *
+     * @example
+     * ```typescript
+     * // Reset the editor to clean state
+     * cesdk.resetEditor();
+     *
+     * // Reconfigure as needed
+     * cesdk.feature.enable('ly.img.navigationBar', true);
+     * cesdk.addDefaultAssetSources();
+     * ```
+     *
+     * @category Configuration
+     */
+    resetEditor(): void;
     /**
      * Save and return a scene as a base64 encoded string.
      *
@@ -4480,13 +4528,214 @@ export declare interface UserInterface {
     hide?: boolean;
     smallViewportOptimization?: boolean;
     /**
-     * @deprecated The configuration options `ui.colorPalette` has been deprecated. Please use `ui.colorLibraries` and asset sources instead.
+     * @deprecated Add a local asset source using `cesdk.engine.asset.addLocalSource()` and populate it with color assets,
+     * then use `cesdk.ui.updateAssetLibraryEntry('ly.img.colors', { sourceIds: [...] })` to configure which sources to display.
+     *
+     * @example
+     * ```typescript
+     * // Before (deprecated):
+     * const config = {
+     *   ui: {
+     *     colorPalette: ['#FF0000', '#00FF00', '#0000FF']
+     *   }
+     * };
+     *
+     * // After (recommended):
+     * // Add a local source for custom colors
+     * engine.asset.addLocalSource('my.custom.colors');
+     * engine.asset.addAssetToSource('my.custom.colors', {
+     *   id: 'red',
+     *   label: { en: 'Red' },
+     *   payload: {
+     *     color: {
+     *       colorSpace: 'sRGB',
+     *       r: 1.0,
+     *       g: 0.0,
+     *       b: 0.0,
+     *       a: 1.0
+     *     }
+     *   }
+     * });
+     * // ... add more colors
+     *
+     * // Update the asset library entry to use your custom source
+     * cesdk.ui.updateAssetLibraryEntry('ly.img.colors', {
+     *   sourceIds: ['ly.img.colors.documentColors', 'my.custom.colors']
+     * });
+     * ```
      */
     colorPalette?: PaletteColor[];
+    /**
+     * @deprecated Add asset sources using `cesdk.engine.asset.addAssetSource()` or `cesdk.engine.asset.addLocalSource()`,
+     * then use `cesdk.ui.updateAssetLibraryEntry('ly.img.colors', { sourceIds: [...] })` to configure which sources to display.
+     *
+     * @example
+     * ```typescript
+     * // Before (deprecated):
+     * const config = {
+     *   ui: {
+     *     colorLibraries: ['ly.img.colors.defaultPalette', 'my.custom.colors']
+     *   }
+     * };
+     *
+     * // After (recommended):
+     * // Add a local source for custom colors
+     * engine.asset.addLocalSource('my.custom.colors');
+     * // Add color assets to the source
+     * engine.asset.addAssetToSource('my.custom.colors', {
+     *   id: 'custom-color-1',
+     *   payload: { color: { colorSpace: 'sRGB', r: 1.0, g: 0.0, b: 0.0 } }
+     * });
+     *
+     * // Update the library entry to use your sources
+     * cesdk.ui.updateAssetLibraryEntry('ly.img.colors', {
+     *   sourceIds: ['ly.img.colors.defaultPalette', 'my.custom.colors']
+     * });
+     * ```
+     */
     colorLibraries?: string[];
+    /**
+     * @deprecated Add asset sources using `cesdk.engine.asset.addAssetSource()` or `cesdk.engine.asset.addLocalSource()`,
+     * then use `cesdk.ui.updateAssetLibraryEntry('ly.img.typefaces', { sourceIds: [...] })` to configure which sources to display.
+     *
+     * @example
+     * ```typescript
+     * // Before (deprecated):
+     * const config = {
+     *   ui: {
+     *     typefaceLibraries: ['ly.img.typeface', 'my.custom.fonts']
+     *   }
+     * };
+     *
+     * // After (recommended):
+     * // Add a local source for custom typefaces
+     * engine.asset.addLocalSource('my.custom.fonts');
+     * // Add typeface assets to the source
+     * engine.asset.addAssetToSource('my.custom.fonts', {
+     *   id: 'custom-font-1',
+     *   meta: { uri: 'https://example.com/font.ttf' }
+     * });
+     *
+     * // Update the library entry to use your sources
+     * cesdk.ui.updateAssetLibraryEntry('ly.img.typefaces', {
+     *   sourceIds: ['ly.img.typeface', 'my.custom.fonts']
+     * });
+     * ```
+     */
     typefaceLibraries?: string[];
+    /**
+     * @deprecated Add asset sources using `cesdk.engine.asset.addAssetSource()` or `cesdk.engine.asset.addLocalSource()`,
+     * then use `cesdk.ui.updateAssetLibraryEntry('ly.img.pagePresets', { sourceIds: ... })` to configure which sources to display.
+     *
+     * For dynamic source IDs, use a callback function with the new API: `{ sourceIds: ({ engine }) => [...] }`
+     *
+     * @example
+     * ```typescript
+     * // Before (deprecated):
+     * const config = {
+     *   ui: {
+     *     pagePresetsLibraries: (engine) => {
+     *       const sceneMode = engine.scene.getMode();
+     *       return sceneMode === 'Video'
+     *         ? ['ly.img.page.presets.video']
+     *         : ['ly.img.page.presets'];
+     *     }
+     *   }
+     * };
+     *
+     * // After (recommended):
+     * // Add a local source for custom page presets
+     * engine.asset.addLocalSource('my.custom.pagePresets');
+     * // Add page preset assets to the source
+     * engine.asset.addAssetToSource('my.custom.pagePresets', {
+     *   id: 'custom-preset-1',
+     *   payload: { transformPreset: { type: 'FixedSize', width: 800, height: 600 } }
+     * });
+     *
+     * // Update the library entry with dynamic sourceIds
+     * cesdk.ui.updateAssetLibraryEntry('ly.img.pagePresets', {
+     *   sourceIds: ({ engine }) => {
+     *     const sceneMode = engine.scene.getMode();
+     *     return sceneMode === 'Video'
+     *       ? ['ly.img.page.presets.video', 'my.custom.pagePresets']
+     *       : ['ly.img.page.presets', 'my.custom.pagePresets'];
+     *   }
+     * });
+     * ```
+     */
     pagePresetsLibraries?: string[] | ((engine: CreativeEngine_2) => string[]);
+    /**
+     * @deprecated Add asset sources using `cesdk.engine.asset.addAssetSource()` or `cesdk.engine.asset.addLocalSource()`,
+     * then use `cesdk.ui.updateAssetLibraryEntry('ly.img.cropPresets', { sourceIds: ... })` to configure which sources to display.
+     *
+     * For dynamic source IDs, use a callback function with the new API: `{ sourceIds: ({ engine }) => [...] }`
+     *
+     * @example
+     * ```typescript
+     * // Before (deprecated):
+     * const config = {
+     *   ui: {
+     *     cropPresetsLibraries: ['ly.img.crop.presets']
+     *   }
+     * };
+     *
+     * // After (recommended):
+     * // Add a local source for custom crop presets
+     * engine.asset.addLocalSource('my.custom.cropPresets');
+     * // Add crop preset assets to the source
+     * engine.asset.addAssetToSource('my.custom.cropPresets', {
+     *   id: 'custom-crop-1',
+     *   payload: { transformPreset: { type: 'FixedAspectRatio', width: 16, height: 9 } }
+     * });
+     *
+     * // Update the library entry to use your sources
+     * cesdk.ui.updateAssetLibraryEntry('ly.img.cropPresets', {
+     *   sourceIds: ['ly.img.crop.presets', 'my.custom.cropPresets']
+     * });
+     * ```
+     */
     cropPresetsLibraries?: string[] | ((engine: CreativeEngine_2) => string[]);
+    /**
+     * @deprecated Add a local asset source using `cesdk.engine.asset.addLocalSource()` and populate it with page format assets,
+     * then use `cesdk.ui.updateAssetLibraryEntry('ly.img.pagePresets', { sourceIds: [...] })` to configure which sources to display.
+     *
+     * @example
+     * ```typescript
+     * // Before (deprecated):
+     * const config = {
+     *   ui: {
+     *     pageFormats: {
+     *       'custom-format': {
+     *         width: 800,
+     *         height: 600,
+     *         unit: 'Pixel'
+     *       }
+     *     }
+     *   }
+     * };
+     *
+     * // After (recommended):
+     * // Add a local source for custom page formats
+     * engine.asset.addLocalSource('my.custom.pageFormats');
+     * engine.asset.addAssetToSource('my.custom.pageFormats', {
+     *   id: 'custom-format',
+     *   label: { en: 'Custom Format' },
+     *   payload: {
+     *     transformPreset: {
+     *       type: 'FixedSize',
+     *       width: 800,
+     *       height: 600,
+     *       designUnit: 'Pixel'
+     *     }
+     *   }
+     * });
+     *
+     * // Update the asset library entry to use your custom source
+     * cesdk.ui.updateAssetLibraryEntry('ly.img.pagePresets', {
+     *   sourceIds: ['my.custom.pageFormats']
+     * });
+     * ```
+     */
     pageFormats?: {
         [id: string]: PageFormatDefinition;
     };
@@ -4953,22 +5202,7 @@ export declare class UserInterfaceAPI {
      */
     removeDockOrderComponent(matcher: OrderComponentMatcher<OrderComponent<DockOrderComponentId>>, orderContext?: OrderContext): {
         removed: number;
-        order: DockOrderComponent[]; /**
-        * Inserts a component into the render order of the dock area.
-        *
-        * This method inserts a new dock order component before, after, or to replace a component matching
-        * the provided matcher. The matcher can be a function or an object describing the component to match.
-        * The location can be 'before', 'after', or 'replace'.
-        *
-        * The insert API can be used in different contexts (such as edit modes).
-        *
-        * @category UI Layout
-        * @param component - The component ID or configuration to insert.
-        * @param matcher - Function or object to match the component to insert relative to.
-        * @param location - Where to insert the new component relative to the matched component ('before' or 'after').
-        * @param orderContext - Optional context specifying which order to update.
-        * @returns The updated dock order array.
-        */
+        order: DockOrderComponent[];
     };
     /**
      * Inserts a component into the render order of the dock area.
@@ -5054,22 +5288,7 @@ export declare class UserInterfaceAPI {
      */
     removeInspectorBarOrderComponent(matcher: OrderComponentMatcher<OrderComponent<InspectorBarComponentId>>, orderContext?: OrderContext): {
         removed: number;
-        order: OrderComponent<InspectorBarComponentId>[]; /**
-        * Inserts a component into the render order of the dock area.
-        *
-        * This method inserts a new dock order component before, after, or to replace a component matching
-        * the provided matcher. The matcher can be a function or an object describing the component to match.
-        * The location can be 'before', 'after', or 'replace'.
-        *
-        * The insert API can be used in different contexts (such as edit modes).
-        *
-        * @category UI Layout
-        * @param component - The component ID or configuration to insert.
-        * @param matcher - Function or object to match the component to insert relative to.
-        * @param location - Where to insert the new component relative to the matched component ('before' or 'after').
-        * @param orderContext - Optional context specifying which order to update.
-        * @returns The updated dock order array.
-        */
+        order: OrderComponent<InspectorBarComponentId>[];
     };
     /**
      * Inserts a component into the render order of the inspector bar.
@@ -5151,22 +5370,7 @@ export declare class UserInterfaceAPI {
      */
     removeCanvasMenuOrderComponent(matcher: OrderComponentMatcher<OrderComponent<CanvasMenuComponentId>>, orderContext?: OrderContext): {
         removed: number;
-        order: OrderComponent<CanvasMenuComponentId>[]; /**
-        * Inserts a component into the render order of the dock area.
-        *
-        * This method inserts a new dock order component before, after, or to replace a component matching
-        * the provided matcher. The matcher can be a function or an object describing the component to match.
-        * The location can be 'before', 'after', or 'replace'.
-        *
-        * The insert API can be used in different contexts (such as edit modes).
-        *
-        * @category UI Layout
-        * @param component - The component ID or configuration to insert.
-        * @param matcher - Function or object to match the component to insert relative to.
-        * @param location - Where to insert the new component relative to the matched component ('before' or 'after').
-        * @param orderContext - Optional context specifying which order to update.
-        * @returns The updated dock order array.
-        */
+        order: OrderComponent<CanvasMenuComponentId>[];
     };
     /**
      * Inserts a component into the render order of the canvas menu.
@@ -5335,22 +5539,7 @@ export declare class UserInterfaceAPI {
      */
     removeCanvasBarOrderComponent(matcher: OrderComponentMatcher<OrderComponent<CanvasBarComponentId>>, position: 'top' | 'bottom', orderContext?: OrderContext): {
         removed: number;
-        order: OrderComponent<CanvasBarComponentId>[]; /**
-        * Inserts a component into the render order of the dock area.
-        *
-        * This method inserts a new dock order component before, after, or to replace a component matching
-        * the provided matcher. The matcher can be a function or an object describing the component to match.
-        * The location can be 'before', 'after', or 'replace'.
-        *
-        * The insert API can be used in different contexts (such as edit modes).
-        *
-        * @category UI Layout
-        * @param component - The component ID or configuration to insert.
-        * @param matcher - Function or object to match the component to insert relative to.
-        * @param location - Where to insert the new component relative to the matched component ('before' or 'after').
-        * @param orderContext - Optional context specifying which order to update.
-        * @returns The updated dock order array.
-        */
+        order: OrderComponent<CanvasBarComponentId>[];
     };
     /**
      * Inserts a component into the render order of the canvas bar.
@@ -5390,16 +5579,19 @@ export declare class UserInterfaceAPI {
      *
      * @category Asset Library
      * @param id - The ID of the asset library entry to update.
-     * @param assetLibraryEntry - Partial entry properties to merge with the existing entry.
+     * @param assetLibraryEntry - Partial entry properties to merge with the existing entry, or a function that receives the current entry and pre-normalized sourceIds and returns the updated properties.
      */
-    updateAssetLibraryEntry(id: string, assetLibraryEntry: Partial<Omit<AssetLibraryEntry, 'id'>>): void;
+    updateAssetLibraryEntry(id: AssetEntryId, assetLibraryEntry: Partial<Omit<AssetLibraryEntry, 'id'>> | ((context: {
+        entry: AssetLibraryEntry;
+        sourceIds: string[];
+    }) => Partial<Omit<AssetLibraryEntry, 'id'>>)): void;
     /**
      * Removes an asset library entry from the available entries.
      *
      * @category Asset Library
      * @param id - The ID of the asset library entry to remove.
      */
-    removeAssetLibraryEntry(id: string): void;
+    removeAssetLibraryEntry(id: AssetEntryId): void;
     /**
      * Gets a specific asset library entry by its ID.
      *
@@ -5407,14 +5599,14 @@ export declare class UserInterfaceAPI {
      * @param id - The ID of the asset library entry to retrieve.
      * @returns The asset library entry configuration, or undefined if not found.
      */
-    getAssetLibraryEntry(id: string): AssetLibraryEntry | undefined;
+    getAssetLibraryEntry(id: AssetEntryId): AssetLibraryEntry | undefined;
     /**
      * Gets all currently registered asset library entry IDs.
      *
      * @category Asset Library
      * @returns Array of asset library entry IDs.
      */
-    findAllAssetLibraryEntries(): string[];
+    findAllAssetLibraryEntries(): AssetEntryId[];
     /**
      * Sets the asset library entries to use for the background track in video scenes.
      *
@@ -5437,7 +5629,7 @@ export declare class UserInterfaceAPI {
      * });
      * ```
      */
-    setBackgroundTrackAssetLibraryEntries(backgroundTrackAssetLibraryEntries: string[]): void;
+    setBackgroundTrackAssetLibraryEntries(backgroundTrackAssetLibraryEntries: AssetEntryId[]): void;
     /**
      * Gets the asset library entries configured for the background track in video scenes.
      *
@@ -5447,7 +5639,7 @@ export declare class UserInterfaceAPI {
      * @returns Array of asset library entry IDs configured for the background track.
      * @deprecated The background track entries are now defined via the cesdk.actions API.
      */
-    getBackgroundTrackAssetLibraryEntries(): string[];
+    getBackgroundTrackAssetLibraryEntries(): AssetEntryId[];
     /**
      * Sets a function that determines which asset library entries to use for replacement operations.
      *
@@ -5457,7 +5649,7 @@ export declare class UserInterfaceAPI {
      * @category Asset Library
      * @param replaceAssetLibraryEntries - Function that receives context and returns an array of asset library entry IDs for replacement.
      */
-    setReplaceAssetLibraryEntries(replaceAssetLibraryEntries: (context: ReplaceAssetLibraryEntriesContext) => string[]): void;
+    setReplaceAssetLibraryEntries(replaceAssetLibraryEntries: (context: ReplaceAssetLibraryEntriesContext) => AssetEntryId[]): void;
     /**
      * Gets the current view style of the editor interface.
      *
@@ -5585,6 +5777,8 @@ declare namespace UserInterfaceElements {
         CustomCardSvgVectorPathBackground,
         CustomCardBackground,
         AssetLibraryEntryView,
+        AssetEntrySourceIdsContext,
+        AssetEntryId,
         AssetLibraryEntryData,
         AssetLibraryEntry,
         AssetLibraryEntries,
@@ -5961,6 +6155,16 @@ declare interface UserInterfaceSettings extends UserInterfaceElement {
 export declare class UtilsAPI {
     #private;
 
+    /**
+     * Generates the automatic, localized fallback name for a design block. When
+     * the block does not have an explicit name set, this mirrors the naming shown
+     * in the UI panels.
+     *
+     * @param blockId - The block ID to generate a fallback name for
+     * @returns The localized fallback name for the block
+     * @public
+     */
+    generateBlockName(blockId: number): string;
     /**
      * Shows and manages a loading dialog with progress tracking
      *