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

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.
      *
@@ -4769,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.
      *
@@ -6259,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];
 
@@ -8866,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 & {});