@cesdk/engine 1.62.0-nightly.20251007 → 1.62.0-nightly.20251009

package/index.d.ts

@@ -128,6 +128,24 @@ export declare type AnimationTypeShorthand = 'slide' | 'pan' | 'fade' | 'blur' |
  */
 export declare type ApplicationMimeType = Extract<MimeType_2, 'application/octet-stream' | 'application/pdf' | 'application/zip'>;
 
+/**
+ * Options for applying an asset to the scene.
+ * @public
+ */
+export declare interface ApplyAssetOptions {
+    /**
+     * How the asset should be placed in the scene.
+     * - 'clip': Foreground clip placed at playhead
+     * - 'overlay': Background overlay placed on background track
+     */
+    clipType?: 'clip' | 'overlay';
+    /**
+     * Additional custom context options.
+     * Allows passing arbitrary data to middleware for custom placement logic.
+     */
+    [key: string]: unknown;
+}
+
 /**
  * Generic asset information
  * @public
@@ -179,12 +197,17 @@ export declare class AssetAPI {
     /**
      * Register middleware that intercepts asset application to scenes.
      *
-     * The middleware function receives the source ID, asset result, and the original apply function.
+     * The middleware function receives the source ID, asset result, the original apply function,
+     * and a context object containing options about how the asset should be applied.
      * It can perform custom logic before, after, or instead of the default asset application.
      *
      * @example
      * ```ts
-     * engine.asset.unstable_registerApplyAssetMiddleware(async (sourceId, assetResult, apply) => {
+     * engine.asset.registerApplyMiddleware(async (sourceId, assetResult, apply, context) => {
+     *   // Access context to determine placement intent
+     *   console.log('Clip type:', context.clipType); // 'clip', 'overlay', or undefined
+     *   console.log('Custom data:', context.myCustomField); // Access custom fields
+     *
      *   // do something before applying the asset
      *   // You still have the choice to call apply or skip it
      *   const blockId = await apply(sourceId, assetResult);
@@ -193,12 +216,11 @@ export declare class AssetAPI {
      * })
      * ```
      *
-     * @category Experimental Features
+     * @category Asset Application
      * @param middleware - The middleware function that is called before applying the asset.
      * @returns A function that can be used to remove the middleware.
-     * @experimental This API is experimental and may change or be removed in future versions.
      */
-    unstable_registerApplyAssetMiddleware(middleware: (sourceId: string, assetResult: AssetResult, apply: AssetAPI['apply']) => Promise<DesignBlockId | undefined>): VoidFunction;
+    registerApplyMiddleware(middleware: (sourceId: string, assetResult: AssetResult, apply: AssetAPI['apply'], context: ApplyAssetOptions) => Promise<DesignBlockId | undefined>): VoidFunction;
     /**
      * Register middleware that intercepts asset application to specific blocks.
      *
@@ -207,7 +229,7 @@ export declare class AssetAPI {
      *
      * @example
      * ```ts
-     * engine.asset.unstable_registerApplyAssetToBlockMiddleware(async (sourceId, assetResult, block, applyToBlock) => {
+     * engine.asset.registerApplyToBlockMiddleware(async (sourceId, assetResult, block, applyToBlock) => {
      *   // do something before applying the asset
      *   // You still have the choice to call applyToBlock or skip it
      *   await applyToBlock(sourceId, assetResult, block);
@@ -215,12 +237,11 @@ export declare class AssetAPI {
      * })
      * ```
      *
-     * @category Experimental Features
+     * @category Asset Application
      * @param middleware - The middleware function that is called before applying the asset.
      * @returns A function that can be used to remove the middleware.
-     * @experimental This API is experimental and may change or be removed in future versions.
      */
-    unstable_registerApplyAssetToBlockMiddleware(middleware: (sourceId: string, assetResult: AssetResult, block: DesignBlockId, applyToBlock: AssetAPI['applyToBlock']) => Promise<void>): VoidFunction;
+    registerApplyToBlockMiddleware(middleware: (sourceId: string, assetResult: AssetResult, block: DesignBlockId, applyToBlock: AssetAPI['applyToBlock']) => Promise<void>): VoidFunction;
     /**
      * Add a custom asset source with unique ID.
      *
@@ -525,18 +546,30 @@ export declare class AssetAPI {
      * Apply an asset to the active scene.
      *
      * Creates a new block configured according to the asset's properties and adds it to the scene.
-     * The behavior can be customized by providing an `applyAsset` function when registering the asset source.
+     * The behavior can be customized by providing an `applyAsset` function when registering the asset source,
+     * or by passing context options to guide middleware behavior.
      *
+     * @example
      * ```javascript
+     * // Default behavior
      * await engine.asset.apply('asset-source-id', assetResult.assets[0]);
      * ```
      *
+     * @example
+     * ```javascript
+     * // Background overlay placement
+     * await engine.asset.apply('asset-source-id', assetResult.assets[0], {
+     *   clipType: 'overlay'
+     * });
+     * ```
+     *
      * @category Asset Application
      * @param sourceId - The ID of the asset source.
      * @param assetResult - A single asset result from a `findAssets` query.
+     * @param options - Optional configuration for asset application.
      * @returns Promise resolving to the created block ID, or undefined if no block was created.
      */
-    apply(sourceId: string, assetResult: AssetResult): Promise<DesignBlockId | undefined>;
+    apply(sourceId: string, assetResult: AssetResult, options?: ApplyAssetOptions): Promise<DesignBlockId | undefined>;
     /**
      * Apply an asset to a specific block.
      *
@@ -5271,10 +5304,10 @@ export declare class BlockAPI {
      * This is useful for organizing content in video scenes where you want
      * certain elements to be part of the background layer.
      * The background track is the track that determines the page duration.
+     * If no background track exists, one will be created automatically.
      *
      * @category Helper
      * @param block - The ID of the block to move to the background track
-     * @throws Error if no background track is found
      */
     moveToBackgroundTrack(block: DesignBlockId): void;
 }