@cesdk/node 1.75.0-nightly.20260424 → 1.75.0-nightly.20260429

package/README.md

@@ -23,10 +23,15 @@ npm install --save @cesdk/node
 ```
 
 or with `yarn`
-```bash 
+```bash
 yarn add @cesdk/node
 ```
 
+or with `pnpm`
+```bash
+pnpm add @cesdk/node
+```
+
 ## 2. Instantiate Creative Engine
 The last step involves the configuration and instantiation of the SDK.
 

package/index.d.ts

@@ -1452,6 +1452,22 @@ export declare class BlockAPI {
      * ```
      */
     export(handle: DesignBlockId, mimeType?: ExportOptions['mimeType'], options?: Omit<ExportOptions, 'mimeType'>): Promise<Blob>;
+    /**
+     * Extracts the dominant colors from the rendered appearance of a block.
+     *
+     * Performs an internal update to resolve the final layout for the block. Will not
+     * complete as long as assets are in a pending state; asset loading progresses during
+     * engine updates. Crops, color adjustments, and effects applied to the block are
+     * reflected in the returned palette. Fully or mostly transparent pixels are excluded
+     * from the analysis.
+     *
+     * @category Block Analysis
+     * @param handle - The design block element to analyze. Must be attached to a scene
+     * and render visible content.
+     * @param options - See `DominantColorsOptions`.
+     * @returns A promise that resolves with the dominant colors sorted by weight, descending.
+     */
+    getDominantColors(handle: DesignBlockId, options?: DominantColorsOptions): Promise<DominantColor[]>;
     /**
      * Exports a design block and a color mask to two separate Blobs.
      *
@@ -2043,6 +2059,21 @@ export declare class BlockAPI {
      * @returns A list of block ids.
      */
     findAllPlaceholders(): DesignBlockId[];
+    /**
+     * Finds all blocks that are not attached to any scene.
+     *
+     * A block is considered unused when it has no path to a scene (no scene
+     * reference and no ancestor that belongs to a scene) and is not itself a
+     * scene. Generated blocks and render blocks (fills, effects, shapes, blurs)
+     * are excluded, matching the behaviour of {@link BlockAPI.findAll}.
+     *
+     * This is useful for cleanup workflows and for filtering the URIs returned
+     * by {@link EditorAPI.findAllMediaURIs} before relocating resources.
+     *
+     * @category Block Exploration
+     * @returns A list of block ids that are not attached to any scene.
+     */
+    findAllUnused(): DesignBlockId[];
     /**
      * Creates a new shape block of a given type.
      *
@@ -3825,6 +3856,34 @@ export declare class BlockAPI {
      * @returns True if the block's stroke is enabled.
      */
     isStrokeEnabled(id: DesignBlockId): boolean;
+    /**
+     * Marks the stroke of a block as overprint for PDF export.
+     *
+     * The flag is only honored by the PDF writer when the stroke uses a spot color
+     * (Separation/DeviceN). For process-color strokes it is a silent no-op. On-screen
+     * rendering ignores the flag.
+     *
+     * ```javascript
+     * engine.block.setStrokeOverprint(block, true);
+     * ```
+     *
+     * @category Block Strokes
+     * @param id - The block whose stroke overprint flag should be set.
+     * @param overprint - If true, the stroke is marked as overprint in exported PDFs.
+     */
+    setStrokeOverprint(id: DesignBlockId, overprint: boolean): void;
+    /**
+     * Queries whether the stroke of a block is marked as overprint for PDF export.
+     *
+     * ```javascript
+     * const overprint = engine.block.getStrokeOverprint(block);
+     * ```
+     *
+     * @category Block Strokes
+     * @param id - The block whose stroke overprint flag should be queried.
+     * @returns The stroke overprint flag.
+     */
+    getStrokeOverprint(id: DesignBlockId): boolean;
     /**
      * Sets the stroke color of a block using RGBA values.
      *
@@ -4419,6 +4478,41 @@ export declare class BlockAPI {
      * @param to - The end index of the UTF-16 range. Defaults to the end of the current selection or text.
      */
     toggleTextDecorationOverline(id: DesignBlockId, from?: number, to?: number): void;
+    /**
+     * Gets the paragraph-level horizontal alignment override for a specific paragraph,
+     * or the block-level alignment.
+     *
+     * ```javascript
+     * const alignment = engine.block.getTextHorizontalAlignment(text, 0);
+     * const blockAlignment = engine.block.getTextHorizontalAlignment(text); // paragraphIndex defaults to -1
+     * // e.g. 'Left' | 'Center' | 'Right' | 'Auto' | undefined
+     * ```
+     *
+     * @category Block Text
+     * @param id - The text block to query.
+     * @param paragraphIndex - The 0-based index of the paragraph to query.
+     * Negative values return the block-level `text/horizontalAlignment` setting.
+     * @returns The paragraph override, `undefined` if no override is set,
+     * or the block-level alignment when `paragraphIndex < 0`.
+     */
+    getTextHorizontalAlignment(id: DesignBlockId, paragraphIndex?: number): TextHorizontalAlignment | undefined;
+    /**
+     * Sets the paragraph-level horizontal alignment override for one or all paragraphs.
+     *
+     * ```javascript
+     * engine.block.setTextHorizontalAlignment(text, 'Center', 0);
+     * engine.block.setTextHorizontalAlignment(text, undefined, 0); // clear override
+     * engine.block.setTextHorizontalAlignment(text, 'Right'); // apply to all
+     * ```
+     *
+     * @category Block Text
+     * @param id - The text block to modify.
+     * @param alignment - The alignment to apply, or `undefined` to clear the paragraph override.
+     * @param paragraphIndex - The 0-based index of the paragraph.
+     * Negative values clear all paragraph-level alignment overrides and, when `alignment` is provided,
+     * apply that alignment to the whole text block.
+     */
+    setTextHorizontalAlignment(id: DesignBlockId, alignment: TextHorizontalAlignment | undefined, paragraphIndex?: number): void;
     /**
      * Gets the list style for a specific paragraph of a text block.
      *
@@ -4479,15 +4573,23 @@ export declare class BlockAPI {
     /**
      * Returns the 0-based paragraph indices that overlap the given UTF-16 range.
      *
+     * The range is half-open (exclusive): `from` is inclusive, `to` is exclusive (one past the last
+     * code unit of interest). When `from === to` the range is a cursor position and the paragraph
+     * containing `from` is returned. This convention matches `getTextCursorRange`, so the values
+     * it returns can be passed directly without adjustment.
+     *
+     * Negative values for either parameter cause all paragraph indices to be returned.
+     *
      * ```javascript
      * const indices = engine.block.getTextParagraphIndices(text);
-     * const indices = engine.block.getTextParagraphIndices(text, 0, 5);
+     * const { from, to } = engine.block.getTextCursorRange();
+     * const indices = engine.block.getTextParagraphIndices(text, from, to);
      * ```
      *
      * @category Block Text
      * @param id - The text block to query.
-     * @param from - The start index of the UTF-16 range. Negative values reference the entire text.
-     * @param to - The end index of the UTF-16 range. Negative values reference the entire text.
+     * @param from - The inclusive start UTF-16 index. Negative values reference the entire text.
+     * @param to - The exclusive end UTF-16 index. Negative values reference the entire text.
      * @returns The paragraph indices overlapping the range.
      */
     getTextParagraphIndices(id: DesignBlockId, from?: number, to?: number): number[];
@@ -4618,7 +4720,10 @@ export declare class BlockAPI {
     /**
      * Gets the current text cursor or selection range.
      *
-     * Returns the UTF-16 indices of the selected range of the text block that is currently being edited.
+     * Returns the UTF-16 indices of the selected range of the text block that is currently being
+     * edited. The range is half-open (exclusive): `from` is the index of the first selected code
+     * unit, `to` is one past the last selected code unit. When `from === to` the cursor is
+     * positioned between characters with no text selected.
      *
      * ```javascript
      * const selectedRange = engine.block.getTextCursorRange();
@@ -4723,6 +4828,34 @@ export declare class BlockAPI {
      * @param enabled - If true, the fill will be enabled.
      */
     setFillEnabled(id: DesignBlockId, enabled: boolean): void;
+    /**
+     * Queries whether the fill of a block is marked as overprint for PDF export.
+     *
+     * ```javascript
+     * const overprint = engine.block.getFillOverprint(block);
+     * ```
+     *
+     * @category Block Fills
+     * @param id - The block whose fill overprint flag should be queried.
+     * @returns The fill overprint flag.
+     */
+    getFillOverprint(id: DesignBlockId): boolean;
+    /**
+     * Marks the fill of a block as overprint for PDF export.
+     *
+     * The flag is only honored by the PDF writer when the fill uses a spot color
+     * (Separation/DeviceN). For process-color fills it is a silent no-op. On-screen
+     * rendering ignores the flag.
+     *
+     * ```javascript
+     * engine.block.setFillOverprint(block, true);
+     * ```
+     *
+     * @category Block Fills
+     * @param id - The block whose fill overprint flag should be set.
+     * @param overprint - If true, the fill is marked as overprint in exported PDFs.
+     */
+    setFillOverprint(id: DesignBlockId, overprint: boolean): void;
     /**
      * Gets the fill block attached to a given block.
      *
@@ -5920,10 +6053,11 @@ export declare interface CompleteAssetResult extends AssetResult {
  * Compression format for scene serialization.
  * @public
  */
-export declare enum CompressionFormat {
+declare enum CompressionFormat_2 {
     None = 0,
     Zstd = 1
 }
+export { CompressionFormat_2 as CompressionFormat }
 
 /**
  * Compression level for scene serialization.
@@ -6212,6 +6346,50 @@ export declare type DesignBlockTypeLonghand = `//ly.img.ubq/${DesignBlockTypeSho
 /** @public */
 export declare type DesignBlockTypeShorthand = (typeof DESIGN_BLOCK_TYPES)[number];
 
+/**
+ * A single color extracted from the rendered appearance of a block.
+ *
+ * @public
+ */
+export declare interface DominantColor {
+    /** Red component in sRGB, normalized to the range [0, 1]. */
+    r: number;
+    /** Green component in sRGB, normalized to the range [0, 1]. */
+    g: number;
+    /** Blue component in sRGB, normalized to the range [0, 1]. */
+    b: number;
+    /**
+     * Share of analyzed pixels represented by this color, in the range [0, 1].
+     * Higher values indicate a more prominent color. The sum of weights returned
+     * by a single `BlockAPI.getDominantColors` call is `1.0`.
+     */
+    weight: number;
+}
+
+/**
+ * Options for `BlockAPI.getDominantColors`.
+ *
+ * @public
+ */
+export declare interface DominantColorsOptions {
+    /**
+     * Number of dominant colors to extract.
+     * The returned palette may contain fewer entries for images with very little variation,
+     * and is empty when `count` is `0`.
+     *
+     * @defaultValue 5
+     */
+    count?: number;
+    /**
+     * If `true`, near-white pixels are excluded from the analysis.
+     * Useful when analyzing images on white backgrounds to avoid the background
+     * dominating the result.
+     *
+     * @defaultValue false
+     */
+    ignoreWhite?: boolean;
+}
+
 /** @public */
 export declare type DoubleClickSelectionMode = (typeof DoubleClickSelectionModeValues)[number];
 
@@ -7309,6 +7487,50 @@ export declare class EditorAPI {
      * @param enabled - Whether the block should be selectable.
      */
     setSelectionEnabled(id: DesignBlockId, enabled: boolean): void;
+    /**
+     * Set one or more rules that limit how far blocks can be positioned outside their
+     * parent page during user interactions (drag, resize, touch gestures, crop).
+     * Programmatic API calls are not affected.
+     *
+     * `overshoot` is a non-negative fraction of the moved block's own size: `0`
+     * pins blocks fully inside the page, `0.3` allows 30% to extend past the page
+     * bounds. Each rule's scope is determined by its keys:
+     * - `{ overshoot }` — scene-wide default for every page in the scene.
+     * - `{ overshoot, block }` — applies to a specific block. Pages are blocks, so
+     *   setting this on a page acts as the default for blocks inside that page.
+     * - `{ overshoot, blockType }` — applies to every block of the given type
+     *   (e.g. `"text"` or `"//ly.img.ubq/text"`).
+     *
+     * Use `removeMovementConstraint` to clear a rule.
+     *
+     * When multiple rules match a block, the most specific one wins:
+     * block \> parent page \> blockType \> scene-wide.
+     *
+     * @param rules - A single rule or an array of rules to apply.
+     */
+    setMovementConstraint(rules: MovementConstraintRule | MovementConstraintRule[]): void;
+    /**
+     * Get the effective movement constraint for a block, picking the most specific
+     * matching rule: block \> parent page \> blockType \> scene-wide.
+     *
+     * The returned `overshoot` is a fraction of the block's own size.
+     *
+     * @param id - The block to query.
+     * @returns `{ overshoot }` with the effective value, or `null` if unconstrained.
+     */
+    getMovementConstraint(id: DesignBlockId): ResolvedMovementConstraint;
+    /**
+     * Remove previously set movement constraints.
+     *
+     * - No argument: removes the scene-wide default.
+     * - `{ block }` / `{ blockType }` (or an array): removes the matching scope(s).
+     *
+     * Removing a scope falls through to the next tier on subsequent resolution.
+     *
+     * @param scopes - Scope or array of scopes to remove. Omit to remove the
+     *                 scene-wide default.
+     */
+    removeMovementConstraint(scopes?: MovementConstraintScope | MovementConstraintScope[]): void;
 }
 
 /**
@@ -7410,6 +7632,8 @@ export declare class EventAPI {
  * - 'exportPdfWithUnderlayer': Export the PDF document with an underlayer.
  * - 'underlayerSpotColorName': The name of the spot color to be used for the underlayer's fill.
  * - 'underlayerOffset': The adjustment in size of the shape of the underlayer.
+ * - 'underlayerRenderRatio': Resolution multiplier for the underlayer contour extraction.
+ * - 'underlayerMaxError': Curve-fit error tolerance for the underlayer contour.
  * - 'abortSignal': An abort signal that can be used to cancel the export.
  *
  * @public
@@ -7477,6 +7701,26 @@ export declare type ExportOptions = {
      * The adjustment in size of the shape of the underlayer.
      */
     underlayerOffset?: number;
+    /**
+     * Resolution multiplier for the raster pass that extracts the underlayer contour.
+     * Higher values produce sharper underlayer outlines at the cost of memory and export time.
+     * Useful for small text on large pages, where the 1.0 default can miss fine glyph details.
+     * Values `<= 0` fall back to 1.0. `NaN` / `Infinity` are rejected at the binding boundary
+     * with a `StructError`; pass a real number or leave the field undefined to use the default.
+     *
+     * @defaultValue 1.0
+     */
+    underlayerRenderRatio?: number;
+    /**
+     * Maximum acceptable curve-fit error, in pixels, when vectorising the underlayer contour.
+     * Smaller values produce tighter fits at the cost of more path complexity.
+     * Useful together with `underlayerRenderRatio` for small text on large pages.
+     * Values `<= 0` fall back to 2.0. `NaN` / `Infinity` are rejected at the binding boundary
+     * with a `StructError`; pass a real number or leave the field undefined to use the default.
+     *
+     * @defaultValue 2.0
+     */
+    underlayerMaxError?: number;
     /**
      * If true, the export will include text bounding boxes that account for glyph overhangs.
      * When enabled, text blocks with glyphs that extend beyond their frame (e.g., decorative fonts with swashes)
@@ -7875,6 +8119,33 @@ declare const MimeType_2: {
 declare type MimeType_2 = (typeof MimeType_2)[keyof typeof MimeType_2];
 export { MimeType_2 as MimeType }
 
+/**
+ * A movement constraint rule. The scope is determined by which key is present:
+ * neither (scene-wide default), `block` (per-block, includes pages), or
+ * `blockType` (per-block-type).
+ *
+ * `overshoot` is a non-negative fraction of the moved block's own size.
+ */
+declare type MovementConstraintRule = {
+    overshoot: number;
+} | {
+    overshoot: number;
+    block: DesignBlockId;
+} | {
+    overshoot: number;
+    blockType: string;
+};
+
+/**
+ * A scope descriptor used to identify an existing movement constraint for
+ * removal.
+ */
+declare type MovementConstraintScope = {
+    block: DesignBlockId;
+} | {
+    blockType: string;
+};
+
 /**
  * The block type IDs for all blocks types in the Creative Engine. Those are the types that can be
  * passed to `cesdk.engine.block.findByType(type)` for example.
@@ -7961,6 +8232,14 @@ declare interface Range_2 {
 }
 export { Range_2 as Range }
 
+/**
+ * The effective movement constraint for a block, or `null` when no constraint
+ * applies.
+ */
+declare type ResolvedMovementConstraint = {
+    overshoot: number;
+} | null;
+
 /**
  * Represents a color in the RGBA color space.
  *
@@ -8050,7 +8329,7 @@ declare interface SaveToStringOptions {
      */
     compression?: {
         /** Compression format (None = no compression, Zstd = zstd compression) */
-        format?: CompressionFormat;
+        format?: CompressionFormat_2;
         /** Compression level (Fastest, Default, Best) */
         level?: CompressionLevel;
     };
@@ -8172,7 +8451,7 @@ export declare class SceneAPI {
         allowedResourceSchemes?: string[];
         onDisallowedResourceScheme?: (url: string, dataHash: string) => Promise<string>;
         compression?: {
-            format?: CompressionFormat;
+            format?: CompressionFormat_2;
             level?: CompressionLevel;
         };
     }): Promise<string>;
@@ -8718,7 +8997,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' | (string & {});
+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' | (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 & {});
@@ -9445,6 +9724,8 @@ declare interface UBQExportOptions {
     exportPdfWithUnderlayer: boolean;
     underlayerSpotColorName: string;
     underlayerOffset: number;
+    underlayerRenderRatio: number;
+    underlayerMaxError: number;
     allowTextOverhang: boolean;
     exportPdfWithDeviceCMYK: boolean;
 }