@cesdk/engine 1.32.0 → 1.33.0-rc.0

package/index.d.ts

@@ -286,7 +286,7 @@ export declare type AssetMetaData = {
  */
 export declare interface AssetNumberProperty {
     property: string;
-    type: 'Integer' | 'Float' | 'Double';
+    type: 'Int' | 'Float' | 'Double';
     value: number;
     defaultValue: number;
     min: number;
@@ -2916,47 +2916,12 @@ export declare interface Buffer {
     buffer: Uint8Array;
 }
 
-declare type CameraSettings = {
-    /** Horizontal resolution in physical pixels */
-    width: number;
-    /** Vertical resolution in physical pixels */
-    height: number;
-    /** Physical pixels per CSS pixel */
-    pixelRatio: number;
-};
-
 /**
  * An HTML Canvas or an Offscreen Canvas
  * @public
  */
 export declare type Canvas = HTMLCanvasElement | OffscreenCanvas_2;
 
-/**
- * A Channel represents a reactive data source consisting of three elements:
- *
- * * A `subscribe` method to register a callback for values coming from the
- *   data source. Calling this method returns an `unsubscribe` method.
- * * An (optional) `update` method to update the data source
- * * An (optional) synchronous `value` method that can be used to retrieve
- *   the current value.
- * @public
- */
-declare interface Channel<Out, In = Out> {
-    subscribe: Source_2<Out>;
-    update?: (v: In) => void;
-    value?: () => Out;
-}
-
-/**
- * A {@link Channel} that is guaranteed to have a `value` method
- * @public
- */
-declare interface ChannelSync<Out, In = Out> extends Channel<Out, In> {
-    subscribe: Source_2<Out>;
-    update?: (v: In) => void;
-    value: () => Out;
-}
-
 /**
  * @public
  */
@@ -3325,7 +3290,7 @@ declare class CreativeEngine {
     event: EventAPI;
     scene: SceneAPI;
     variable: VariableAPI;
-
+    reactor: Reactor;
 
     /**
      * Adds and initializes a plugin to the engine.
@@ -3344,6 +3309,7 @@ declare class CreativeEngine {
     unstable_setVideoExportInactivityTimeout(timeout: number): void;
 
 
+
     /**
      * Install the mousewheel event handler for the CreativeEngine on a different
      * element than the canvas.
@@ -3931,6 +3897,28 @@ export declare class EditorAPI {
      * @throws An error if the resource could not be downloaded or the mimetype could not be determined.
      */
     getMimeType(uri: string): Promise<string>;
+    /**
+     * Returns the URLs and sizes of all resources whose data would be lost if the scene was exported.
+     * This function is useful for determining which resources need to be relocated (e.g., to a CDN) before
+     * exporting a scene since the resources are not included in the exported scene.
+     * @returns The URLs and sizes of transient resources.
+     */
+    findAllTransientResources(): TransientResource[];
+    /**
+     * Provides the data of a resource at the given URL.
+     * @param url - The URL of the resource.
+     * @param chunkSize - The size of the chunks in which the resource data is provided.
+     * @param onData - The callback function that is called with the resource data or an error if an error occurred.
+     * The callback will be called as long as there is data left to provide and the callback returns `true`.
+     */
+    getResourceData(uri: string, chunkSize: number, onData: (result: Uint8Array) => boolean): void;
+    /**
+     * Changes the URL associated with a resource.
+     * This function can be used change the URL of a resource that has been relocated (e.g., to a CDN).
+     * @param currentURL - The current URL of the resource.
+     * @param relocatedURL - The new URL of the resource.
+     */
+    relocateResource(currentUrl: string, relocatedUrl: string): void;
 }
 
 /**
@@ -4154,12 +4142,6 @@ b: number,
 a: number
 ];
 
-/**
- * Will be called by a stream whenever a new value is available.
- * @public
- */
-declare type Handler<T> = (v: T) => void;
-
 /**
  * A hexadecimal color value (RGB or RGBA) that starts with a '#'
  * @example #6686FF or #6686FFFF
@@ -4346,41 +4328,94 @@ declare interface Range_2 {
 export { Range_2 as Range }
 
 /**
- * A Read only {@link Channel}
- * @public
- */
-declare interface ReadOnlyChannel<Out> extends Omit<Channel<Out>, 'update'> {
-    subscribe: Source_2<Out>;
-    value?: () => Out;
-}
-
-/**
- * A {@link ReadOnlyChannel} that is guaranteed to have a `value`
- * @public
- */
-declare interface ReadOnlyChannelSync<Out> extends Omit<ChannelSync<Out>, 'update'>, ReadOnlyChannel<Out> {
-    subscribe: Source_2<Out>;
-    value: () => Out;
-}
-
-/**
- * A {@link Channel} that is guaranteed to have an `update` method.
+ * Reactions track read calls and provide a way to react if they change.
+ *
+ * - Read calls are tracked by passing a function to `track`. That function
+ *   will be executed, and any read calls made during that execution will be
+ *   tracked and associated with this reaction.
+ * - Reactions can be subscribed to by passing a callback to `subscribe`. That
+ *   callback will be executed whenever any of the read calls associated with
+ *   this reaction change.
+ *
  * @public
  */
-declare interface ReadWriteChannel<Out, In = Out> extends Channel<Out, In> {
-    subscribe: Source_2<Out>;
-    update: (v: In) => void;
-    value?: () => Out;
+export declare interface Reaction {
+    /**
+     * Execute the callback and track all engine read calls that happen during
+     * the execution. These read calls are associated with this reaction.
+     */
+    track<T>(cb: () => T): T;
+    /**
+     * When the Reactor detects that the engine read calls associated with this
+     * reaction might have changed, it will invoke the subscription handler.
+     * @returns A function that can be called to unsubscribe the handler.
+     */
+    subscribe(cb: () => void): () => void;
+    /**
+     * Unsubscribe all handlers, nullify the reference to the Reactor
+     * and dispose the reaction.
+     */
+    dispose(): void;
 }
 
 /**
- * A {@link ReadWriteChannel} that is guaranteed to have a `value` and an `update` method
+ * The reactor coordinates the update of registered _Reactions_.
+ *
+ * - Reactions are created with `createReaction()`
+ * - `reactor.decorateObject(object)` will register all functions on an object marked with
+ *   `@getter` as read calls. If these are called during reaction tracking, their
+ *   arguments and return values will be stored so that changes can be detected later.
+ * - `reactor.decorateFunction` does the same, but for individual functions
+ * - `reaction.track(effect)` will run the effect and associate any engine read
+ *   calls during the execution with the Reaction.
+ * - `reaction.subscribe(handler)` will invoke the handler whenever the engine read calls
+ *   in the reaction might have changed after an update.
+ *
  * @public
  */
-declare interface ReadWriteChannelSync<Out, In = Out> extends ChannelSync<Out, In>, ReadWriteChannel<Out, In> {
-    subscribe: Source_2<Out>;
-    update: (v: In) => void;
-    value: () => Out;
+export declare interface Reactor {
+    /**
+     * Decorate a single function to be tracked by the reactor.
+     * @param func - The function to decorate.
+     * @param fnName - Name of the function to decorate. Used to generate the
+     *                 callId, so make sure it's unique with regard to its context.
+     * @returns The decorated function. Calling this function will track the call
+     *          in the Reactor and provide caching in reactions.
+     */
+    decorateFunction<A extends any[], R>(func: (...args: A) => R, fnName?: string): (...args: A) => R;
+    /**
+     * Decorate all marked `@getter` and `@setter` functions to be tracked by the reactor
+     *
+     * All functions on the object that are marked with `@getter` will be tracked
+     * during reaction tracking.
+     *
+     * @returns A function that can be called to stop tracking the object.
+     */
+    decorateObject<T extends object>(object: T): () => void;
+    /**
+     * Create and return a new Reaction that is associated with this Reactor.
+     */
+    createReaction(debugName?: string): Reaction;
+    /**
+     * Dispose the reactor and all reactions.
+     * After this call, the reactor is no longer usable.
+     */
+    dispose(): void;
+    /**
+     * A promise that will resolve after the next update of the Reactor.
+     *
+     * This can be used to wait for the next update of the Reactor in an async function.
+     *
+     * ```ts
+     * await reactor.nextReaction;
+     * ```
+     *
+     * This is useful in situations where you want to make sure that the effects of
+     * a reactor update have propagated to any dependent code before continuing.
+     * Particularly, this can be used to ensure that the UI has updated before
+     * continuing with other operations.
+     */
+    nextReaction: Promise<void>;
 }
 
 /**
@@ -4546,20 +4581,21 @@ export declare class SceneAPI {
      */
     getPages(): DesignBlockId[];
     /**
-     * Get the current page, i.e., the page nearest to the view port center.
+     * Get the current page, i.e., the page of the first selected element if this page
+     * is at least 25% visible or, otherwise, the page nearest to the viewport center.
      * @returns The current page in the scene or null.
      */
     getCurrentPage(): DesignBlockId | null;
     /**
-     * Find all blocks with the given type sorted by the distance to view port center.
+     * Find all blocks with the given type sorted by the distance to viewport center.
      * @param type - The type to search for.
-     * @returns A list of block ids sorted by distance to view port center.
+     * @returns A list of block ids sorted by distance to viewport center.
      */
     findNearestToViewPortCenterByType(type: DesignBlockType): DesignBlockId[];
     /**
-     * Find all blocks with the given kind sorted by the distance to view port center.
+     * Find all blocks with the given kind sorted by the distance to viewport center.
      * @param kind - The kind to search for.
-     * @returns A list of block ids sorted by distance to view port center.
+     * @returns A list of block ids sorted by distance to viewport center.
      */
     findNearestToViewPortCenterByKind(kind: string): DesignBlockId[];
     /**
@@ -4717,7 +4753,7 @@ export declare type SceneMode = 'Design' | 'Video';
 export declare type Scope = 'text/edit' | 'text/character' | 'fill/change' | 'fill/changeType' | 'stroke/change' | 'shape/change' | 'layer/move' | 'layer/resize' | 'layer/rotate' | 'layer/flip' | 'layer/crop' | 'layer/opacity' | 'layer/blendMode' | 'layer/visibility' | 'layer/clipping' | 'appearance/adjustments' | 'appearance/filter' | 'appearance/effect' | 'appearance/blur' | 'appearance/shadow' | 'appearance/animation' | 'lifecycle/destroy' | 'lifecycle/duplicate' | 'editor/add' | 'editor/select';
 
 /** @public */
-export declare type SettingsBool = 'controlGizmo/showCropHandles' | 'controlGizmo/showCropScaleHandles' | 'controlGizmo/showResizeHandles' | 'controlGizmo/showRotateHandles' | 'controlGizmo/showScaleHandles' | 'doubleClickToCropEnabled' | 'features/singlePageModeEnabled' | 'features/pageCarouselEnabled' | 'mouse/enableScroll' | 'mouse/enableZoom' | 'checkScopesInAPIs' | 'page/dimOutOfPageAreas' | 'page/title/appendPageName' | 'page/title/show' | 'page/title/showOnSinglePage' | 'page/title/showPageTitleTemplate' | 'placeholderControls/showButton' | 'placeholderControls/showOverlay' | 'blockAnimations/enabled' | 'showBuildVersion' | 'touch/dragStartCanSelect' | 'touch/singlePointPanning';
+export declare type SettingsBool = 'controlGizmo/showCropHandles' | 'controlGizmo/showCropScaleHandles' | 'controlGizmo/showMoveHandles' | 'controlGizmo/showResizeHandles' | 'controlGizmo/showRotateHandles' | 'controlGizmo/showScaleHandles' | 'doubleClickToCropEnabled' | 'features/singlePageModeEnabled' | 'features/pageCarouselEnabled' | 'mouse/enableScroll' | 'mouse/enableZoom' | 'checkScopesInAPIs' | 'page/dimOutOfPageAreas' | 'page/title/appendPageName' | 'page/title/show' | 'page/title/showOnSinglePage' | 'page/title/showPageTitleTemplate' | 'placeholderControls/showButton' | 'placeholderControls/showOverlay' | 'blockAnimations/enabled' | 'showBuildVersion' | 'touch/dragStartCanSelect' | 'touch/singlePointPanning';
 
 /** @public
  */
@@ -4798,17 +4834,6 @@ export declare interface Source {
     height: number;
 }
 
-/**
- * A stream source.
- *
- * This is an ordinary function. Pass a handler to have that handler called by
- * the source whenever a new value is available.
- *
- * Returns a function that unsubscribes the handler from the source
- * @public
- */
-declare type Source_2<T> = (handler: Handler<T>) => UnsubscribeFn;
-
 /** @public */
 export declare interface SpotColor {
     name: string;
@@ -4860,6 +4885,12 @@ export declare function supportsWasm(): boolean;
  */
 export declare type TextCase = 'Normal' | 'Uppercase' | 'Lowercase' | 'Titlecase';
 
+/** @public */
+export declare interface TransientResource {
+    uri: string;
+    size: number;
+}
+
 /** @public */
 export declare interface Typeface {
     /** The unique name of this typeface */
@@ -4885,12 +4916,6 @@ export declare type TypefaceDefinition = {
 
 declare type _TypefaceDefinition = TypefaceDefinition;
 
-/**
- * Invoke to unsubscribe from a stream.
- * @public
- */
-declare type UnsubscribeFn = () => void;
-
 /**
  * @public
  */