@cesdk/engine 1.19.0 → 1.20.0-rc.1

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
+     * 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
      *
-     * If no worker factory is provided, the engine will perform long-running
-     * tasks in the main thread.
+     * A plugin can have the following methods:
+     * - `initialize` - Called once when the plugin is added to the engine
+     * - `update` - Called every frame
      *
-     * @example
-     * In a webpack environment, the implementation of the worker factory could
-     * look like this:
-     *
-     * ```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
@@ -3101,6 +3140,7 @@ export declare class EditorAPI {
     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`.
@@ -3109,6 +3149,7 @@ export declare class EditorAPI {
     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`.
@@ -3264,6 +3305,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
  */
@@ -3559,6 +3606,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%.
@@ -3569,7 +3625,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.
@@ -3588,7 +3644,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;
 }
 
@@ -3597,7 +3653,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;
 }
 
@@ -3606,7 +3662,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;
 }
@@ -3616,7 +3672,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;
 }
@@ -3942,11 +3998,11 @@ export declare type SceneLayout = 'Free' | 'VerticalStack' | 'HorizontalStack' |
 export declare type SceneMode = 'Design' | 'Video';
 
 /** @public */
-export declare type SettingsBool = 'doubleClickToCropEnabled' | 'features/singlePageModeEnabled' | 'mouse/enableZoom' | 'mouse/enableScroll' | 'page/dimOutOfPageAreas' | 'page/title/show' | 'placeholderControls/showButton' | 'placeholderControls/showOverlay' | 'showBuildVersion' | 'touch/dragStartCanSelect' | 'touch/singlePointPanning';
+export declare type SettingsBool = 'controlGizmo/showCropHandles' | 'controlGizmo/showCropScaleHandles' | 'controlGizmo/showResizeHandles' | 'controlGizmo/showRotateHandles' | 'controlGizmo/showScaleHandles' | 'doubleClickToCropEnabled' | 'features/singlePageModeEnabled' | 'mouse/enableScroll' | 'mouse/enableZoom' | 'page/dimOutOfPageAreas' | 'page/title/appendPageName' | 'page/title/show' | 'page/title/showOnSinglePage' | 'page/title/showPageTitleTemplate' | 'placeholderControls/showButton' | 'placeholderControls/showOverlay' | 'showBuildVersion' | 'touch/dragStartCanSelect' | 'touch/singlePointPanning';
 
 /** @public
  */
-declare type SettingsColor = 'clearColor' | 'errorStateColor' | 'highlightColor' | 'page/title/color' | 'placeholderHighlightColor' | 'progressColor';
+declare type SettingsColor = 'borderOutlineColor' | 'clearColor' | 'colorMaskingSettings/maskColor' | 'cropOverlayColor' | 'errorStateColor' | 'highlightColor' | 'page/innerBorderColor' | 'page/marginFillColor' | 'page/marginFrameColor' | 'page/outerBorderColor' | 'page/title/color' | 'placeholderHighlightColor' | 'progressColor' | 'rotationSnappingGuideColor' | 'snappingGuideColor' | 'textVariableHighlightColor';
 
 /** @public
  * @deprecated Use SettingsColor instead.
@@ -3962,10 +4018,10 @@ export declare type SettingsEnum = {
 };
 
 /** @public */
-export declare type SettingsFloat = 'positionSnappingThreshold';
+export declare type SettingsFloat = 'positionSnappingThreshold' | 'rotationSnappingThreshold';
 
 /** @public */
-export declare type SettingsString = 'basePath' | 'license' | 'page/title/fontFileUri' | 'defaultEmojiFontFileUri';
+export declare type SettingsString = 'basePath' | 'defaultEmojiFontFileUri' | 'license' | 'page/title/fontFileUri' | 'page/title/separator';
 
 /** @public */
 export declare type SettingType = 'Bool' | 'Int' | 'Float' | 'String' | 'Color' | 'Enum';
@@ -4006,6 +4062,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.
  *
@@ -4015,7 +4081,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 {