@cesdk/engine 1.58.0-nightly.20250730 → 1.58.0-nightly.20250807

package/index.d.ts

@@ -1018,7 +1018,6 @@ export declare type AssetTransformPreset = AssetFixedAspectRatio | AssetFreeAspe
 /**
  * Represents the options for exporting audio.
  *
- * @categoryDescription Audio Export Options
  * Defines the possible options for exporting audio.
  * - 'mimeType': The MIME type of the output audio file.
  * - 'onProgress': A callback which reports on the progress of the export.
@@ -1391,6 +1390,10 @@ export declare class BlockAPI {
      * @category Block Lifecycle
      * @param blocks - The blocks to save.
      * @param allowedResourceSchemes - The resource schemes to allow in the saved string. Defaults to ['buffer', 'http', 'https'].
+     * @param onDisallowedResourceScheme - An optional callback that is called for each resource URL that has a scheme absent from
+     * `resourceSchemesAllowed`. The `url` parameter is the resource URL and the `dataHash` parameter is the hash of the
+     * resource's data. The callback should return a new URL for the resource, which will be used in the serialized
+     * scene. The callback is expected to return the original URL if no persistence is needed.
      * @returns A promise that resolves to a string representing the blocks or an error.
      * @example
      * ```typescript
@@ -1403,7 +1406,7 @@ export declare class BlockAPI {
      * const serialized = await engine.block.saveToString([page]);
      * ```
      */
-    saveToString(blocks: DesignBlockId[], allowedResourceSchemes?: string[]): Promise<string>;
+    saveToString(blocks: DesignBlockId[], allowedResourceSchemes?: string[], onDisallowedResourceScheme?: (url: string, dataHash: string) => Promise<string>): Promise<string>;
     /**
      * Saves the given blocks and their assets to a zip archive.
      *
@@ -5018,9 +5021,6 @@ export declare class BlockAPI {
  * The `BlockEvent` interface provides a set of properties that describe an event related to
  * a design block, including the block ID and the type of event.
  *
- * @categoryDescription BlockEvent
- * Methods for working with events related to design blocks.
- *
  * @public
  */
 export declare interface BlockEvent {
@@ -5047,9 +5047,6 @@ export declare type BlockState = BlockStateError | BlockStatePending | BlockStat
  * The `BlockStateError` interface provides a set of properties that describe an error state
  * for a design block, including the type of error and a description of the error.
  *
- * @categoryDescription BlockStateError
- * Methods for working with error states for design blocks.
- *
  * @public
  */
 export declare interface BlockStateError {
@@ -5063,9 +5060,6 @@ export declare interface BlockStateError {
  * The `BlockStatePending` interface provides a set of properties that describe a pending
  * state for a design block, including the type of state and the progress of the operation.
  *
- * @categoryDescription BlockStatePending
- * Methods for working with pending states for design blocks.
- *
  * @public
  */
 export declare interface BlockStatePending {
@@ -5080,9 +5074,6 @@ export declare interface BlockStatePending {
  * The `BlockStateReady` interface provides a set of properties that describe a ready state
  * for a design block, including the type of state.
  *
- * @categoryDescription BlockStateReady
- * Methods for working with ready states for design blocks.
- *
  * @public
  */
 export declare interface BlockStateReady {
@@ -5127,7 +5118,6 @@ export declare type BlurTypeShorthand = 'uniform' | 'linear' | 'mirrored' | 'rad
 /**
  * Represents the names of boolean operations.
  *
- * @categoryDescription Boolean Operation
  * Defines the possible boolean operations.
  * - 'Difference': The difference between two shapes.
  * - 'Intersection': The intersection of two shapes.
@@ -5144,9 +5134,6 @@ export declare type BooleanOperation = 'Difference' | 'Intersection' | 'Union' |
  * The `Buffer` interface provides a set of properties that describe a buffer of data,
  * including a handle and the buffer itself.
  *
- * @categoryDescription Buffer
- * Methods for working with buffers of data.
- *
  * @public
  */
 export declare interface Buffer {
@@ -5188,7 +5175,6 @@ export declare type CMYK = [c: number, m: number, y: number, k: number];
 /**
  * Represents a CMYK color value.
  *
- * @categoryDescription CMYK Color
  * Defines a CMYK color value with components between 0 and 1.
  * - 'c': The cyan component.
  * - 'm': The magenta component.
@@ -5263,9 +5249,6 @@ export declare interface CompleteAssetResult extends AssetResult {
  * user ID, core settings, logger, feature flags, presets, force WebGL1, audio output,
  * and role.
  *
- * @categoryDescription Configuration
- * Methods for configuring the settings of the Creative Editor SDK.
- *
  * @public
  */
 export declare interface Configuration {
@@ -6474,7 +6457,6 @@ export declare type EffectTypeShorthand = 'adjustments' | 'cross_cut' | 'dot_pat
 /**
  * Represents an engine plugin.
  *
- * @categoryDescription Engine Plugin
  * Defines the structure of an engine plugin, including its name, version, and initialization function.
  * - 'name': The name of the plugin.
  * - 'version': The version of the plugin.
@@ -6491,7 +6473,6 @@ export declare interface EnginePlugin {
 /**
  * Represents the context for an engine plugin.
  *
- * @categoryDescription Engine Plugin Context
  * Defines the context provided to an engine plugin, including APIs for assets, blocks, scenes, editor, events, and variables.
  * - 'engine': The engine instance containing APIs for asset, block, scene, editor, event, and variable management.
  *
@@ -6553,7 +6534,6 @@ declare interface ExportAudioOptions {
 /**
  * Represents the options for exporting a design block.
  *
- * @categoryDescription Export Options
  * Defines the possible options for exporting a design block.
  * - 'mimeType': The MIME type of the output file.
  * - 'pngCompressionLevel': The PNG compression level to use, when exporting to PNG.
@@ -6647,9 +6627,6 @@ export declare type ExportOptions = {
  * for JPEG, WebP, PNG, and PDF exports, as well as options for resizing and
  * adding underlayers.
  *
- * @categoryDescription Export Options
- * Methods for configuring export settings for design blocks.
- *
  * @public
  */
 declare interface ExportOptions_2 {
@@ -6758,9 +6735,6 @@ declare interface Flip {
  * The Font interface defines the structure of a font within the Creative Editor SDK.
  * It includes properties for the uri, subFamily, weight, and style.
  *
- * @categoryDescription Fonts
- * Methods for managing fonts within the editor.
- *
  * @public
  */
 export declare interface Font {
@@ -6776,9 +6750,6 @@ export declare interface Font {
  * The FontStyle type defines the possible styles of a font within the Creative Editor SDK.
  * Each style corresponds to a different appearance, allowing for flexibility in how fonts are styled.
  *
- * @categoryDescription Fonts
- * Methods for managing font styles within the editor.
- *
  * @public
  */
 export declare type FontStyle = 'normal' | 'italic';
@@ -6789,9 +6760,6 @@ export declare type FontStyle = 'normal' | 'italic';
  * The FontWeight type defines the possible weights of a font within the Creative Editor SDK.
  * Each weight corresponds to a different thickness, allowing for flexibility in how fonts are styled.
  *
- * @categoryDescription Fonts
- * Methods for managing font weights within the editor.
- *
  * @public
  */
 export declare type FontWeight = 'thin' | 'extraLight' | 'light' | 'normal' | 'medium' | 'semiBold' | 'bold' | 'extraBold' | 'heavy';
@@ -6799,7 +6767,6 @@ export declare type FontWeight = 'thin' | 'extraLight' | 'light' | 'normal' | 'm
 /**
  * Represents a gradient color stop.
  *
- * @categoryDescription Gradient Color Stop
  * Defines a gradient color stop with a color and a stop position.
  * - 'color': The color value.
  * - 'stop': The relative position of the color within the gradient in the range [0, 1].
@@ -7240,7 +7207,6 @@ export declare type RGBA = [r: number, g: number, b: number, a: number];
 /**
  * Represents an RGBA color value.
  *
- * @categoryDescription RGBA Color
  * Defines an RGBA color value with components between 0 and 1.
  * - 'r': The red component.
  * - 'g': The green component.
@@ -7263,7 +7229,6 @@ export declare interface RGBAColor {
 /**
  * Represents an RGB color value.
  *
- * @categoryDescription RGB Color
  * Defines an RGB color value with components between 0 and 1.
  * - 'r': The red component.
  * - 'g': The green component.
@@ -7342,9 +7307,10 @@ export declare class SceneAPI {
      *
      * @category Scene Loading
      * @param sceneContent - The scene file contents, a base64 string.
+     * @param overrideEditorConfig - Whether to override editor configuration with settings and data from the scene file. Defaults to false.
      * @returns A handle to the loaded scene.
      */
-    loadFromString(sceneContent: string): Promise<DesignBlockId>;
+    loadFromString(sceneContent: string, overrideEditorConfig?: boolean): Promise<DesignBlockId>;
     /**
      * Load a scene from the URL to the scene file.
      *
@@ -7357,9 +7323,10 @@ export declare class SceneAPI {
      *
      * @category Scene Loading
      * @param url - The URL of the scene file.
+     * @param overrideEditorConfig - Whether to override editor configuration with settings and data from the scene file. Defaults to false.
      * @returns scene A promise that resolves once the scene was loaded or rejects with an error otherwise.
      */
-    loadFromURL(url: string): Promise<DesignBlockId>;
+    loadFromURL(url: string, overrideEditorConfig?: boolean): Promise<DesignBlockId>;
     /**
      * Load a previously archived scene from the URL to the scene file.
      *
@@ -7368,16 +7335,22 @@ export declare class SceneAPI {
      *
      * @category Scene Loading
      * @param url - The URL of the scene file.
+     * @param overrideEditorConfig - Whether to override editor configuration with settings and data from the scene file. Defaults to false.
      * @returns scene A promise that resolves once the scene was loaded or rejects with an error otherwise.
      */
-    loadFromArchiveURL(url: string): Promise<DesignBlockId>;
+    loadFromArchiveURL(url: string, overrideEditorConfig?: boolean): Promise<DesignBlockId>;
     /**
      * Serializes the current scene into a string. Selection is discarded.
      *
      * @category Scene Saving
+     * @param allowedResourceSchemes - The resource schemes to allow in the saved string. Defaults to ['blob', 'bundle', 'file', 'http', 'https', 'opfs'].
+     * @param onDisallowedResourceScheme - An optional callback that is called for each resource URL that has a scheme absent from
+     * `resourceSchemesAllowed`. The `url` parameter is the resource URL and the `dataHash` parameter is the hash of the
+     * resource's data. The callback should return a new URL for the resource, which will be used in the serialized
+     * scene. The callback is expected to return the original URL if no persistence is needed.
      * @returns A promise that resolves with a string on success or an error on failure.
      */
-    saveToString(allowedResourceSchemes?: string[]): Promise<string>;
+    saveToString(allowedResourceSchemes?: string[], onDisallowedResourceScheme?: (url: string, dataHash: string) => Promise<string>): Promise<string>;
     /**
      * Saves the current scene and all of its referenced assets into an archive.
      *
@@ -7965,7 +7938,6 @@ export declare type SettingsColorRGBA = SettingsColor;
 /**
  * Represents the enum settings available in the editor.
  *
- * @categoryDescription Enum Settings
  * Defines the possible enum settings in the editor.
  * - 'doubleClickSelectionMode': The mode for double-click selection.
  * - 'touch/pinchAction': The action for pinch gestures.
@@ -8089,7 +8061,6 @@ export declare interface Source {
 /**
  * Represents a spot color value.
  *
- * @categoryDescription Spot Color
  * Defines a spot color value with a name, tint, and external reference.
  * - 'name': The name of the spot color.
  * - 'tint': The tint factor.
@@ -8204,9 +8175,6 @@ export declare type TextCase = 'Normal' | 'Uppercase' | 'Lowercase' | 'Titlecase
  * The `TransientResource` interface provides a set of properties that describe a transient
  * resource, including a URI and the size of the resource.
  *
- * @categoryDescription TransientResource
- * Methods for working with transient resources.
- *
  * @public
  */
 export declare interface TransientResource {
@@ -8220,9 +8188,6 @@ export declare interface TransientResource {
  * The Typeface interface defines the structure of a typeface within the Creative Editor SDK.
  * It includes properties for the name and fonts.
  *
- * @categoryDescription Fonts
- * Methods for managing typefaces within the editor.
- *
  * @public
  */
 export declare interface Typeface {
@@ -8237,7 +8202,6 @@ export declare interface Typeface {
  *
  * @deprecated This type definition is not used anymore and will be removed.
  *
- * @categoryDescription Typeface Definition
  * Defines the structure of a typeface definition, including metadata, family name, and font details.
  * - 'meta': Optional metadata for the typeface, including default status, library, and categories.
  * - 'family': The name of the typeface family.
@@ -8349,7 +8313,6 @@ export declare type VerticalTextAlignment = 'Top' | 'Bottom' | 'Center';
 /**
  * Represents the options for exporting a video.
  *
- * @categoryDescription Video Export Options
  * Defines the possible options for exporting a video.
  * - 'mimeType': The MIME type of the output video file.
  * - 'onProgress': A callback which reports on the progress of the export.