@cesdk/engine 1.76.0-nightly.20260522 → 1.76.0-rc.1

package/index.d.ts

@@ -3640,6 +3640,25 @@ export declare class BlockAPI {
      * @param locked - Whether aspect ratio should be locked.
      */
     setCropAspectRatioLocked(id: DesignBlockId, locked: boolean): void;
+    /**
+     * Checks whether the "Original" crop preset (`ContentAspectRatio`) can be applied to a block.
+     *
+     * This runs the same preliminary check the apply path performs: it resolves the intrinsic
+     * content dimensions from the block's image/video fill (an image fill resolves only from its
+     * `sourceSet`; a video fill resolves from its `sourceSet` or the first decoded frame). Use it
+     * to gate UI that would otherwise call the preset and fail — e.g. an unreplaced placeholder
+     * image fill with an empty `sourceSet`.
+     *
+     * ```javascript
+     * const canRevert = engine.block.canRevertToOriginalRatio(block);
+     * ```
+     *
+     * @category Block Crop
+     * @param id - The block to query.
+     * @returns True if the preset would resolve, false if it cannot (no/placeholder fill, empty
+     * sourceSet, video not yet decoded, or unsupported fill type).
+     */
+    canRevertToOriginalRatio(id: DesignBlockId): boolean;
     /**
      * Checks if a block has an opacity property.
      *
@@ -6655,7 +6674,7 @@ export declare function _createReactiveProperty<T>(initialValue: T, options?: _R
  */
 export declare type CreateSceneOptions = {
     /** The page options */
-    page: {
+    page?: {
         /** The size of the page */
         size: number | {
             width: number;
@@ -6664,6 +6683,15 @@ export declare type CreateSceneOptions = {
         /** The background color of the page */
         color?: Color;
     };
+    /**
+     * The design unit of the new scene. Defaults to `Pixel`.
+     */
+    designUnit?: SceneDesignUnit;
+    /**
+     * The unit in which font sizes for `setTextFontSize` and `getTextFontSizes` are interpreted.
+     * If omitted, it is paired with `designUnit`: `Pixel` scenes get `Pixel`, all other scenes get `Point`.
+     */
+    fontSizeUnit?: SceneFontSizeUnit;
 };
 
 /**
@@ -7495,6 +7523,17 @@ export declare class EditorAPI {
      * @returns True if a redo step is available.
      */
     canRedo(): boolean;
+    /**
+     * Subscribe to undo/redo history changes.
+     *
+     * @deprecated Use {@link onHistoryUpdatedWithKind} instead, which additionally reports a {@link HistoryUpdate}
+     * describing the kind of update.
+     *
+     * @category Event Subscriptions
+     * @param callback - Function called when the undo/redo history changes.
+     * @returns A method to unsubscribe from the event.
+     */
+    onHistoryUpdated: (callback: () => void) => (() => void);
     /**
      * Subscribe to undo/redo history changes.
      *
@@ -7503,7 +7542,7 @@ export declare class EditorAPI {
      * via `setActiveHistory`.
      *
      * ```javascript
-     * const unsubscribe = engine.editor.onHistoryUpdated((kind) => {
+     * const unsubscribe = engine.editor.onHistoryUpdatedWithKind((kind) => {
      *   if (kind === 'Activated') {
      *     // The active history was switched; no scene change happened on this event.
      *     return;
@@ -7518,7 +7557,7 @@ export declare class EditorAPI {
      * @param callback - Function called when the undo/redo history changes. The argument describes the kind of update.
      * @returns A method to unsubscribe from the event.
      */
-    onHistoryUpdated: (callback: (kind: HistoryUpdate) => void) => (() => void);
+    onHistoryUpdatedWithKind: (callback: (kind: HistoryUpdate) => void) => (() => void);
     /**
      * Subscribe to editor settings changes.
      *
@@ -8656,7 +8695,7 @@ export declare type HexColorString = string;
 export declare type HistoryId = number;
 
 /**
- * Describes the kind of update that triggered an `onHistoryUpdated` callback.
+ * Describes the kind of update that triggered an `onHistoryUpdatedWithKind` callback.
  *
  * - `Updated`: The active history's snapshots changed: a new snapshot was added (e.g. after an edit), or undo/redo
  *   was applied. The scene state changed as a direct consequence.
@@ -9454,6 +9493,8 @@ export declare class SceneAPI {
      *
      * ```javascript
      * const scene = engine.scene.create(layout);
+     * // With a specific design unit and auto-paired font-size unit:
+     * const pxScene = engine.scene.create('Free', { designUnit: 'Pixel' });
      * ```
      *
      * @category Scene Creation
@@ -9462,6 +9503,9 @@ export declare class SceneAPI {
      *   - `page` - Page options. Properties:
      *     - `size` - The size of the page.
      *     - `color` - Optional background color of the page.
+     *   - `designUnit` - The design unit of the new scene. Defaults to `Pixel`.
+     *   - `fontSizeUnit` - The font-size unit. If omitted, paired with `designUnit`
+     *     (`Pixel` design unit → `Pixel` font unit, others → `Point`).
      * @returns The scene's handle.
      */
     create(sceneLayout?: SceneLayout, options?: CreateSceneOptions): DesignBlockId;
@@ -9605,6 +9649,30 @@ export declare class SceneAPI {
      * @returns The current design unit.
      */
     getDesignUnit(): SceneDesignUnit;
+    /**
+     * Sets the unit in which font sizes for `setTextFontSize` and `getTextFontSizes` are interpreted.
+     * The engine continues to store font sizes in points internally; this only affects how values
+     * are interpreted at the API boundary when callers don't specify a `unit` in `TextFontSizeOptions`.
+     *
+     * ```javascript
+     * engine.scene.setFontSizeUnit('Pixel');
+     * ```
+     *
+     * @category Scene Properties
+     * @param fontSizeUnit - The new font-size unit of the scene.
+     */
+    setFontSizeUnit(fontSizeUnit: SceneFontSizeUnit): void;
+    /**
+     * Returns the font-size unit of the current scene.
+     *
+     * ```javascript
+     * engine.scene.getFontSizeUnit();
+     * ```
+     *
+     * @category Scene Properties
+     * @returns The current font-size unit.
+     */
+    getFontSizeUnit(): SceneFontSizeUnit;
     /**
      * Get the layout of the current scene.
      *
@@ -9950,6 +10018,12 @@ export { SceneDesignUnit }
 /** @public */
 export declare const SceneDesignUnitValues: readonly ["Pixel", "Millimeter", "Inch"];
 
+/** @public */
+export declare type SceneFontSizeUnit = (typeof SceneFontSizeUnitValues)[number];
+
+/** @public */
+export declare const SceneFontSizeUnitValues: readonly ["Pixel", "Point"];
+
 /** @public */
 export declare type SceneLayout = (typeof SceneLayoutValues)[number];
 
@@ -9980,7 +10054,7 @@ export declare const SceneModeValues: readonly ["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 SettingBoolPropertyName = 'alwaysHighlightPlaceholders' | 'doubleClickToCropEnabled' | 'showBuildVersion' | 'placeholderControls/showButton' | 'placeholderControls/showOverlay' | 'blockAnimations/enabled' | 'renderTextCursorAndSelectionInEngine' | 'touch/dragStartCanSelect' | 'touch/singlePointPanning' | 'mouse/enableZoom' | 'mouse/enableScroll' | 'controlGizmo/showCropHandles' | 'controlGizmo/showMoveHandles' | 'controlGizmo/dynamicMoveHandleVisibility' | 'controlGizmo/showResizeHandles' | 'controlGizmo/showScaleHandles' | 'controlGizmo/showRotateHandles' | 'controlGizmo/showCropScaleHandles' | 'page/title/canEdit' | 'page/title/show' | 'page/title/showPageTitleTemplate' | 'page/title/appendPageName' | 'page/title/showOnSinglePage' | 'page/dimOutOfPageAreas' | 'page/allowCropInteraction' | 'page/allowResizeInteraction' | 'page/restrictResizeInteractionToFixedAspectRatio' | 'page/allowRotateInteraction' | 'page/allowMoveInteraction' | 'page/marqueeSelectOnBodyDrag' | 'page/restrictPageSelectionToBorderAndTitle' | 'page/moveChildrenWhenCroppingFill' | 'page/selectWhenNoBlocksSelected' | 'page/highlightWhenCropping' | 'page/highlightDropTarget' | 'page/reparentBlocksToSceneWhenOutOfPage' | 'colorMaskingSettings/secondPass' | 'clampThumbnailTextureSizes' | 'useSystemFontFallback' | 'forceSystemEmojis' | 'features/textEditModeTransformHandlesEnabled' | 'features/videoStreamingEnabled' | 'grid/enabled' | 'grid/snapEnabled' | 'features/enableAutomaticEnumerations' | 'features/transparentClickThroughEnabled' | 'features/fontLineGapEnabled' | (string & {});
+export declare type SettingBoolPropertyName = 'alwaysHighlightPlaceholders' | 'doubleClickToCropEnabled' | 'showBuildVersion' | 'placeholderControls/showButton' | 'placeholderControls/showOverlay' | 'blockAnimations/enabled' | 'playback/showAllBlocks' | 'renderTextCursorAndSelectionInEngine' | 'touch/dragStartCanSelect' | 'touch/singlePointPanning' | 'mouse/enableZoom' | 'mouse/enableScroll' | 'controlGizmo/showCropHandles' | 'controlGizmo/showMoveHandles' | 'controlGizmo/dynamicMoveHandleVisibility' | 'controlGizmo/showResizeHandles' | 'controlGizmo/showScaleHandles' | 'controlGizmo/showRotateHandles' | 'controlGizmo/showCropScaleHandles' | 'page/title/canEdit' | 'page/title/show' | 'page/title/showPageTitleTemplate' | 'page/title/appendPageName' | 'page/title/showOnSinglePage' | 'page/dimOutOfPageAreas' | 'page/allowCropInteraction' | 'page/allowResizeInteraction' | 'page/restrictResizeInteractionToFixedAspectRatio' | 'page/allowRotateInteraction' | 'page/allowMoveInteraction' | 'page/marqueeSelectOnBodyDrag' | 'page/restrictPageSelectionToBorderAndTitle' | 'page/moveChildrenWhenCroppingFill' | 'page/selectWhenNoBlocksSelected' | 'page/highlightWhenCropping' | 'page/highlightDropTarget' | 'page/reparentBlocksToSceneWhenOutOfPage' | 'colorMaskingSettings/secondPass' | 'clampThumbnailTextureSizes' | 'useSystemFontFallback' | 'forceSystemEmojis' | 'features/textEditModeTransformHandlesEnabled' | 'features/videoStreamingEnabled' | 'grid/enabled' | 'grid/snapEnabled' | 'features/enableAutomaticEnumerations' | 'features/transparentClickThroughEnabled' | 'features/fontLineGapEnabled' | (string & {});
 
 /** @public */
 export declare type SettingColorPropertyName = 'clearColor' | 'handleFillColor' | 'highlightColor' | 'pageHighlightColor' | 'placeholderHighlightColor' | 'snappingGuideColor' | 'rotationSnappingGuideColor' | 'cropOverlayColor' | 'textVariableHighlightColor' | 'borderOutlineColor' | 'progressColor' | 'errorStateColor' | 'page/title/color' | 'page/marginFillColor' | 'page/marginFrameColor' | 'page/innerBorderColor' | 'page/outerBorderColor' | 'colorMaskingSettings/maskColor' | 'grid/color' | (string & {});
@@ -10100,6 +10174,11 @@ export declare interface Settings {
     'placeholderControls/showOverlay': boolean;
     /** Whether animations should be enabled or not. */
     'blockAnimations/enabled': boolean;
+    /**
+     * When enabled, every block stays visible regardless of the current playback time, instead of being
+     * culled outside its time offset/duration. No effect on export.
+     */
+    'playback/showAllBlocks': boolean;
     /** Whether the background grid is shown on pages. */
     'grid/enabled': boolean;
     /** Whether elements should snap to grid lines when dragged. */
@@ -10606,7 +10685,10 @@ export declare type TextDecorationStyle = 'Solid' | 'Double' | 'Dotted' | 'Dashe
  * @public
  */
 export declare interface TextFontSizeOptions {
-    /** The unit of the font size. Defaults to 'Point' */
+    /**
+     * The unit of the font size. Defaults to the scene's `fontSizeUnit`
+     * (configured via `engine.scene.setFontSizeUnit()`), which itself defaults to `'Point'`.
+     */
     unit?: FontSizeUnit;
     /** The start index of the UTF-16 range. Defaults to -1 (start of selection/text) */
     from?: number;