@canva/design 2.4.1-beta.2 → 2.6.0-beta.1

package/beta.d.ts

@@ -348,17 +348,45 @@ export declare interface ContentDraft<T> {
   save(): Promise<void>;
 }
 
+/**
+ * @beta
+ * Object for interacting with fill content (images/videos).
+ */
+export declare type ContentFill = (
+  | Omit<ImageFill, "altText">
+  | Omit<VideoFill, "altText">
+) & {
+  /**
+   * Indicates whether the fill object has been deleted.
+   */
+  deleted: boolean;
+};
+
+/**
+ * @beta
+ * Session for reading and updating fill content in a user's design.
+ */
+export declare interface ContentFillSession {
+  readonly contents: readonly ContentFill[];
+  sync(): Promise<void>;
+}
+
+/**
+ * @beta
+ */
+export declare type ContentType = "richtext" | "fill";
+
 /**
  * @public
  * A type of content that can be read from a user's design.
  */
-export declare type ContentType = "richtext";
+declare type ContentType_2 = "richtext";
 
 /**
  * @public
  * Options for configuring where content in a design should be queried from.
  */
-declare type ContextOptions = {
+export declare type ContextOptions = {
   target: "current_page";
 };
 
@@ -384,13 +412,13 @@ export declare type Coordinates = {
 export declare const createRichtextRange: () => RichtextRange;
 
 /**
- * @beta
+ * @public
  * Describes a part of a design.
  */
 export declare type DesignContext = DesignContextOptions["type"];
 
 /**
- * @beta
+ * @public
  * Options for configuring which part of a design to read.
  */
 declare type DesignContextOptions = {
@@ -401,194 +429,501 @@ declare type DesignContextOptions = {
 };
 
 /**
- * @beta
+ * @public
  * Provides methods for reading and updating the structure and content of a design.
  */
 export declare namespace DesignEditing {
   /**
-   * @beta
-   * A snapshot containing a fragment of a design's structure and content.
+   * @public
+   * Options for creating an image fill in the element state builder
    */
-  export type DesignDraft<D> = Readonly<D> & {
+  export type ImageFillOpts = {
     /**
-     * Saves any changes made to the draft.
-     *
-     * @remarks
-     * - Any changes to the draft are only reflected in the design after this method is called.
-     * - Once this method is called, further changes to the draft are not possible.
+     * The type of media.
      */
-    save(): Promise<void>;
+    type: "image";
+    /**
+     * A unique identifier that points to an image asset in Canva's backend.
+     */
+    imageRef: ImageRef;
+    /**
+     * If `true`, the image is flipped horizontally.
+     */
+    flipX?: boolean;
+    /**
+     * If `true`, the image is flipped vertically.
+     */
+    flipY?: boolean;
   };
   /**
-   * @beta
-   * Options for creating an image fill in the element builder
+   * @public
+   * Options for creating a video fill in the element state builder
    */
-  export type ImageFillOpts = Partial<ImageFill> &
-    Required<Pick<ImageFill, "type" | "imageRef">>;
+  export type VideoFillOpts = {
+    /**
+     * The type of media.
+     */
+    type: "video";
+    /**
+     * A unique identifier that points to a video asset in Canva's backend.
+     */
+    videoRef: VideoRef;
+    /**
+     * If `true`, the video is flipped horizontally.
+     */
+    flipX?: boolean;
+    /**
+     * If `true`, the video is flipped vertically.
+     */
+    flipY?: boolean;
+  };
   /**
-   * @beta
-   * Options for creating a video fill in the element builder
+   * @public
+   * Options for creating a media fill in the element state builder
    */
-  export type VideoFillOpts = Partial<VideoFill> &
-    Required<Pick<VideoFill, "type" | "videoRef">>;
+  export type MediaContainerOpts = ImageFillOpts | VideoFillOpts;
   /**
-   * @beta
-   * Options for creating a media fill in the element builder
+   * @public
+   * Options for creating a fill in the element state builder
    */
-  export type MediaFillOpts = ImageFillOpts | VideoFillOpts;
+  export type FillOpts =
+    | {
+        colorContainer: ColorContainerOpts;
+        mediaContainer?: MediaContainerOpts;
+      }
+    | {
+        colorContainer?: ColorContainerOpts;
+        mediaContainer: MediaContainerOpts;
+      };
   /**
-   * @beta
-   * Options for creating a fill in the element builder
+   * @public
+   * Options for creating a fill of a shape in the element state builder
    */
-  export type FillOpts =
+  export type PathFillOpts =
     | {
-        color: ColorFillOpts;
-        media?: MediaFillOpts;
+        colorContainer: ColorContainerOpts;
+        mediaContainer?: MediaContainerOpts;
+        isMediaEditable?: boolean;
       }
     | {
-        color?: ColorFillOpts;
-        media: MediaFillOpts;
+        colorContainer?: ColorContainerOpts;
+        mediaContainer: MediaContainerOpts;
+        isMediaEditable?: boolean;
       };
   /**
-   * @beta
+   * @public
    */
-  export type ColorFillOpts = Exclude<ColorFill, Unsupported>;
+  export type ColorContainerOpts = SolidFillState;
   /**
-   * @beta
-   * Options for creating a stroke in the element builder
+   * @public
+   * Options for creating a stroke in the element state builder
    */
-  export type StrokeOpts = Pick<Stroke, "weight"> & {
-    color: ColorFillOpts;
+  export type StrokeOpts = {
+    /**
+     * The weight (thickness) of the stroke.
+     *
+     * @remarks
+     * - Minimum: 0
+     * - Maximum: 100
+     */
+    weight: number;
+    /**
+     * The color of the stroke.
+     */
+    colorContainer: ColorContainerOpts;
   };
   /**
-   * @beta
-   * Options for creating a shape path in the element builder
+   * @public
+   * Options for creating a shape path in the element state builder
    */
-  export type PathOpts = Pick<Path, "d"> & {
-    fill?: FillOpts;
+  export type PathOpts = {
+    d: string;
+    /**
+     * Describes how a fill is filled with color or media.
+     *
+     * @remarks
+     * If both `media` and `color` are defined, `media` takes precedence.
+     */
+    fill?: PathFillOpts;
+    /**
+     * The outline of the path.
+     */
     stroke?: StrokeOpts;
   };
   /**
-   * @beta
+   * @public
    * Options for creating a rect element.
    */
-  export type CreateRectElementOpts = Required<
-    Pick<RectElement, "top" | "left" | "width" | "height">
-  > & {
+  export type CreateRectElementOpts = {
+    /**
+     * The distance from the top edge of the container, in pixels.
+     *
+     * @remarks
+     * - The pixels are relative to their container.
+     * - Minimum: -32768
+     * - Maximum: 32767
+     */
+    top: number;
+    /**
+     * The distance from the left edge of the container, in pixels.
+     *
+     * @remarks
+     * - The pixels are relative to their container.
+     * - Minimum: -32768
+     * - Maximum: 32767
+     */
+    left: number;
+    /**
+     * A rotation, in degrees.
+     *
+     * @remarks
+     * - Minimum: -180
+     * - Maximum: 180
+     */
+    rotation?: number;
+    /**
+     * Transparency as a percentage.
+     *
+     * @remarks
+     * - Minimum: 0
+     * - Maximum: 1
+     */
+    transparency?: number;
+    /**
+     * A width, in pixels.
+     */
+    width: number;
+    /**
+     * A height, in pixels.
+     */
+    height: number;
+    /**
+     * Describes how a fill is filled with color or media.
+     *
+     * @remarks
+     * If both `media` and `color` are defined, `media` takes precedence.
+     */
     fill?: FillOpts;
-  } & {
+    /**
+     * The outline of the rect.
+     */
     stroke?: StrokeOpts;
-  } & Partial<Omit<RectElement, "fill" | "stroke" | "type">>;
+  };
   /**
-   * @beta
+   * @public
    * Options for creating a shape element.
    */
-  export type CreateShapeElementOpts = Required<
-    Pick<ShapeElement, "top" | "left" | "width" | "height" | "viewBox">
-  > & {
+  export type CreateShapeElementOpts = {
+    /**
+     * The distance from the top edge of the container, in pixels.
+     *
+     * @remarks
+     * - The pixels are relative to their container.
+     * - Minimum: -32768
+     * - Maximum: 32767
+     */
+    top: number;
+    /**
+     * The distance from the left edge of the container, in pixels.
+     *
+     * @remarks
+     * - The pixels are relative to their container.
+     * - Minimum: -32768
+     * - Maximum: 32767
+     */
+    left: number;
+    /**
+     * A rotation, in degrees.
+     *
+     * @remarks
+     * - Minimum: -180
+     * - Maximum: 180
+     */
+    rotation?: number;
+    /**
+     * Transparency as a percentage.
+     *
+     * @remarks
+     * - Minimum: 0
+     * - Maximum: 1
+     */
+    transparency?: number;
+    /**
+     * A width, in pixels.
+     */
+    width: number;
+    /**
+     * A height, in pixels.
+     */
+    height: number;
+    /**
+     * The scale and cropping of the shape.
+     */
+    readonly viewBox: AlignedBoxState;
+    /**
+     * The paths that define the structure of the shape.
+     *
+     * @remarks
+     * - Must have between 1 and 30 paths.
+     * - Total size of all paths must not exceed 2kb.
+     * - Maximum of 6 unique fill colors across all paths.
+     */
     paths: PathOpts[];
-  } & Partial<Omit<ShapeElement, "type" | "paths">>;
+  };
   /**
-   * @beta
+   * @public
    * Options for creating an embed element.
    */
-  export type CreateEmbedElementOpts = Required<
-    Pick<EmbedElement, "top" | "left" | "width" | "height" | "url">
-  > &
-    Partial<Omit<EmbedElement, "type">>;
+  export type CreateEmbedElementOpts = {
+    /**
+     * The distance from the top edge of the container, in pixels.
+     *
+     * @remarks
+     * - The pixels are relative to their container.
+     * - Minimum: -32768
+     * - Maximum: 32767
+     */
+    top: number;
+    /**
+     * The distance from the left edge of the container, in pixels.
+     *
+     * @remarks
+     * - The pixels are relative to their container.
+     * - Minimum: -32768
+     * - Maximum: 32767
+     */
+    left: number;
+    /**
+     * A rotation, in degrees.
+     *
+     * @remarks
+     * - Minimum: -180
+     * - Maximum: 180
+     */
+    rotation?: number;
+    /**
+     * Transparency as a percentage.
+     *
+     * @remarks
+     * - Minimum: 0
+     * - Maximum: 1
+     */
+    transparency?: number;
+    /**
+     * A width, in pixels.
+     */
+    width: number;
+    /**
+     * A height, in pixels.
+     */
+    height: number;
+    /**
+     * The URL of the rich media.
+     *
+     * @remarks
+     * This URL must be supported by the Iframely API.
+     */
+    url: string;
+  };
   /**
-   * @beta
+   * @public
    * Options for creating a text element.
    */
-  export type CreateTextElementOpts = Required<
-    Pick<TextElement, "top" | "left" | "width" | "text">
-  > &
-    Partial<Omit<TextElement, "type" | "height">>;
+  export type CreateTextElementOpts = {
+    /**
+     * The distance from the top edge of the container, in pixels.
+     *
+     * @remarks
+     * - The pixels are relative to their container.
+     * - Minimum: -32768
+     * - Maximum: 32767
+     */
+    top: number;
+    /**
+     * The distance from the left edge of the container, in pixels.
+     *
+     * @remarks
+     * - The pixels are relative to their container.
+     * - Minimum: -32768
+     * - Maximum: 32767
+     */
+    left: number;
+    /**
+     * A width, in pixels.
+     */
+    width: number;
+    /**
+     * The text content.
+     */
+    text: {
+      regions: readonly TextRegion[];
+    };
+    /**
+     * A rotation, in degrees.
+     *
+     * @remarks
+     * - Minimum: -180
+     * - Maximum: 180
+     */
+    rotation?: number;
+    /**
+     * Transparency as a percentage.
+     *
+     * @remarks
+     * - Minimum: 0
+     * - Maximum: 1
+     */
+    transparency?: number;
+  };
   /**
-   * @beta
-   * Provides methods for creating elements.
+   * @public
+   * Provides methods for creating element states.
    *
    * @remarks
    * These methods don't add the elements to the design. They only return elements that can
    * be added to a design, such as with the `insertAfter` method.
+   *
+   * @preventInline
    */
-  export interface ElementBuilder {
+  export interface ElementStateBuilder {
     /**
-     * Creates a rect element.
+     * Creates a rect element state.
      * @param opts - Options for creating the rect element.
      */
-    createRectElement(opts: CreateRectElementOpts): RectElement;
+    createRectElement(opts: CreateRectElementOpts): RectElementState;
     /**
-     * Creates a shape element.
+     * Creates a shape element state.
      * @param opts - Options for creating the shape element.
      */
-    createShapeElement(opts: CreateShapeElementOpts): ShapeElement;
+    createShapeElement(opts: CreateShapeElementOpts): ShapeElementState;
     /**
-     * Creates an embed element.
+     * Creates an embed element state.
      * @param opts - Options for creating the embed element.
      */
-    createEmbedElement(opts: CreateEmbedElementOpts): EmbedElement;
+    createEmbedElement(opts: CreateEmbedElementOpts): EmbedElementState;
     /**
-     * Creates a text element.
+     * Creates a text element state.
      * @param opts - Options for creating the text element.
      */
-    createTextElement(opts: CreateTextElementOpts): TextElement;
+    createTextElement(opts: CreateTextElementOpts): TextElementState;
     /**
      * Creates a richtext range.
      */
     createRichtextRange(): RichtextRange;
+  }
+  /**
+   * @public
+   * Async methods for handling more complex operations.
+   */
+  export interface AsyncOperations {
+    /**
+     * Group specified elements.
+     *
+     * @param opts - Options for grouping elements.
+     *
+     * @returns a new group element containing all the given elements.
+     */
+    group(opts: AsyncOperationsGroupOpts): Promise<GroupElement>;
     /**
-     * Creates a clone of an element.
-     * @returns a new element with the same properties as the argument.
+     * Ungroup a group element.
+     *
+     * @param opts - Options for ungrouping a group element.
+     *
+     * @returns new elements that are ungrouped from the given group.
      */
-    cloneElement(element: RectElement): RectElement;
-    cloneElement(element: ShapeElement): ShapeElement;
-    cloneElement(element: EmbedElement): EmbedElement;
-    cloneElement(element: TextElement): TextElement;
-    cloneElement(
-      element: RectElement | ShapeElement | EmbedElement | TextElement,
-    ): RectElement | ShapeElement | EmbedElement | TextElement;
+    ungroup(
+      opts: AsyncOperationsUngroupOpts,
+    ): Promise<readonly AbsoluteElement[]>;
   }
   /**
-   * @beta
+   * @public
+   * Options for `group` operation.
+   */
+  export interface AsyncOperationsGroupOpts {
+    /**
+     * Elements to be grouped.
+     */
+    elements: readonly Exclude<GroupContentElement, UnsupportedElement>[];
+  }
+  /**
+   * @public
+   * Options for `ungroup` operation.
+   */
+  export interface AsyncOperationsUngroupOpts {
+    /**
+     * Group element to be ungroup.
+     */
+    element: GroupElement;
+  }
+  /**
+   * @public
+   * Helpers for use with supported pages.
+   *
+   * @remarks
+   * Not applicable to unsupported pages.
+   *
+   * @preventInline
+   */
+  export type PageHelpers = AsyncOperations & {
+    /**
+     * Build an element state that can be used to create an element with the `insert` methods of
+     * the page's element list
+     */
+    elementStateBuilder: DesignEditing.ElementStateBuilder;
+  };
+  /**
+   * @public
    * The result of reading part of a design when the context is the current page.
    */
-  export type CurrentPageResult = DesignDraft<{
+  export type CurrentPageResult<
+    Page = DesignEditing.Page,
+    Helpers = DesignEditing.PageHelpers,
+  > = Readonly<{
     /**
      * The current page of the design.
      */
-    page: FixedPage;
+    page: Page;
+    /**
+     * These are various utilities that allow apps to do more complex operations on the page.
+     */
+    helpers: Helpers;
+    /**
+     * Saves any changes made during the session while keeping the transaction open.
+     *
+     * @remarks
+     * - Any changes in the session are only reflected in the design after this method is called.
+     * - Once this method is called, further changes in the session can still be made.
+     */
+    sync(): Promise<void>;
   }>;
-  /**
-   * @beta
-   * The result of reading part of a design.
-   */
-  export type DesignOpenResult = CurrentPageResult;
   /**
    * A function called for each item in the list.
    *
    * @param item - The current item in the list.
    * @param index - The index of the current item.
    */
-  export type ForEachCallback<T> = (item: T, index: number) => void;
+  export type ForEachCallback<M> = (item: M, index: number) => void;
   /**
    * A function that determines if an item should be included in the result.
    *
    * @param item - The item to test.
    * @returns `true` if the item should be included, otherwise `false`.
    */
-  export type FilterPredicate<T> = (item: T) => boolean;
+  export type FilterPredicate<M> = (item: M) => boolean;
   /**
    * A type predicate function that determines if an item is of a specific type.
    *
    * @param item - The item to test.
    * @returns `true` if the item is of type `C`, otherwise `false`.
    */
-  export type TypeFilterPredicate<T, C extends T> = (item: T) => item is C;
+  export type TypeFilterPredicate<M, C extends M> = (item: M) => item is C;
   /**
+   * @public
    * A list that cannot be changed.
+   *
+   * @preventInline
    */
-  export interface ReadableList<T> {
+  export interface ReadableList<M> {
     /**
      * Gets the number of items in the list.
      *
@@ -600,33 +935,119 @@ export declare namespace DesignEditing {
      *
      * @returns An array containing all items. The items are the same as in the list.
      */
-    toArray(): readonly T[];
+    toArray(): readonly M[];
     /**
      * Executes a function for each item in the list.
      *
      * @param callback - The function to run for each item.
      */
-    forEach(callback: ForEachCallback<T>): void;
+    forEach(callback: ForEachCallback<M>): void;
     /**
      * Creates a new array with items that match a specific type.
      *
      * @param filter - A function that checks if an item is of type `C`.
      * @returns An array of items that are of type `C`.
      */
-    filter<C extends T>(filter: TypeFilterPredicate<T, C>): readonly C[];
+    filter<C extends M>(filter: TypeFilterPredicate<M, C>): readonly C[];
     /**
      * Creates a new array with items that pass a test.
      *
      * @param filter - A function that tests each item. Returns `true` to keep the item.
      * @returns An array of items that passed the test.
      */
-    filter(filter: FilterPredicate<T>): readonly T[];
+    filter(filter: FilterPredicate<M>): readonly M[];
   }
   /**
-   * @beta
-   * A list of items that can be changed.
+   * @public
+   * A list of items that can be read.
+   *
+   * @preventInline
+   */
+  export interface ListState<T> extends Iterable<T | undefined> {
+    join(separator?: string): string;
+    slice(start?: number, end?: number): EditableListState<T>;
+    indexOf(searchElement: T, fromIndex?: number): number;
+    lastIndexOf(searchElement: T, fromIndex?: number): number;
+    every<S extends T>(
+      predicate: (value: T, index: number) => value is S,
+    ): this is ListState<S>;
+    every(predicate: (value: T, index: number) => unknown): boolean;
+    some(predicate: (value: T, index: number) => unknown): boolean;
+    forEach(callbackFn: (value: T, index: number) => void): void;
+    map<U>(callbackFn: (value: T, index: number) => U): EditableListState<U>;
+    filter<S extends T>(
+      predicate: (value: T, index: number) => value is S,
+    ): S[];
+    filter(predicate: (value: T, index: number) => unknown): T[];
+    reduce(
+      callbackFn: (
+        previousValue: T,
+        currentValue: T,
+        currentIndex: number,
+      ) => T,
+      initialValue?: T,
+    ): T;
+    reduce<U>(
+      callbackFn: (
+        previousValue: U,
+        currentValue: T,
+        currentIndex: number,
+      ) => U,
+      initialValue: U,
+    ): U;
+    reduceRight(
+      callbackFn: (
+        previousValue: T,
+        currentValue: T,
+        currentIndex: number,
+      ) => T,
+      initialValue?: T,
+    ): T;
+    reduceRight<U>(
+      callbackFn: (
+        previousValue: U,
+        currentValue: T,
+        currentIndex: number,
+      ) => U,
+      initialValue: U,
+    ): U;
+    find<S extends T>(
+      predicate: (value: T | undefined, index: number) => value is S,
+    ): S | undefined;
+    find(
+      predicate: (value: T | undefined, index: number) => unknown,
+    ): T | undefined;
+    flatMap<U>(
+      callback: (value: T, index: number, array: T[]) => U | readonly U[],
+    ): U[];
+    readonly length: number;
+    readonly [n: number]: T;
+  }
+  /**
+   * @public
+   * A list of items that can be read and updated.
+   */
+  export type EditableListState<T> = ListState<T> & {
+    length: number;
+    pop(): T | undefined;
+    push(...items: T[]): number;
+    shift(): T | undefined;
+    splice(start: number, deleteCount?: number): EditableListState<T>;
+    splice(
+      start: number,
+      deleteCount: number,
+      ...items: T[]
+    ): EditableListState<T>;
+    unshift(...items: T[]): number;
+    [n: number]: T;
+  };
+  /**
+   * @public
+   * A list of items that can be read and updated.
+   *
+   * @preventInline
    */
-  export interface MutableList<T> {
+  export interface List<S, M> extends ReadableList<M> {
     /**
      * Adds a copy of an item to the list and places it right before another item.
      *
@@ -639,7 +1060,7 @@ export declare namespace DesignEditing {
      * @returns
      * The added item, or `undefined` if the operation failed.
      */
-    insertBefore(ref: T | undefined, item: T): T | undefined;
+    insertBefore(ref: M | undefined, item: S): M | undefined;
     /**
      * Adds a copy of an item to the list and places it right after another item.
      *
@@ -652,7 +1073,7 @@ export declare namespace DesignEditing {
      * @returns
      * The added item, or `undefined` if the operation failed.
      */
-    insertAfter(ref: T | undefined, item: T): T | undefined;
+    insertAfter(ref: M | undefined, item: S): M | undefined;
     /**
      * Moves an existing item to a new position right before another item.
      *
@@ -663,7 +1084,7 @@ export declare namespace DesignEditing {
      * @param item - The item to move.
      * The operation fails if the item is not already in the list.
      */
-    moveBefore(ref: T | undefined, item: T): void;
+    moveBefore(ref: M | undefined, item: M): void;
     /**
      * Moves an existing item to a new position right after another item.
      *
@@ -674,44 +1095,26 @@ export declare namespace DesignEditing {
      * @param item - The item to move.
      * The operation fails if the item is not already in the list.
      */
-    moveAfter(ref: T | undefined, item: T): void;
+    moveAfter(ref: M | undefined, item: M): void;
     /**
      * Removes an item from the list.
      *
      * @param item - The item to remove from the list.
      */
-    delete(item: T): void;
+    delete(item: M): void;
   }
   /**
-   * @beta
-   * A list of items that can be read and updated.
-   */
-  export interface List<T> extends ReadableList<T>, MutableList<T> {}
-  /**
-   * @beta
-   * Represents an element that's not supported by the Apps SDK.
+   * @public
+   * Represents something that's not supported by the Apps SDK.
    */
   export interface Unsupported {
-    /**
-     * The type of element.
-     */
     readonly type: "unsupported";
   }
   /**
-   * @beta
-   * A single valid character in a hex code.
-   */
-  export type Hex = `123456790abcdef`[number];
-  /**
-   * @beta
-   * A six-character hexadecimal color code prefixed with a `#`.
-   */
-  export type HexCode = `#${Hex}${Hex}${Hex}${Hex}${Hex}${Hex}`;
-  /**
-   * @beta
-   * A set of dimensions.
+   * @public
+   * A state that creates a set of dimensions.
    */
-  export interface Dimensions {
+  export interface DimensionsState {
     /**
      * A width, in pixels.
      */
@@ -722,10 +1125,15 @@ export declare namespace DesignEditing {
     readonly height: number;
   }
   /**
-   * @beta
-   * An image that fills the interior of a path.
+   * @public
+   * A set of dimensions.
    */
-  export interface ImageFill {
+  export type Dimensions = DimensionsState;
+  /**
+   * @public
+   * A state that creates an image fill.
+   */
+  export interface ImageFillState {
     /**
      * The type of media.
      */
@@ -733,7 +1141,7 @@ export declare namespace DesignEditing {
     /**
      * A unique identifier that points to an image asset in Canva's backend.
      */
-    imageRef: ImageRef;
+    readonly imageRef: ImageRef;
     /**
      * If `true`, the image is flipped horizontally.
      */
@@ -744,10 +1152,15 @@ export declare namespace DesignEditing {
     flipY: boolean;
   }
   /**
-   * @beta
-   * A video that fills the interior of a path.
+   * @public
+   * An image that fills the interior of a media.
+   */
+  export type ImageFill = ImageFillState;
+  /**
+   * @public
+   * A state that creates a video fill.
    */
-  export interface VideoFill {
+  export interface VideoFillState {
     /**
      * The type of media.
      */
@@ -755,7 +1168,7 @@ export declare namespace DesignEditing {
     /**
      * A unique identifier that points to a video asset in Canva's backend.
      */
-    videoRef: VideoRef;
+    readonly videoRef: VideoRef;
     /**
      * If `true`, the video is flipped horizontally.
      */
@@ -766,59 +1179,171 @@ export declare namespace DesignEditing {
     flipY: boolean;
   }
   /**
-   * @beta
-   * A media item that fills the interior of a path.
+   * @public
+   * A video that fills the interior of a media.
+   */
+  export type VideoFill = VideoFillState;
+  /**
+   * @public
+   * A state that creates a media fill.
+   */
+  export type MediaFillState = ImageFillState | VideoFillState;
+  /**
+   * @public
+   * A media item that fills an interior.
    */
   export type MediaFill = ImageFill | VideoFill;
   /**
-   * @beta
-   * A solid color that fills the interior of a path.
+   * @public
+   * A state that creates a solid color fill.
    */
-  export interface SolidFill {
+  export interface SolidFillState {
     /**
      * The type of color.
      */
     readonly type: "solid";
     /**
-     * The color of the fill, as a hex code.
+     * The color of the fill.
+     * This must be a valid, six-digit hex code, prefixed with a `#` symbol.
      *
      * @remarks
      * - Must be six characters long.
      * - Must start with a `#`.
      * - Must use lowercase letters.
+     * @example "#ff0099"
      */
-    color: HexCode;
+    color: string;
   }
   /**
-   * @beta
-   * A color that fills the interior of a path.
+   * @public
+   * A solid color that fills an interior.
+   */
+  export type SolidFill = SolidFillState;
+  /**
+   * @public
+   * A state that creates a color fill.
+   */
+  export type ColorFillState = SolidFillState | Unsupported;
+  /**
+   * @public
+   * A color that fills an interior.
    */
   export type ColorFill = SolidFill | Unsupported;
   /**
-   * @beta
-   * Describes how a path is filled with color or media.
+   * @public
+   * A state that creates a fill with color or media.
    *
    * @remarks
    * If both `media` and `color` are defined, `media` takes precedence.
    */
-  export interface Fill {
+  export interface FillState {
     /**
      * The media fill for the path, if any.
      */
-    media: MediaFill | undefined;
+    mediaContainer: MediaFillState | undefined;
     /**
      * The color fill for the path, if any.
      */
-    color: ColorFill | undefined;
+    colorContainer: ColorFillState | undefined;
   }
   /**
-   * @beta
-   * The scale and cropping of a shape.
+   * @public
+   * A state that creates a shape path fill with color or media.
+   *
+   * @remarks
+   * If both `media` and `color` are defined, `media` takes precedence.
+   */
+  export interface PathFillState {
+    /**
+     * Defines whether the media fill is editable.
+     */
+    isMediaEditable: boolean;
+    /**
+     * The media fill for the path, if any.
+     */
+    mediaContainer: MediaFillState | undefined;
+    /**
+     * The color fill for the path, if any.
+     */
+    colorContainer: ColorFillState | undefined;
+  }
+  /**
+   * @public
+   * Describes how a fill of a shape path is filled with color or media.
+   *
+   * @remarks
+   * If both `media` and `color` are defined, `media` takes precedence.
+   */
+  export type PathFill =
+    | PathFillWithEditableMedia
+    | PathFillWithNonEditableMedia;
+  export interface PathFillWithEditableMedia {
+    readonly isMediaEditable: true;
+    /**
+     * A media fill, if any.
+     */
+    readonly mediaContainer: {
+      set(state: MediaFillState | undefined): void;
+      ref: MediaFill | undefined;
+    };
+    /**
+     * A color fill, if any.
+     */
+    readonly colorContainer: {
+      set(state: SolidFillState | undefined): void;
+      ref: ColorFill | undefined;
+    };
+  }
+  export interface PathFillWithNonEditableMedia {
+    readonly isMediaEditable: false;
+    /**
+     * A media fill, if any.
+     * MediaFill is not editable
+     */
+    readonly mediaContainer: {
+      ref: MediaFill | undefined;
+    };
+    /**
+     * A color fill, if any.
+     */
+    readonly colorContainer: {
+      set(state: SolidFillState | undefined): void;
+      ref: ColorFill | undefined;
+    };
+  }
+  /**
+   * @public
+   * Describes how a fill is filled with color or media.
+   *
+   * @remarks
+   * If both `media` and `color` are defined, `media` takes precedence.
+   *
+   * @preventInline
+   */
+  export interface Fill {
+    /**
+     * A media fill, if any.
+     */
+    readonly mediaContainer: {
+      set(state: MediaFillState | undefined): void;
+      ref: MediaFill | undefined;
+    };
+    /**
+     * A color fill, if any.
+     */
+    readonly colorContainer: {
+      set(state: SolidFillState | undefined): void;
+      ref: ColorFill | undefined;
+    };
+  }
+  /**
+   * @public
+   * A state that creates the scale and cropping of a shape.
    *
    * @remarks
    * This is similar to the `viewBox` attribute of an `SVGElement`.
    */
-  export type AlignedBox = {
+  export interface AlignedBoxState {
     /**
      * The distance of the shape from the top edge of the element, in pixels.
      */
@@ -826,21 +1351,57 @@ export declare namespace DesignEditing {
     /**
      * The distance of the shape from the left edge of the element, in pixels.
      */
-    readonly left: number;
+    readonly left: number;
+    /**
+     * The width of the view box, in pixels.
+     */
+    readonly width: number;
+    /**
+     * The height of the view box, in pixels.
+     */
+    readonly height: number;
+  }
+  /**
+   * @public
+   * The scale and cropping of a shape.
+   *
+   * @remarks
+   * This is similar to the `viewBox` attribute of an `SVGElement`.
+   */
+  export type AlignedBox = AlignedBoxState;
+  /**
+   * @public
+   * A state that creates a path that defines the structure of a shape element.
+   */
+  export interface PathState {
+    /**
+     * The shape of the path.
+     *
+     * @remarks
+     * This is similar to the `d` attribute of an SVG's `path` element, with some limitations:
+     *
+     * - Must start with an `M` command.
+     * - Only one `M` command is allowed.
+     * - `Q` and `T` commands are not permitted.
+     * - The path must be closed using a `Z` command or matching start and end coordinates.
+     */
+    readonly d: string;
     /**
-     * The width of the view box, in pixels.
+     * The appearance of the path's interior.
      */
-    readonly width: number;
+    readonly fill: PathFillState;
     /**
-     * The height of the view box, in pixels.
+     * The stroke (outline) of the path, if any.
      */
-    readonly height: number;
-  };
+    readonly stroke: StrokeState | undefined;
+  }
   /**
-   * @beta
+   * @public
    * A path that defines the structure of a shape element.
+   *
+   * @preventInline
    */
-  export interface Path {
+  export type Path = {
     /**
      * The shape of the path.
      *
@@ -856,17 +1417,37 @@ export declare namespace DesignEditing {
     /**
      * The appearance of the path's interior.
      */
-    readonly fill: Fill;
+    readonly fill: PathFill;
     /**
      * The stroke (outline) of the path, if any.
      */
     readonly stroke: Stroke | undefined;
+  };
+  /**
+   * @public
+   * A state that creates an outline, such as the border of an element.
+   */
+  export interface StrokeState {
+    /**
+     * The weight (thickness) of the stroke.
+     *
+     * @remarks
+     * - Minimum: 0
+     * - Maximum: 100
+     */
+    weight: number;
+    /**
+     * The color of the stroke.
+     */
+    colorContainer: ColorFillState;
   }
   /**
-   * @beta
+   * @public
    * Represents an outline, such as the border of an element.
+   *
+   * @preventInline
    */
-  export interface Stroke {
+  export type Stroke = {
     /**
      * The weight (thickness) of the stroke.
      *
@@ -878,16 +1459,66 @@ export declare namespace DesignEditing {
     /**
      * The color of the stroke.
      */
-    color: ColorFill;
+    readonly colorContainer: {
+      ref: ColorFill;
+      set(state: SolidFillState): void;
+    };
+  };
+  /**
+   * @public
+   * The basic properties of the state of an element.
+   *
+   * @remarks
+   * These properties are shared by all elements in a design.
+   */
+  export interface ElementState extends DimensionsState {
+    /**
+     * If `true`, the element is locked and cannot be modified.
+     */
+    readonly locked: boolean;
+    /**
+     * The distance from the top edge of the container, in pixels.
+     *
+     * @remarks
+     * - The pixels are relative to their container.
+     * - Minimum: -32768
+     * - Maximum: 32767
+     */
+    readonly top: number;
+    /**
+     * The distance from the left edge of the container, in pixels.
+     *
+     * @remarks
+     * - The pixels are relative to their container.
+     * - Minimum: -32768
+     * - Maximum: 32767
+     */
+    readonly left: number;
+    /**
+     * A rotation, in degrees.
+     *
+     * @remarks
+     * - Minimum: -180
+     * - Maximum: 180
+     */
+    readonly rotation: number;
+    /**
+     * Transparency as a percentage.
+     *
+     * @remarks
+     * - Minimum: 0
+     * - Maximum: 1
+     */
+    readonly transparency: number;
   }
   /**
-   * @beta
+   * @public
    * The basic properties of an element.
    *
    * @remarks
    * These properties are shared by all elements in a design.
    */
-  export interface Element extends Dimensions {
+  export type Element = DimensionsState & {
     /**
      * If `true`, the element is locked and cannot be modified.
      */
@@ -926,12 +1557,12 @@ export declare namespace DesignEditing {
      * - Maximum: 1
      */
     transparency: number;
-  }
+  };
   /**
-   * @beta
-   * Represents a rectangular element.
+   * @public
+   * A state that creates a rectangular element.
    */
-  export interface Rect {
+  export interface RectState {
     /**
      * The type of content.
      */
@@ -939,17 +1570,32 @@ export declare namespace DesignEditing {
     /**
      * The appearance of the rectangle's interior.
      */
+    readonly fill: FillState;
+    /**
+     * The outline of the rectangle.
+     */
+    readonly stroke: StrokeState;
+  }
+  /**
+   * @public
+   * Represents a rectangular element.
+   */
+  export type Rect = {
+    /**
+     * The element type
+     */
+    readonly type: "rect";
     readonly fill: Fill;
     /**
      * The outline of the rectangle.
      */
     readonly stroke: Stroke;
-  }
+  };
   /**
-   * @beta
-   * Represents a vector shape element.
+   * @public
+   * A state that creates a vector shape element.
    */
-  export interface Shape {
+  export interface ShapeState {
     /**
      * The type of content.
      */
@@ -957,7 +1603,7 @@ export declare namespace DesignEditing {
     /**
      * The scale and cropping of the shape.
      */
-    viewBox: AlignedBox;
+    readonly viewBox: AlignedBoxState;
     /**
      * The paths that define the structure of the shape.
      *
@@ -966,13 +1612,45 @@ export declare namespace DesignEditing {
      * - Total size of all paths must not exceed 2kb.
      * - Maximum of 6 unique fill colors across all paths.
      */
+    readonly paths: ListState<PathState>;
+  }
+  /**
+   * @public
+   * Represents a vector shape element.
+   */
+  export type Shape = {
+    /**
+     * The type of content.
+     */
+    readonly type: "shape";
+    /**
+     * The scale and cropping of the shape.
+     */
+    readonly viewBox: AlignedBox;
+    /**
+     * The paths that define the structure of the shape.
+     */
     readonly paths: ReadableList<Path>;
+  };
+  /**
+   * @public
+   * A state that creates group content.
+   */
+  export interface GroupState {
+    /**
+     * The type of content.
+     */
+    readonly type: "group";
+    /**
+     * The elements that exist within the group.
+     */
+    readonly contents: ListState<GroupContentElementState>;
   }
   /**
-   * @beta
+   * @public
    * Represents group content.
    */
-  export interface Group<C> {
+  export type Group = {
     /**
      * The type of content.
      */
@@ -980,13 +1658,13 @@ export declare namespace DesignEditing {
     /**
      * The elements that exist within the group.
      */
-    readonly contents: ReadableList<C>;
-  }
+    readonly contents: ReadableList<GroupContentElement>;
+  };
   /**
-   * @beta
-   * Represents rich media content.
+   * @public
+   * A state that creates rich media content.
    */
-  export interface Embed {
+  export interface EmbedState {
     /**
      * The type of content.
      */
@@ -1000,10 +1678,15 @@ export declare namespace DesignEditing {
     readonly url: string;
   }
   /**
-   * @beta
-   * Represents text content.
+   * @public
+   * Represents rich media content.
+   */
+  export type Embed = EmbedState;
+  /**
+   * @public
+   * A state that creates text content.
    */
-  export interface Text {
+  export interface TextState {
     /**
      * The type of content.
      */
@@ -1011,44 +1694,99 @@ export declare namespace DesignEditing {
     /**
      * The text content.
      */
-    readonly text: RichtextRange;
+    readonly text: {
+      regions: ListState<TextRegion>;
+    };
   }
   /**
-   * @beta
+   * @public
+   * Represents text content.
+   */
+  export type Text = {
+    readonly type: "text";
+    readonly text: RichtextRange;
+  };
+  /**
+   * @public
+   * A state that creates a rectangle element.
+   *
+   * @remarks
+   * The rectangle can be filled with image content, video content, or a solid color.
+   */
+  export type RectElementState = RectState & ElementState;
+  /**
+   * @public
    * An element that renders a rectangle.
    *
    * @remarks
    * The rectangle can be filled with image content, video content, or a solid color.
    */
-  export interface RectElement extends Rect, Element {}
+  export type RectElement = Rect & Element;
   /**
-   * @beta
+   * @public
+   * A state that creates a vector shape element.
+   */
+  export type ShapeElementState = ShapeState & ElementState;
+  /**
+   * @public
    * An element that renders a vector shape.
    */
-  export interface ShapeElement extends Shape, Element {}
+  export type ShapeElement = Shape & Element;
   /**
-   * @beta
+   * @public
+   * A state that creates a group element.
+   */
+  export type GroupElementState = GroupState & ElementState;
+  /**
+   * @public
    * An element that renders a group of other elements.
    */
-  export interface GroupElement extends Group<GroupContentElement>, Element {}
+  export type GroupElement = Group & Element;
   /**
-   * @beta
+   * @public
+   * A state that creates an embed element, such as a YouTube video.
+   */
+  export type EmbedElementState = EmbedState & ElementState;
+  /**
+   * @public
    * An element that embeds rich media, such as a YouTube video.
    */
-  export interface EmbedElement extends Embed, Element {}
+  export type EmbedElement = Embed & Element;
   /**
-   * @beta
+   * @public
+   * A state that creates a text element.
+   */
+  export type TextElementState = TextState & ElementState;
+  /**
+   * @public
    * An element that renders text content.
    */
-  export interface TextElement extends Text, Element {}
+  export type TextElement = Text & Element;
   /**
-   * @beta
+   * @public
+   * An element state that is not supported by the Apps SDK.
+   */
+  export type UnsupportedElementState = Unsupported & ElementState;
+  /**
+   * @public
    * An element that is not supported by the Apps SDK.
    */
-  export interface UnsupportedElement extends Unsupported, Element {}
+  export type UnsupportedElement = Unsupported & Readonly<Element>;
   /**
-   * @beta
+   * @public
+   * An element state that can exist in a group content state.
+   */
+  export type GroupContentElementState =
+    | RectElementState
+    | ShapeElementState
+    | EmbedElementState
+    | TextElementState
+    | UnsupportedElementState;
+  /**
+   * @public
    * An element that can exist in a group element.
+   *
+   * @preventInline
    */
   export type GroupContentElement =
     | RectElement
@@ -1057,10 +1795,25 @@ export declare namespace DesignEditing {
     | TextElement
     | UnsupportedElement;
   /**
-   * @beta
-   * An element that can exist on a fixed page.
+   * @public
+   * An element state that can exist on an absolute page state.
+   *
+   * @preventInline
+   */
+  export type AbsoluteElementState =
+    | RectElementState
+    | ShapeElementState
+    | GroupElementState
+    | EmbedElementState
+    | TextElementState
+    | UnsupportedElementState;
+  /**
+   * @public
+   * An element that can exist on an absolute page.
+   *
+   * @preventInline
    */
-  export type FixedElement =
+  export type AbsoluteElement =
     | RectElement
     | ShapeElement
     | GroupElement
@@ -1068,14 +1821,58 @@ export declare namespace DesignEditing {
     | TextElement
     | UnsupportedElement;
   /**
-   * @beta
-   * A page with fixed dimensions.
+   * @public
+   * A list of elements.
+   *
+   * @preventInline
+   */
+  export interface ElementList
+    extends List<AbsoluteElementState, AbsoluteElement> {
+    insertBefore(
+      ref: AbsoluteElement | undefined,
+      state: EmbedElementState,
+    ): EmbedElement;
+    insertBefore(
+      ref: AbsoluteElement | undefined,
+      state: TextElementState,
+    ): TextElement;
+    insertBefore(
+      ref: AbsoluteElement | undefined,
+      state: ShapeElementState,
+    ): ShapeElement;
+    insertBefore(
+      ref: AbsoluteElement | undefined,
+      state: RectElementState,
+    ): RectElement;
+    insertAfter(
+      ref: AbsoluteElement | undefined,
+      state: EmbedElementState,
+    ): EmbedElement;
+    insertAfter(
+      ref: AbsoluteElement | undefined,
+      state: TextElementState,
+    ): TextElement;
+    insertAfter(
+      ref: AbsoluteElement | undefined,
+      state: ShapeElementState,
+    ): ShapeElement;
+    insertAfter(
+      ref: AbsoluteElement | undefined,
+      state: RectElementState,
+    ): RectElement;
+  }
+
+  /**
+   * @public
+   * A page with either fixed or unbounded dimensions.
+   *
+   * @preventInline
    */
-  export interface FixedPage {
+  export type AbsolutePage = {
     /**
      * The type of page.
      */
-    readonly type: "fixed";
+    readonly type: "absolute";
     /**
      * If `true`, the page is locked and cannot be modified.
      */
@@ -1095,14 +1892,18 @@ export declare namespace DesignEditing {
      * Elements are rendered in the order they appear in the list.
      * Later elements appear on top of earlier ones.
      */
-    readonly elements: List<FixedElement>;
-  }
+    readonly elements: ElementList;
+  };
   /**
-   * @beta
+   * @public
    * A page in a design.
+   *
+   * @remarks
+   * - Currently, only absolute pages are supported.
+   * - Other page types are represented as `Unsupported`.
+   * - Additional page types may be supported in future releases.
    */
-  export type Page = FixedPage | Unsupported;
-
+  export type Page = AbsolutePage | Unsupported;
   {
   }
 }
@@ -1156,23 +1957,16 @@ export declare type DesignMetadata = {
 };
 
 /**
- * @beta
+ * @public
  * A callback for reading and updating part of a design.
- * @param draft - The result of reading part of a design.
- * @param helpers - Helper methods for reading and updating the design.
+ * @param session - The result of reading part of a design.
  */
 export declare type DesignOpenCallback = (
-  draft: DesignEditing.DesignOpenResult,
-  helpers: {
-    /**
-     * Provides methods for creating elements.
-     */
-    elementBuilder: DesignEditing.ElementBuilder;
-  },
-) => Promise<void> | void;
+  session: DesignEditing.CurrentPageResult,
+) => Promise<void>;
 
 /**
- * @beta
+ * @public
  * Options for configuring which part of a design to read.
  */
 export declare type DesignOpenOptions = DesignContextOptions;
@@ -1270,38 +2064,48 @@ export declare type DragStartEvent<E extends Element> = Pick<
  * @param callback - A callback for operating on the read content.
  */
 export declare const editContent: (
-  options: EditContentOptions,
-  callback: EditContentCallback,
+  options: EditContentOptions_2,
+  callback: EditContentCallback_2,
 ) => Promise<void>;
 
+/**
+ * @beta
+ * A callback for reading and updating the requested design content.
+ * @param session - The result of reading the content in the design.
+ */
+export declare type EditContentCallback = (
+  session: RichtextContentSession | ContentFillSession,
+) => Promise<void> | void;
+
 /**
  * @public
  * A callback for reading and updating the requested design content.
  * @param session - The result of reading the content in the design.
  */
-export declare type EditContentCallback = (session: {
-  /**
-   * The individual content items returned by a query.
-   */
-  readonly contents: readonly RichtextContentRange[];
+declare type EditContentCallback_2 = (
+  session: RichtextContentSession,
+) => Promise<void> | void;
+
+/**
+ * @beta
+ * Options for configuring how the design content is read.
+ */
+export declare type EditContentOptions = {
   /**
-   * Commits any changes made to the items in the `contents` array.
-   *
-   * @remarks
-   * An app must call this method for any changes to be reflected in the user's design.
+   * The type of content to edit from the user's design
    */
-  sync(): Promise<void>;
-}) => Promise<void> | void;
+  contentType: ContentType;
+} & ContextOptions;
 
 /**
  * @public
  * Options for configuring how the design content is read.
  */
-export declare type EditContentOptions = {
+declare type EditContentOptions_2 = {
   /**
    * The type of content to edit from the user's design
    */
-  contentType: ContentType;
+  contentType: ContentType_2;
 } & ContextOptions;
 
 /**
@@ -1924,7 +2728,8 @@ export declare type NativeVideoElementWithBox = VideoElementAtPoint;
 declare type ObjectPrimitive = Boolean | String;
 
 /**
- * @beta
+ * @public
+ *
  * Reads a specified part of the user's design and returns all elements in that part.
  *
  * @param options - Options for configuring how the design is read.
@@ -1932,12 +2737,7 @@ declare type ObjectPrimitive = Boolean | String;
  */
 export declare const openDesign: (
   options: DesignOpenOptions,
-  callback: (
-    draft: DesignEditing.DesignOpenResult,
-    helpers: {
-      elementBuilder: DesignEditing.ElementBuilder;
-    },
-  ) => Promise<void> | void,
+  callback: DesignOpenCallback,
 ) => Promise<void>;
 
 /**
@@ -2128,6 +2928,15 @@ export declare interface RichtextContentRange extends RichtextRange {
   readonly deleted: boolean;
 }
 
+/**
+ * @public
+ * Session for reading and updating richtext content in a user's design.
+ */
+export declare interface RichtextContentSession {
+  readonly contents: readonly RichtextContentRange[];
+  sync(): Promise<void>;
+}
+
 /**
  * @public
  * An element that renders richtext content.