@cesdk/engine 1.54.0-nightly.20250612 → 1.54.0-rc.0

package/index.d.ts

@@ -19,6 +19,9 @@ export declare type AnimationTypeLonghand = `//ly.img.ubq/animation/${AnimationT
  */
 export declare type AnimationTypeShorthand = 'slide' | 'pan' | 'fade' | 'blur' | 'grow' | 'zoom' | 'pop' | 'wipe' | 'baseline' | 'crop_zoom' | 'spin' | 'spin_loop' | 'fade_loop' | 'blur_loop' | 'pulsating_loop' | 'breathing_loop' | 'jump_loop' | 'squeeze_loop' | 'sway_loop' | 'typewriter_text' | 'block_swipe_text' | 'spread_text' | 'merge_text' | 'ken_burns';
 
+/** @public */
+export declare type ApplicationMimeType = Extract<MimeType_2, 'application/octet-stream' | 'application/pdf' | 'application/zip'>;
+
 /**
  * Generic asset information
  * @public
@@ -589,6 +592,16 @@ export declare type AssetTransformPreset = AssetFixedAspectRatio | AssetFreeAspe
  * @public
  */
 export declare type AudioExportOptions = {
+    /**
+     * The MIME type of the output audio file.
+     *
+     * @defaultValue 'audio/wav'
+     */
+    mimeType?: AudioMimeType;
+    /**
+     * A callback which reports on the progress of the export.
+     */
+    onProgress?: (numberOfRenderedFrames: number, numberOfEncodedFrames: number, totalNumberOfFrames: number) => void;
     /**
      * The time offset in seconds relative to the target block.
      *
@@ -615,6 +628,9 @@ export declare type AudioExportOptions = {
     numberOfChannels?: number;
 };
 
+/** @public */
+export declare type AudioMimeType = Extract<MimeType_2, 'audio/wav'>;
+
 /**
  * @public
  */
@@ -626,6 +642,14 @@ export declare type BlendMode = 'PassThrough' | 'Normal' | 'Darken' | 'Multiply'
 export declare class BlockAPI {
     #private;
 
+    /**
+     * Exports a design block element as a file of the given mime type.
+     * Performs an internal update to resolve the final layout for the blocks.
+     * @param handle - The design block element to export.
+     * @param options - The options for exporting the block type, including mime type and export settings.
+     * @returns A promise that resolves with the exported image or is rejected with an error.
+     */
+    export(handle: DesignBlockId, options?: ExportOptions): Promise<Blob>;
     /**
      * Exports a design block element as a file of the given mime type.
      * Performs an internal update to resolve the final layout for the blocks.
@@ -633,8 +657,28 @@ export declare class BlockAPI {
      * @param mimeType - The mime type of the output file.
      * @param options - The options for exporting the block type
      * @returns A promise that resolves with the exported image or is rejected with an error.
+     * @deprecated Use the new `export` signature instead
+     *
+     * @example
+     * ```typescript
+     * // Before migration
+     * const blob = await cesdk.block.export(blockId, MimeType.Png, { pngCompressionLevel: 5 })
+     * // After migration
+     * const blob = await cesdk.block.export(blockId, { mimeType: 'image/png', pngCompressionLevel: 5 })
+     * ```
      */
-    export(handle: DesignBlockId, mimeType?: MimeType_2, options?: ExportOptions): Promise<Blob>;
+    export(handle: DesignBlockId, mimeType?: ExportOptions['mimeType'], options?: Omit<ExportOptions, 'mimeType'>): Promise<Blob>;
+    /**
+     * Exports a design block element as a file of the given mime type.
+     * Performs an internal update to resolve the final layout for the blocks.
+     * @param handle - The design block element to export.
+     * @param maskColorR - The red component of the special color mask color.
+     * @param maskColorG - The green component of the special color mask color.
+     * @param maskColorB - The blue component of the special color mask color.
+     * @param options - The options for exporting the block type
+     * @returns A promise that resolves with an array of the exported image and mask or is rejected with an error.
+     */
+    exportWithColorMask(handle: DesignBlockId, maskColorR: number, maskColorG: number, maskColorB: number, options?: ExportOptions): Promise<Blob[]>;
     /**
      * Exports a design block element as a file of the given mime type.
      * Performs an internal update to resolve the final layout for the blocks.
@@ -645,27 +689,77 @@ export declare class BlockAPI {
      * @param maskColorB - The blue component of the special color mask color.
      * @param options - The options for exporting the block type
      * @returns A promise that resolves with an array of the exported image and mask or is rejected with an error.
+     * @deprecated Use the new `exportWithColorMask` signature instead
+     *
+     * @example
+     * ```typescript
+     * // Before migration
+     * const blob = await cesdk.block.exportWithColorMask(
+     *    blockId,
+     *    MimeType.Png,
+     *    0.5,
+     *    0,
+     *    0,
+     *    {
+     *      pngCompressionLevel: 5
+     *    }
+     * );
+     * // After migration
+     * const blob = await cesdk.block.exportWithColorMask(
+     *    blockId,
+     *    0.5,
+     *    0,
+     *    0,
+     *    {
+     *      mimeType: 'image/png',
+     *      pngCompressionLevel: 5
+     *    }
+     * );
+     * ```
      */
-    exportWithColorMask(handle: DesignBlockId, mimeType: MimeType_2 | undefined, maskColorR: number, maskColorG: number, maskColorB: number, options?: ExportOptions): Promise<Blob[]>;
+    exportWithColorMask(handle: DesignBlockId, mimeType: ExportOptions['mimeType'] | undefined, maskColorR: number, maskColorG: number, maskColorB: number, options?: Omit<ExportOptions, 'mimeType'>): Promise<Blob[]>;
     /**
      * Exports a design block as a video file of the given mime type.
      * Note: The export will run across multiple iterations of the update loop. In each iteration a frame is scheduled for encoding.
      * @param handle - The design block element to export. Currently, only page blocks are supported.
-     * @param mimeType - The mime type of the output video file.
-     * @param progressCallback - A callback which reports on the progress of the export. It informs the receiver of the current frame index, which currently gets exported and the total frame count.
-     * @param options - The options for exporting the video.
+     * @param options - The options for exporting the video, including mime type, h264 profile, level, bitrate, time offset, duration, framerate, target width and height.
      * @returns A promise that resolves with a video blob or is rejected with an error.
      */
-    exportVideo(handle: DesignBlockId, mimeType: MimeType_2 | undefined, progressCallback: (numberOfRenderedFrames: number, numberOfEncodedFrames: number, totalNumberOfFrames: number) => void, options: VideoExportOptions): Promise<Blob>;
+    exportVideo(handle: DesignBlockId, options?: VideoExportOptions): Promise<Blob>;
+    /**
+     * Exports a design block as a video file of the given mime type.
+     * Note: The export will run across multiple iterations of the update loop. In each iteration a frame is scheduled for encoding.
+     * @param handle - The design block element to export. Currently, only page blocks are supported.
+     * @param mimeType - The MIME type of the output video file.
+     * @param onProgress - A callback which reports on the progress of the export.
+     * @param options - The options for exporting the video, including h264 profile, level, bitrate, time offset, duration, framerate, target width and height.
+     * @returns A promise that resolves with a video blob or is rejected with an error.
+     * @deprecated Use the new `exportVideo` signature instead
+     *
+     * @example
+     * ```typescript
+     * // Before migration
+     * const blob = await cesdk.block.exportVideo(blockId, 'video/mp4', handleProgress, {
+     *   targetWidth: 1920,
+     *   targetHeight: 1080,
+     * })
+     * // After migration
+     * const blob = await cesdk.block.exportVideo(blockId, {
+     *   mimeType: 'video/mp4',
+     *   onProgress: handleProgress,
+     *   targetWidth: 1920,
+     *   targetHeight: 1080,
+     * })
+     * ```
+     */
+    exportVideo(handle: DesignBlockId, mimeType?: VideoExportOptions['mimeType'], progressCallback?: VideoExportOptions['onProgress'], options?: Omit<VideoExportOptions, 'mimeType' | 'onProgress'>): Promise<Blob>;
     /**
      * Exports a design block as an audio file of the given mime type.
      * @param handle - The design block element to export. Currently, only audio blocks are supported.
-     * @param mimeType - The mime type of the output audio file.
-     * @param progressCallback - A callback which reports on the progress of the export.
-     * @param options - The options for exporting the audio.
+     * @param options - The options for exporting the audio, including mime type, progress callback, and export settings.
      * @returns A promise that resolves with an audio blob or is rejected with an error.
      */
-    unstable_exportAudio(handle: DesignBlockId, mimeType: MimeType_2 | undefined, progressCallback: (numberOfRenderedFrames: number, numberOfEncodedFrames: number, totalNumberOfFrames: number) => void, options: AudioExportOptions): Promise<Blob>;
+    unstable_exportAudio(handle: DesignBlockId, options?: AudioExportOptions): Promise<Blob>;
     /**
      * Loads existing blocks from the given string.
      * The blocks are not attached by default and won't be visible until attached to a page or the scene.
@@ -2491,6 +2585,13 @@ export declare class BlockAPI {
      * @returns The bounding box of the line.
      */
     getTextVisibleLineGlobalBoundingBoxXYWH(id: DesignBlockId, lineIndex: number): XYWH;
+    /**
+     * Returns the text content of the given visible line of the text block.
+     * @param id - The text block whose line content should be returned.
+     * @param lineIndex - The index of the line whose content should be returned.
+     * @returns The text content of the line.
+     */
+    getTextVisibleLineContent(id: DesignBlockId, lineIndex: number): string;
     /**
      * Query if the given block has fill color properties.
      * @param id - The block to query.
@@ -4013,6 +4114,12 @@ declare interface ExportAudioOptions {
  * @public
  */
 export declare type ExportOptions = {
+    /**
+     * The MIME type of the output file.
+     *
+     * @defaultValue 'image/png'
+     */
+    mimeType?: ImageMimeType | Exclude<ApplicationMimeType, 'application/zip'>;
     /**
      * The PNG compression level to use, when exporting to PNG.
      *
@@ -4226,6 +4333,9 @@ export declare interface HTMLCreativeEngineCanvasElement extends HTMLElement {
     clear(): void;
 }
 
+/** @public */
+export declare type ImageMimeType = Extract<MimeType_2, 'image/png' | 'image/jpeg' | 'image/webp' | 'image/x-tga'>;
+
 /**
  * Type guard for {@link CMYKColor}
  * @public
@@ -4269,19 +4379,25 @@ export declare const LogLevel: {
     readonly Error: "Error";
 };
 
+/**
+ * @public
+ * @deprecated Use The `MimeType` string literal types instead.
+ * */
+declare const MimeType_2: {
+    readonly Png: "image/png";
+    readonly Jpeg: "image/jpeg";
+    readonly WebP: "image/webp";
+    readonly Tga: "image/x-tga";
+    readonly Wav: "audio/wav";
+    readonly Mp4: "video/mp4";
+    readonly QuickTime: "video/quicktime";
+    readonly Binary: "application/octet-stream";
+    readonly Pdf: "application/pdf";
+    readonly Zip: "application/zip";
+};
+
 /** @public */
-declare enum MimeType_2 {
-    Png = "image/png",
-    Jpeg = "image/jpeg",
-    WebP = "image/webp",
-    Tga = "image/x-tga",
-    Wav = "audio/wav",
-    Mp4 = "video/mp4",
-    QuickTime = "video/quicktime",
-    Binary = "application/octet-stream",
-    Pdf = "application/pdf",
-    Zip = "application/zip"
-}
+declare type MimeType_2 = (typeof MimeType_2)[keyof typeof MimeType_2];
 export { MimeType_2 as MimeType }
 
 /**
@@ -4986,6 +5102,16 @@ export declare type VerticalTextAlignment = 'Top' | 'Bottom' | 'Center';
  * @public
  */
 export declare type VideoExportOptions = {
+    /**
+     * The MIME type of the output video file.
+     *
+     * @defaultValue 'video/mp4'
+     */
+    mimeType?: VideoMimeType;
+    /**
+     * A callback which reports on the progress of the export.
+     */
+    onProgress?: (numberOfRenderedFrames: number, numberOfEncodedFrames: number, totalNumberOfFrames: number) => void;
     /**
      * Determines the encoder feature set and in turn the quality, size and speed of the encoding process.
      *
@@ -5046,6 +5172,9 @@ export declare type VideoExportOptions = {
     abortSignal?: AbortSignal;
 };
 
+/** @public */
+export declare type VideoMimeType = Extract<MimeType_2, 'video/mp4' | 'video/quicktime'>;
+
 /**
  * Describes a rectangle on the screen
  * - `x` and `y` indicate the position