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

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

@@ -4419,6 +4419,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 +4514,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 +4661,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();
@@ -5920,10 +5966,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.
@@ -7309,6 +7356,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 +7501,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 +7570,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 +7988,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 +8101,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 +8198,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 +8320,7 @@ export declare class SceneAPI {
         allowedResourceSchemes?: string[];
         onDisallowedResourceScheme?: (url: string, dataHash: string) => Promise<string>;
         compression?: {
-            format?: CompressionFormat;
+            format?: CompressionFormat_2;
             level?: CompressionLevel;
         };
     }): Promise<string>;
@@ -9445,6 +9593,8 @@ declare interface UBQExportOptions {
     exportPdfWithUnderlayer: boolean;
     underlayerSpotColorName: string;
     underlayerOffset: number;
+    underlayerRenderRatio: number;
+    underlayerMaxError: number;
     allowTextOverhang: boolean;
     exportPdfWithDeviceCMYK: boolean;
 }