@cesdk/engine 1.19.0-rc.0 → 1.20.0-rc.0

package/index.d.ts

@@ -187,7 +187,7 @@ export declare interface AssetDefinition extends Asset {
 export declare type AssetGroups = string[];
 
 /**
- * AssetColor Meta information
+ * Generic asset information
  * @public
  */
 export declare type AssetMetaData = {
@@ -201,6 +201,7 @@ export declare type AssetMetaData = {
     uri?: string;
     thumbUri?: string;
     previewUri?: string;
+    sourceSet?: Source[];
     filename?: string;
     vectorPath?: string;
     width?: number;
@@ -216,6 +217,7 @@ export declare type AssetMetaData = {
  */
 export declare interface AssetPayload {
     color?: AssetColor;
+    sourceSet?: Source[];
 }
 
 /**
@@ -540,6 +542,25 @@ export declare class BlockAPI {
      * @param id - A block id.
      */
     exitGroup(id: DesignBlockId): void;
+    /**
+     * Checks whether blocks could be combined.
+     * Only graphics blocks and text blocks can be combined.
+     * All blocks must have the "lifecycle/duplicate" scope enabled.
+     * @param ids - An array of block ids.
+     * @returns Whether the blocks can be combined.
+     */
+    isCombinable(ids: DesignBlockId[]): boolean;
+    /**
+     * Perform a boolean operation on the given blocks.
+     * All blocks must be combinable. See `isCombinable`.
+     * The parent, fill and  sort order of the new block is that of the prioritized block.
+     * When performing a `Union`, `Intersection` or `XOR`, the operation is performed pair-wise starting with the element with the highest sort order.
+     * When performing a `Difference`, the operation is performed pair-wise starting with the element with the lowest sort order.
+     * @param ids - The blocks to combine. They will be destroyed if "lifecycle/destroy" scope is enabled.
+     * @param op - The boolean operation to perform.
+     * @returns The newly created block or an error.
+     */
+    combine(ids: DesignBlockId[], op: BooleanOperation): DesignBlockId;
     /**
      * Update a block's name.
      * @param id - The block to update.
@@ -1201,6 +1222,20 @@ export declare class BlockAPI {
      * @returns The gradient colors.
      */
     getGradientColorStops(id: DesignBlockId, property: string): GradientColorStop[];
+    /**
+     * Get the source set value of the given property.
+     * @param id - The block that should be queried.
+     * @param property - The name of the property to query.
+     * @returns The block's source set.
+     */
+    getSourceSet(id: DesignBlockId, property: string): Source[];
+    /**
+     * Set the property of the given block.
+     * @param id - The block whose property should be set.
+     * @param property - The name of the property to set.
+     * @param sourceSet - The block's new source set.
+     */
+    setSourceSet(id: DesignBlockId, property: string, sourceSet: Source[]): void;
     /**
      * Set an enum property of the given design block to the given value.
      * @param id - The block whose property should be set.
@@ -2308,6 +2343,13 @@ export declare type BlurTypeLonghand = `//ly.img.ubq/blur/${BlurTypeShorthand}`;
  */
 export declare type BlurTypeShorthand = 'uniform' | 'linear' | 'mirrored' | 'radial';
 
+/**
+ * Names of boolean operations.
+ *
+ * @public
+ */
+export declare type BooleanOperation = 'Difference' | 'Intersection' | 'Union' | 'XOR';
+
 declare type CameraSettings = {
     /** Horizontal resolution in physical pixels */
     width: number;
@@ -2334,7 +2376,7 @@ export declare type Canvas = HTMLCanvasElement | OffscreenCanvas_2;
  * @public
  */
 declare interface Channel<Out, In = Out> {
-    subscribe: Source<Out>;
+    subscribe: Source_2<Out>;
     update?: (v: In) => void;
     value?: () => Out;
 }
@@ -2344,7 +2386,7 @@ declare interface Channel<Out, In = Out> {
  * @public
  */
 declare interface ChannelSync<Out, In = Out> extends Channel<Out, In> {
-    subscribe: Source<Out>;
+    subscribe: Source_2<Out>;
     update?: (v: In) => void;
     value: () => Out;
 }
@@ -2653,6 +2695,10 @@ export declare interface Configuration {
      * The settings that were configured here can be set via the
      * following EditorAPI settings:
      * - `setSettingBool('page/title/show', show)`
+     * - `setSettingBool('page/title/showPageTitleTemplate', show)`
+     * - `setSettingBool('page/title/appendPageName', append)`
+     * - `setSettingBool('page/title/showOnSinglePage', hide)`
+     * - `setSettingString('page/title/separator', separator)`
      * - `setSettingString('page/title/fontFileUri', uri)`
      * - `setSettingBool('page/dimOutOfPageAreas', dim)`
      */
@@ -2709,30 +2755,23 @@ declare class CreativeEngine {
     variable: VariableAPI;
 
 
-
     /**
-     * Provide a callback that instantiates a web worker using the `@cesdk/engine`
-     * module as its source. How and where exactly you can find that module is
-     * highly depdendent on your particular setup. Web workers are used to perform
-     * certain expensive tasks, such as video export, in the background
-     *
-     * If no worker factory is provided, the engine will perform long-running
-     * tasks in the main thread.
+     * Add a plugin to the engine. If a plugin URL is provided, the plugin will be
+     * loaded from that URL. Otherwise, the argument is expected to be a valid plugin
      *
-     * @example
-     * In a webpack environment, the implementation of the worker factory could
-     * look like this:
+     * A plugin can have the following methods:
+     * - `initialize` - Called once when the plugin is added to the engine
+     * - `update` - Called every frame
      *
-     * ```ts
-     * engine._unstable_setWorkerFactory(
-     *   () => new Worker(new URL('@cesdk/engine', import.meta.url)))
-     * )
-     * ```
+     * PLEASE NOTE: Plugins not provded via URL will not be executed in the worker, e.g.
+     * during the video export the update method is not called.
      *
-     * For more information, consult the webpack documentation at
-     * https://webpack.js.org/guides/web-workers/
+     * Please be aware that this is experimental right now. This API can change or
+     * be replaced or even removed completely in future versions.
      */
-    unstable_setWorkerFactory(workerFactory: null | (() => Worker)): void;
+    unstable_addPlugin(plugin: EnginePlugin & {
+        url?: string;
+    }): Promise<void>;
     /**
      * Some browsers exhibit a bug where support for certain video codecs is
      * offered, but when attempting to decode or encode in these codecs, the
@@ -3001,6 +3040,8 @@ export declare class EditorAPI {
      * @throws An error, if the keypath is invalid.
      */
     setSettingBool(keypath: SettingsBool, value: boolean): void;
+    /** @deprecated Support for `ubq://` prefixed keypaths will be removed in a future release. */
+    setSettingBool(keypath: `ubq://${SettingsBool}`, value: boolean): void;
 
     /**
      * Get a boolean setting.
@@ -3008,6 +3049,8 @@ export declare class EditorAPI {
      * @throws An error, if the keypath is invalid.
      */
     getSettingBool(keypath: SettingsBool): boolean;
+    /** @deprecated Support for `ubq://` prefixed keypaths will be removed in a future release. */
+    getSettingBool(keypath: `ubq://${SettingsBool}`): boolean;
 
     /**
      * Set an integer setting.
@@ -3029,12 +3072,16 @@ export declare class EditorAPI {
      * @throws An error, if the keypath is invalid.
      */
     setSettingFloat(keypath: SettingsFloat, value: number): void;
+    /** @deprecated Support for `ubq://` prefixed keypaths will be removed in a future release. */
+    setSettingFloat(keypath: `ubq://${SettingsFloat}`, value: number): void;
     /**
      * Get a float setting.
      * @param keypath - The settings keypath, e.g. `positionSnappingThreshold`
      * @throws An error, if the keypath is invalid.
      */
     getSettingFloat(keypath: SettingsFloat): number;
+    /** @deprecated Support for `ubq://` prefixed keypaths will be removed in a future release. */
+    getSettingFloat(keypath: `ubq://${SettingsFloat}`): number;
     /**
      * Set a string setting.
      * @param keypath - The settings keypath, e.g. `license`
@@ -3042,24 +3089,32 @@ export declare class EditorAPI {
      * @throws An error, if the keypath is invalid.
      */
     setSettingString(keypath: SettingsString, value: string): void;
+    /** @deprecated Support for `ubq://` prefixed keypaths will be removed in a future release. */
+    setSettingString(keypath: `ubq://${SettingsString}`, value: string): void;
     /**
      * Get a string setting.
      * @param keypath - The settings keypath, e.g. `license`
      * @throws An error, if the keypath is invalid.
      */
     getSettingString(keypath: SettingsString): string;
+    /** @deprecated Support for `ubq://` prefixed keypaths will be removed in a future release. */
+    getSettingString(keypath: `ubq://${SettingsString}`): string;
     /**
      * Set a color setting.
      * @param keypath - The settings keypath, e.g. `highlightColor`.
      * @param value - The The value to set.
      */
     setSettingColor(keypath: SettingsColor, value: Color): void;
+    /** @deprecated Support for `ubq://` prefixed keypaths will be removed in a future release. */
+    setSettingColor(keypath: `ubq://${SettingsColor}`, value: Color): void;
     /**
      * Get a color setting.
      * @param keypath - The settings keypath, e.g. `highlightColor`.
      * @throws An error, if the keypath is invalid.
      */
     getSettingColor(keypath: SettingsColor): Color;
+    /** @deprecated Support for `ubq://` prefixed keypaths will be removed in a future release. */
+    getSettingColor(keypath: `ubq://${SettingsColor}`): Color;
     /**
      * Set a color setting.
      * @param keypath - The settings keypath, e.g. `highlightColor`.
@@ -3069,32 +3124,38 @@ export declare class EditorAPI {
      * @param a - The alpha color component in the range of 0 to 1.
      * @deprecated Use setSettingColor() instead.
      */
-    setSettingColorRGBA(keypath: SettingsColorRGBA, r: number, g: number, b: number, a?: number): void;
+    setSettingColorRGBA(keypath: SettingsColorRGBA | `ubq://${SettingsColorRGBA}`, r: number, g: number, b: number, a?: number): void;
     /**
      * Get a color setting.
      * @param keypath - The settings keypath, e.g. `highlightColor`.
      * @returns A tuple of channels red, green, blue and alpha in the range of 0 to 1.
      * @deprecated Use getSettingColor() instead.
      */
-    getSettingColorRGBA(keypath: SettingsColorRGBA): RGBA;
+    getSettingColorRGBA(keypath: SettingsColorRGBA | `ubq://${SettingsColorRGBA}`): RGBA;
     /**
      * Set an enum setting.
      * @param keypath - The settings keypath, e.g. `role`.
      * @param value - The enum value as string.
      */
     setSettingEnum<T extends keyof SettingsEnum>(keypath: T, value: SettingsEnum[T]): void;
+    /** @deprecated Support for `ubq://` prefixed keypaths will be removed in a future release. */
+    setSettingEnum<T extends keyof SettingsEnum>(keypath: `ubq://${T}`, value: SettingsEnum[T]): void;
     /**
      * Get an enum setting.
      * @param keypath - The settings keypath, e.g. `role`.
      * @returns The value as string.
      */
     getSettingEnum<T extends keyof SettingsEnum>(keypath: T): SettingsEnum[T];
+    /** @deprecated Support for `ubq://` prefixed keypaths will be removed in a future release. */
+    getSettingEnum<T extends keyof SettingsEnum>(keypath: `ubq://${T}`): SettingsEnum[T];
     /**
      * Get the possible enum options for a given enum setting.
      * @param keypath - The settings keypath, e.g. `role`.
      * @returns The possible enum options as strings.
      */
     getSettingEnumOptions<T extends keyof SettingsEnum>(keypath: T): string[];
+    /** @deprecated Support for `ubq://` prefixed keypaths will be removed in a future release. */
+    getSettingEnumOptions<T extends keyof SettingsEnum>(keypath: `ubq://${T}`): string[];
     /**
      * Returns a list of all the settings available.
      * @returns A list of settings keypaths.
@@ -3242,6 +3303,12 @@ export declare type EffectTypeLonghand = `//ly.img.ubq/effect/${EffectTypeShorth
  */
 export declare type EffectTypeShorthand = 'adjustments' | 'cross_cut' | 'dot_pattern' | 'duotone_filter' | 'extrude_blur' | 'glow' | 'half_tone' | 'linocut' | 'liquid' | 'lut_filter' | 'mirror' | 'outliner' | 'pixelize' | 'posterize' | 'radial_pixel' | 'sharpie' | 'shifter' | 'tilt_shift' | 'tv_glitch' | 'vignette';
 
+/** @public */
+export declare interface EnginePlugin {
+    initialize?: (context: PluginContext) => void;
+    update?: (context: PluginContext) => void;
+}
+
 /**
  * @public
  */
@@ -3537,6 +3604,15 @@ export declare interface PageDuration {
  */
 export declare type PaletteColor = HexColorString | RGBColor | RGBAColor | SpotColor;
 
+declare type PluginContext = {
+    asset: AssetAPI;
+    block: BlockAPI;
+    scene: SceneAPI;
+    editor: EditorAPI;
+    event: EventAPI;
+    variable: VariableAPI;
+};
+
 /**
  * - Absolute: Position in absolute design units.
  * - Percent: Position in relation to the block's parent's size in percent, where 1.0 means 100%.
@@ -3547,7 +3623,7 @@ export declare type PaletteColor = HexColorString | RGBColor | RGBAColor | SpotC
 export declare type PositionMode = 'Absolute' | 'Percent' | 'Auto';
 
 /** @public */
-export declare type PropertyType = 'Bool' | 'Int' | 'Float' | 'String' | 'Color' | 'Enum' | 'Struct' | 'Double';
+export declare type PropertyType = 'Bool' | 'Int' | 'Float' | 'String' | 'Color' | 'Enum' | 'Struct' | 'Double' | 'SourceSet';
 
 /**
  * An open range.
@@ -3566,7 +3642,7 @@ export { Range_2 as Range }
  * @public
  */
 declare interface ReadOnlyChannel<Out> extends Omit<Channel<Out>, 'update'> {
-    subscribe: Source<Out>;
+    subscribe: Source_2<Out>;
     value?: () => Out;
 }
 
@@ -3575,7 +3651,7 @@ declare interface ReadOnlyChannel<Out> extends Omit<Channel<Out>, 'update'> {
  * @public
  */
 declare interface ReadOnlyChannelSync<Out> extends Omit<ChannelSync<Out>, 'update'>, ReadOnlyChannel<Out> {
-    subscribe: Source<Out>;
+    subscribe: Source_2<Out>;
     value: () => Out;
 }
 
@@ -3584,7 +3660,7 @@ declare interface ReadOnlyChannelSync<Out> extends Omit<ChannelSync<Out>, 'updat
  * @public
  */
 declare interface ReadWriteChannel<Out, In = Out> extends Channel<Out, In> {
-    subscribe: Source<Out>;
+    subscribe: Source_2<Out>;
     update: (v: In) => void;
     value?: () => Out;
 }
@@ -3594,7 +3670,7 @@ declare interface ReadWriteChannel<Out, In = Out> extends Channel<Out, In> {
  * @public
  */
 declare interface ReadWriteChannelSync<Out, In = Out> extends ChannelSync<Out, In>, ReadWriteChannel<Out, In> {
-    subscribe: Source<Out>;
+    subscribe: Source_2<Out>;
     update: (v: In) => void;
     value: () => Out;
 }
@@ -3920,7 +3996,7 @@ export declare type SceneLayout = 'Free' | 'VerticalStack' | 'HorizontalStack' |
 export declare type SceneMode = 'Design' | 'Video';
 
 /** @public */
-export declare type SettingsBool = 'doubleClickToCropEnabled' | 'features/effectsEnabled' | 'features/hspSelectiveAdjustmentsEnabled' | 'features/layerListEnabled' | 'features/singlePageModeEnabled' | 'features/templatingEnabled' | 'mouse/enableZoom' | 'mouse/enableScroll' | 'page/dimOutOfPageAreas' | 'page/title/show' | 'placeholderControls/showButton' | 'placeholderControls/showOverlay' | 'showBuildVersion' | 'touch/dragStartCanSelect' | 'touch/singlePointPanning';
+export declare type SettingsBool = 'doubleClickToCropEnabled' | 'features/singlePageModeEnabled' | 'mouse/enableZoom' | 'mouse/enableScroll' | 'page/dimOutOfPageAreas' | 'page/title/show' | 'page/title/showPageTitleTemplate' | 'page/title/appendPageName' | 'page/title/showOnSinglePage' | 'placeholderControls/showButton' | 'placeholderControls/showOverlay' | 'showBuildVersion' | 'touch/dragStartCanSelect' | 'touch/singlePointPanning';
 
 /** @public
  */
@@ -3943,7 +4019,7 @@ export declare type SettingsEnum = {
 export declare type SettingsFloat = 'positionSnappingThreshold';
 
 /** @public */
-export declare type SettingsString = 'basePath' | 'license' | 'page/title/fontFileUri' | 'defaultEmojiFontFileUri';
+export declare type SettingsString = 'basePath' | 'license' | 'page/title/separator' | 'page/title/fontFileUri' | 'defaultEmojiFontFileUri';
 
 /** @public */
 export declare type SettingType = 'Bool' | 'Int' | 'Float' | 'String' | 'Color' | 'Enum';
@@ -3984,6 +4060,16 @@ export declare interface Size2 {
  */
 export declare type SizeMode = 'Absolute' | 'Percent' | 'Auto';
 
+/**
+ * A single source width an intrinsic width & height.
+ * @public
+ */
+export declare interface Source {
+    uri: string;
+    width: number;
+    height: number;
+}
+
 /**
  * A stream source.
  *
@@ -3993,7 +4079,7 @@ export declare type SizeMode = 'Absolute' | 'Percent' | 'Auto';
  * Returns a function that unsubscribes the handler from the source
  * @public
  */
-declare type Source<T> = (handler: Handler<T>) => UnsubscribeFn;
+declare type Source_2<T> = (handler: Handler<T>) => UnsubscribeFn;
 
 /** @public */
 export declare interface SpotColor {