@canva/design 2.6.2-beta.1 → 2.7.1-beta.0

package/beta.d.ts

@@ -2,12 +2,131 @@
  * Adds an audio track to the user's design.
  * @public
  * @param audioTrack - The audio track to add to the user's design.
+ *
+ * @example Add audio track to design
+ * ```typescript
+ * import { addAudioTrack } from "@canva/design";
+ * import type { AudioTrack } from "@canva/design";
+ * import type { AudioRef } from "@canva/asset";
+ *
+ * const exampleAudioRef = "YOUR_AUDIO_REF" as AudioRef;
+ *
+ * const audioTrack: AudioTrack = {
+ *   ref: exampleAudioRef
+ * };
+ *
+ * await addAudioTrack(audioTrack);
+ * ```
  */
 export declare const addAudioTrack: (audioTrack: AudioTrack) => Promise<void>;
 
 /**
  * @public
  * Add element to responsive documents, which slot things into a text stream
+ *
+ * @example Insert an image at cursor position
+ * ```typescript
+ * import { addElementAtCursor } from "@canva/design";
+ * import type { ImageElement } from "@canva/design";
+ * import type { ImageRef } from "@canva/asset";
+ *
+ * const exampleImageRef = "YOUR_IMAGE_REF" as ImageRef;
+ *
+ * const imageElement: ImageElement = {
+ *   type: 'image',
+ *   ref: exampleImageRef,
+ *   altText: { text: 'Product image', decorative: false }
+ * };
+ *
+ * await addElementAtCursor(imageElement);
+ * ```
+ *
+ * @example Insert a video at cursor position
+ * ```typescript
+ * import { addElementAtCursor } from "@canva/design";
+ * import type { VideoElement } from "@canva/design";
+ * import type { VideoRef } from "@canva/asset";
+ *
+ * const exampleVideoRef = "YOUR_VIDEO_REF" as VideoRef;
+ *
+ * const videoElement: VideoElement = {
+ *   type: 'video',
+ *   ref: exampleVideoRef,
+ *   altText: { text: 'Product demo', decorative: false }
+ * };
+ *
+ * await addElementAtCursor(videoElement);
+ * ```
+ *
+ * @example Insert embedded content at cursor position
+ * ```typescript
+ * import { addElementAtCursor } from "@canva/design";
+ * import type { EmbedElement } from "@canva/design";
+ *
+ * const embedElement: EmbedElement = {
+ *   type: 'embed',
+ *   url: 'https://www.youtube.com/watch?v=...'
+ * };
+ *
+ * await addElementAtCursor(embedElement);
+ * ```
+ *
+ * @example Insert text at cursor position
+ * ```typescript
+ * import { addElementAtCursor } from "@canva/design";
+ * import type { TextElement } from "@canva/design";
+ *
+ * const textElement: TextElement = {
+ *   type: 'text',
+ *   children: ['Hello World'],
+ *   fontSize: 24,
+ *   color: '#000000'
+ * };
+ *
+ * await addElementAtCursor(textElement);
+ * ```
+ *
+ * @example Insert formatted text at cursor position
+ * ```typescript
+ * import { addElementAtCursor, createRichtextRange } from "@canva/design";
+ * import type { RichtextElement } from "@canva/design";
+ *
+ * const range = createRichtextRange();
+ * range.appendText('Rich Text Content', { color: '#000000' });
+ *
+ * const richtextElement: RichtextElement = {
+ *   type: 'richtext',
+ *   range
+ * };
+ *
+ * await addElementAtCursor(richtextElement);
+ * ```
+ *
+ * @example Insert a table at cursor position
+ * ```typescript
+ * import { addElementAtCursor } from "@canva/design";
+ * import type { TableElement } from "@canva/design";
+ *
+ * const tableElement: TableElement = {
+ *   type: 'table',
+ *   rows: [
+ *     {
+ *       cells: [
+ *         { type: 'string', value: 'Header 1' },
+ *         { type: 'string', value: 'Header 2' }
+ *       ]
+ *     },
+ *     {
+ *       cells: [
+ *         { type: 'string', value: 'Data 1' },
+ *         { type: 'string', value: 'Data 2' }
+ *       ]
+ *     }
+ *   ]
+ * };
+ *
+ * await addElementAtCursor(tableElement);
+ * ```
  */
 export declare const addElementAtCursor: (
   element: ElementAtCursor,
@@ -16,6 +135,84 @@ export declare const addElementAtCursor: (
 /**
  * @public
  * Add element to fixed designs, which use a coordinate-based positioning system.
+ *
+ * @example Insert an image at specific coordinates
+ * ```typescript
+ * import { addElementAtPoint } from "@canva/design";
+ * import type { ImageElementAtPoint } from "@canva/design";
+ * import type { ImageRef } from "@canva/asset";
+ *
+ * const exampleImageRef = "YOUR_IMAGE_REF" as ImageRef;
+ *
+ * const imageElement: ImageElementAtPoint = {
+ *   type: 'image',
+ *   ref: exampleImageRef,
+ *   altText: { text: 'Product image', decorative: false },
+ *   top: 100,
+ *   left: 100,
+ *   width: 300,
+ *   height: 200
+ * };
+ *
+ * await addElementAtPoint(imageElement);
+ * ```
+ *
+ * @example Insert a video at specific coordinates
+ * ```typescript
+ * import { addElementAtPoint } from "@canva/design";
+ * import type { VideoElementAtPoint } from "@canva/design";
+ * import type { VideoRef } from "@canva/asset";
+ *
+ * const exampleVideoRef = "YOUR_VIDEO_REF" as VideoRef;
+ *
+ * const videoElement: VideoElementAtPoint = {
+ *   type: 'video',
+ *   ref: exampleVideoRef,
+ *   altText: { text: 'Product demo', decorative: false },
+ *   top: 100,
+ *   left: 100,
+ *   width: 400,
+ *   height: 300
+ * };
+ *
+ * await addElementAtPoint(videoElement);
+ * ```
+ *
+ * @example Insert embedded content at specific coordinates
+ * ```typescript
+ * import { addElementAtPoint } from "@canva/design";
+ * import type { EmbedElementAtPoint } from "@canva/design";
+ *
+ * const embedElement: EmbedElementAtPoint = {
+ *   type: 'embed',
+ *   url: 'https://www.youtube.com/watch?v=...',
+ *   top: 100,
+ *   left: 100,
+ *   width: 560,
+ *   height: 315
+ * };
+ *
+ * await addElementAtPoint(embedElement);
+ * ```
+ *
+ * @example Insert text at specific coordinates
+ * ```typescript
+ * import { addElementAtPoint } from "@canva/design";
+ * import type { TextElementAtPoint } from "@canva/design";
+ *
+ * const textElement: TextElementAtPoint = {
+ *   type: 'text',
+ *   children: ['Hello World'],
+ *   top: 100,
+ *   left: 100,
+ *   width: 200,
+ *   fontSize: 24,
+ *   color: '#000000',
+ *   textAlign: 'justify'
+ * };
+ *
+ * await addElementAtPoint(textElement);
+ * ```
  */
 export declare const addElementAtPoint: (
   element: DesignElement | ElementAtPoint,
@@ -26,6 +223,22 @@ export declare const addElementAtPoint: (
  * @public
  * Adds a native element to the user's design.
  * @param element - The element to add to the user's design.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { addNativeElement } from "@canva/design";
+ * import type { NativeElementWithBox } from "@canva/design";
+ *
+ * const element: NativeElementWithBox = {
+ *   type: 'text',
+ *   children: ['Legacy element'],
+ *   top: 100,
+ *   left: 100,
+ *   width: 200
+ * };
+ *
+ * await addNativeElement(element);
+ * ```
  */
 export declare const addNativeElement: (
   element: NativeElement | NativeElementWithBox,
@@ -35,6 +248,94 @@ export declare const addNativeElement: (
  * @public
  * Adds a new page immediately after the currently selected page.
  * @param opts - Configuration for the new page to be added.
+ *
+ * @example Create empty page
+ * ```typescript
+ * import { addPage } from "@canva/design";
+ *
+ * await addPage();
+ * ```
+ *
+ * @example Create page with title
+ * ```typescript
+ * import { addPage } from "@canva/design";
+ *
+ * await addPage({
+ *   title: 'My New Page'
+ * });
+ * ```
+ *
+ * @example Create page with background color
+ * ```typescript
+ * import { addPage } from "@canva/design";
+ * import type { PageBackgroundFill } from "@canva/design";
+ *
+ * const background: PageBackgroundFill = {
+ *   color: '#F5F5F5',
+ * };
+ *
+ * await addPage({ background });
+ * ```
+ *
+ * @example Create page with background image
+ * ```typescript
+ * import { addPage } from "@canva/design";
+ * import type { PageBackgroundFill } from "@canva/design";
+ * import type { ImageRef } from "@canva/asset";
+ *
+ * const exampleImageRef = "YOUR_IMAGE_REF" as ImageRef;
+ *
+ * const background: PageBackgroundFill = {
+ *   asset: {
+ *     type: 'image',
+ *     ref: exampleImageRef,
+ *     altText: { text: 'Background image', decorative: true }
+ *   },
+ * };
+ *
+ * await addPage({ background });
+ * ```
+ *
+ * @example Create page with multiple elements
+ * ```typescript
+ * import { addPage } from "@canva/design";
+ * import type { TextElementAtPoint, ImageElementAtPoint } from "@canva/design";
+ * import type { ImageRef } from "@canva/asset";
+ *
+ * const exampleImageRef = "YOUR_IMAGE_REF" as ImageRef;
+ *
+ * await addPage({
+ *   elements: [
+ *     {
+ *       type: 'text',
+ *       children: ['Page Title'],
+ *       top: 50,
+ *       left: 100,
+ *       width: 400,
+ *       fontSize: 32,
+ *       textAlign: 'center'
+ *     } as TextElementAtPoint,
+ *     {
+ *       type: 'text',
+ *       children: ['Subtitle text'],
+ *       top: 100,
+ *       left: 100,
+ *       width: 400,
+ *       fontSize: 18,
+ *       textAlign: 'center'
+ *     } as TextElementAtPoint,
+ *     {
+ *       type: 'image',
+ *       ref: exampleImageRef,
+ *       altText: { text: 'Featured image', decorative: false },
+ *       top: 150,
+ *       left: 200,
+ *       width: 200,
+ *       height: 200
+ *     } as ImageElementAtPoint,
+ *   ]
+ * });
+ * ```
  */
 export declare const addPage: (opts?: {
   /**  Elements to be added to the page */
@@ -75,6 +376,67 @@ export declare type AltText = {
  * - the user selects an existing app element
  *
  * @param appElement - Information about the app element that was changed.
+ *
+ * @example Handle element selection
+ * ```typescript
+ * import { initAppElement } from "@canva/design";
+ *
+ * const appElement = initAppElement<{ content: string }>({
+ *   render: (data) => {
+ *     // Render based on data
+ *     return [{
+ *       type: 'text',
+ *       children: [data.content || 'Default text'],
+ *       top: 0,
+ *       left: 0,
+ *       width: 200
+ *     }];
+ *   }
+ * });
+ *
+ * appElement.registerOnElementChange((element) => {
+ *   if (element) {
+ *     // Element selected or created, do something with the `element.data`
+ *   } else {
+ *     // No element selected
+ *   }
+ * });
+ * ```
+ *
+ * @example Update element data when selected
+ * ```typescript
+ * import { initAppElement } from "@canva/design";
+ *
+ * const appElement = initAppElement<{
+ *   content: string;
+ *   lastSelected: number;
+ *   lastUpdated: number;
+ *   metadata: { lastEdited: number; editCount: number };
+ * }>({
+ *   render: (data) => {
+ *     // Render based on data
+ *     return [{
+ *       type: 'text',
+ *       children: [data.content || 'Default text'],
+ *       top: 0,
+ *       left: 0,
+ *       width: 200
+ *     }];
+ *   }
+ * });
+ *
+ * appElement.registerOnElementChange(async (element) => {
+ *   if (element) {
+ *     // Use the update method to modify the element's data
+ *     await element.update({
+ *       data: {
+ *         ...element.data,
+ *         lastSelected: Date.now()
+ *       }
+ *     });
+ *   }
+ * });
+ * ```
  */
 export declare type AppElementChangeHandler<A extends AppElementData> = (
   appElement:
@@ -89,6 +451,55 @@ export declare type AppElementChangeHandler<A extends AppElementData> = (
         version: number;
         /**
          * Function to update the app element data.
+         *
+         * @param opts - The data and placement to update the app element with.
+         *
+         * @example Update element data only
+         * ```typescript
+         * if (element) {
+         *   await element.update({
+         *     data: {
+         *       ...element.data,
+         *       content: 'Updated content',
+         *       lastUpdated: Date.now()
+         *     }
+         *   });
+         * }
+         * ```
+         *
+         * @example Update data and placement
+         * ```typescript
+         * if (element) {
+         *   await element.update({
+         *     data: {
+         *       ...element.data,
+         *       content: 'Positioned element'
+         *     },
+         *     placement: {
+         *       top: 200,
+         *       left: 200,
+         *       width: 300,
+         *       height: 100
+         *     }
+         *   });
+         * }
+         * ```
+         *
+         * @example Add metadata to element
+         * ```typescript
+         * if (element) {
+         *   await element.update({
+         *     data: {
+         *       ...element.data,
+         *       metadata: {
+         *         ...(element.data.metadata || {}),
+         *         lastEdited: Date.now(),
+         *         editCount: (element.data.metadata?.editCount || 0) + 1,
+         *       },
+         *     },
+         *   });
+         * }
+         * ```
          */
         update: (opts: AppElementOptions<A>) => Promise<void>;
       }
@@ -106,11 +517,135 @@ export declare interface AppElementClient<A extends AppElementData> {
    * Otherwise, the provided data is used to create a new app element.
    * @param appElementData - The data to attach to the app element. Existing data will be overwritten.
    * @param placement - The position, dimensions, and rotation of the app element.
+   *
+   * @example Create or update an element (deprecated)
+   * ```typescript
+   * import { initAppElement } from "@canva/design";
+   *
+   * // Initialize the app element client
+   * const appElement = initAppElement<{ content: string; timestamp: number }>({
+   *   render: (data) => {
+   *     return [{
+   *       type: 'text',
+   *       children: [data.content || 'Default text'],
+   *       top: 100,
+   *       left: 100,
+   *       width: 200
+   *     }];
+   *   }
+   * });
+   *
+   * // Create a new element or update selected element
+   * await appElement.addOrUpdateElement({
+   *   content: 'Hello from the app',
+   *   timestamp: Date.now()
+   * });
+   * ```
+   *
+   * @example Update with specific placement (deprecated)
+   * ```typescript
+   * import { initAppElement } from "@canva/design";
+   *
+   * const appElement = initAppElement<{ content: string }>({
+   *   render: (data) => {
+   *     return [{
+   *       type: 'text',
+   *       children: [data.content || 'Default text'],
+   *       top: 0,
+   *       left: 0,
+   *       width: 200
+   *     }];
+   *   }
+   * });
+   *
+   * // Create or update with specific placement
+   * await appElement.addOrUpdateElement(
+   *   {
+   *     content: 'Positioned content'
+   *   },
+   *   {
+   *     top: 200,
+   *     left: 200,
+   *     width: 300,
+   *     height: 100
+   *   }
+   * );
+   * ```
    */
   addOrUpdateElement(appElementData: A, placement?: Placement): Promise<void>;
   /**
    * Adds a new app element to the design.
    * @param opts - The data and placement of the app element.
+   *
+   * @example Add new element with data
+   * ```typescript
+   * import { initAppElement } from "@canva/design";
+   *
+   * const appElement = initAppElement<{ content: string; id: string }>({
+   *   render: (data) => {
+   *     return [{
+   *       type: 'text',
+   *       children: [data.content || 'Default text'],
+   *       top: 0,
+   *       left: 0,
+   *       width: 200
+   *     }];
+   *   }
+   * });
+   *
+   * // Add a new element
+   * await appElement.addElement({
+   *   data: {
+   *     content: 'New element content',
+   *     id: 'element-' + Date.now()
+   *   }
+   * });
+   * ```
+   *
+   * @example Add element with specific placement
+   * ```typescript
+   * import { initAppElement } from "@canva/design";
+   *
+   * const appElement = initAppElement<{
+   *   title: string;
+   *   description: string;
+   *   createdAt: number;
+   * }>({
+   *   render: (data) => {
+   *     return [{
+   *       type: 'text',
+   *       children: [data.title || 'Default title'],
+   *       top: 0,
+   *       left: 0,
+   *       width: 300,
+   *       fontWeight: 'bold',
+   *       fontSize: 24
+   *     }, {
+   *       type: 'text',
+   *       children: [data.description || 'Default description'],
+   *       top: 50,
+   *       left: 0,
+   *       width: 300
+   *     }];
+   *   }
+   * });
+   *
+   * // Add element with specific placement
+   * await appElement.addElement({
+   *   data: {
+   *     title: 'Element Title',
+   *     description: 'This is a description of the element',
+   *     createdAt: Date.now()
+   *   },
+   *   placement: {
+   *     top: 100,
+   *     left: 100,
+   *     width: 400,
+   *     height: 150,
+   *     rotation: 0
+   *   }
+   * });
+   * ```
    */
   addElement(opts: AppElementOptions<A>): Promise<void>;
   /**
@@ -121,6 +656,89 @@ export declare interface AppElementClient<A extends AppElementData> {
    * - the user selects an existing app element
    *
    * @param handler - The callback to run when the app element changes.
+   *
+   * @example Handle element selection and update
+   * ```typescript
+   * import { initAppElement } from "@canva/design";
+   *
+   * const appElement = initAppElement<{ content: string }>({
+   *   render: (data) => {
+   *     return [{
+   *       type: 'text',
+   *       children: [data.content || 'Default text'],
+   *       top: 0,
+   *       left: 0,
+   *       width: 200
+   *     }];
+   *   }
+   * });
+   *
+   * // Register a handler for element changes
+   * appElement.registerOnElementChange((element) => {
+   *   if (element) {
+   *     // Element is created or selected
+   *     // Optionally update the element
+   *     // element.update({
+   *     //   data: { ...element.data, lastSelected: Date.now() }
+   *     // });
+   *   } else {
+   *     // No element is selected
+   *   }
+   * });
+   * ```
+   *
+   * @example Update element when selected
+   * ```typescript
+   * import { initAppElement } from "@canva/design";
+   *
+   * const appElement = initAppElement<{
+   *   content: string;
+   *   metadata: { created: number; lastSelected: number };
+   * }>({
+   *   render: (data) => {
+   *     // Render based on data
+   *     return [{
+   *       type: 'text',
+   *       children: [data.content || ''],
+   *       top: 0,
+   *       left: 0,
+   *       width: 200
+   *     }];
+   *   }
+   * });
+   *
+   * // Update element when selected
+   * appElement.registerOnElementChange(async (element) => {
+   *   if (element) {
+   *     // Check if this is a newly created or a selected element
+   *     const isNewElement = !element.data.metadata?.created;
+   *
+   *     if (isNewElement) {
+   *       // Update a new element with initial metadata
+   *       await element.update({
+   *         data: {
+   *           ...element.data,
+   *           metadata: {
+   *             created: Date.now(),
+   *             lastSelected: Date.now()
+   *           }
+   *         }
+   *       });
+   *     } else {
+   *       // Update existing element's last selected time
+   *       await element.update({
+   *         data: {
+   *           ...element.data,
+   *           metadata: {
+   *             ...element.data.metadata,
+   *             lastSelected: Date.now()
+   *           }
+   *         }
+   *       });
+   *     }
+   *   }
+   * });
+   * ```
    */
   registerOnElementChange(handler: AppElementChangeHandler<A>): void;
 }
@@ -344,6 +962,55 @@ export declare interface ContentDraft<T> {
    * - Any changes the app has made to to the content will be reflected in the user's design.
    * - Any changes the user has made to the content since the snapshot was created may be overwritten.
    * - Only properties that are different from the original state will be written to the design.
+   *
+   * @example Save changes to selected text
+   * ```typescript
+   * import { selection } from "@canva/design";
+   *
+   * selection.registerOnChange({
+   *   scope: 'plaintext',
+   *   onChange: async (event) => {
+   *     if (event.count > 0) {
+   *       const draft = await event.read();
+   *
+   *       // Make changes to the content
+   *       for (const content of draft.contents) {
+   *         content.text = content.text.toUpperCase();
+   *       }
+   *
+   *       // Save the changes to the design
+   *       await draft.save();
+   *     }
+   *   }
+   * });
+   * ```
+   *
+   * @example Modify then save rich text content
+   * ```typescript
+   * import { selection } from "@canva/design";
+   *
+   * selection.registerOnChange({
+   *   scope: 'richtext',
+   *   onChange: async (event) => {
+   *     if (event.count > 0) {
+   *       const draft = await event.read();
+   *       const range = draft.contents[0];
+   *
+   *       // Get the plain text
+   *       const text = range.readPlaintext();
+   *
+   *       // Apply formatting to the entire text
+   *       range.formatText(
+   *         { index: 0, length: text.length },
+   *         { fontWeight: 'bold', color: '#0066CC' }
+   *       );
+   *
+   *       // Save the formatted text back to the design
+   *       await draft.save();
+   *     }
+   *   }
+   * });
+   * ```
    */
   save(): Promise<void>;
 }
@@ -385,6 +1052,76 @@ export declare type Coordinates = {
 /**
  * @public
  * Creates a new RichtextRange object, which contains methods to manipulate text.
+ *
+ * @example Create formatted text range
+ * ```typescript
+ * import { createRichtextRange } from "@canva/design";
+ * import type { InlineFormatting } from "@canva/design";
+ *
+ * const range = createRichtextRange();
+ *
+ * range.appendText('Hello World', {
+ *   color: '#000000',
+ *   fontWeight: 'bold'
+ * } as InlineFormatting);
+ * ```
+ *
+ * @example Format paragraph styles
+ * ```typescript
+ * import { createRichtextRange } from "@canva/design";
+ * import type { RichtextFormatting } from "@canva/design";
+ *
+ * const range = createRichtextRange();
+ *
+ * const bounds = range.appendText('Centered Title\n');
+ * range.formatParagraph(bounds.bounds, {
+ *   fontSize: 32,
+ *   textAlign: 'center'
+ * } as RichtextFormatting);
+ * ```
+ *
+ * @example Create bulleted list
+ * ```typescript
+ * import { createRichtextRange } from "@canva/design";
+ *
+ * const range = createRichtextRange();
+ *
+ * const item = range.appendText('List item\n');
+ * range.formatParagraph(item.bounds, {
+ *   fontSize: 16,
+ *   listLevel: 1,
+ *   listMarker: 'disc'
+ * });
+ * ```
+ *
+ * @example Extract text content
+ * ```typescript
+ * import { createRichtextRange } from "@canva/design";
+ *
+ * const range = createRichtextRange();
+ * range.appendText('Sample text');
+ *
+ * // Get plain text content
+ * const text = range.readPlaintext();
+ *
+ * // Get formatted regions
+ * const regions = range.readTextRegions();
+ * ```
+ *
+ * @example Replace text with formatting
+ * ```typescript
+ * import { createRichtextRange } from "@canva/design";
+ *
+ * const range = createRichtextRange();
+ * range.appendText('Original text');
+ *
+ * // Replace text while adding formatting
+ * range.replaceText(
+ *   { index: 0, length: range.readPlaintext().length },
+ *   'Modified',
+ *   { color: '#0066CC', decoration: 'underline' }
+ * );
+ * ```
  */
 export declare const createRichtextRange: () => RichtextRange;
 
@@ -1917,7 +2654,7 @@ export declare type DesignElement =
   | TableElement;
 
 /**
- * @beta
+ * @public
  * Information about the design.
  */
 export declare type DesignMetadata = {
@@ -1941,7 +2678,7 @@ export declare type DesignMetadata = {
    * @remarks
    * The order of pages is not guaranteed.
    */
-  pageMetadata: Iterable<PageContext>;
+  pageMetadata: Iterable<PageMetadata>;
   /**
    * The duration of the whole design in seconds.
    * @remarks
@@ -1973,6 +2710,80 @@ export declare type DesignOverlay = {
   /**
    * Registers a callback that runs when the `canOpen` state of an overlay target changes.
    * @param opts - Options for configuring the callback.
+   *
+   * @example Register overlay handler
+   * ```typescript
+   * import { overlay } from "@canva/design";
+   *
+   * overlay.registerOnCanOpen({
+   *   target: 'image_selection',
+   *   onCanOpen: async (event) => {
+   *     if (event.canOpen) {
+   *       // Can open overlay for selected image
+   *     }
+   *   }
+   * });
+   * ```
+   *
+   * @example Open image editing overlay
+   * ```typescript
+   * import { overlay } from "@canva/design";
+   *
+   * overlay.registerOnCanOpen({
+   *   target: 'image_selection',
+   *   onCanOpen: async (event) => {
+   *     if (event.canOpen) {
+   *       const processId = await event.open({
+   *         launchParameters: {
+   *           mode: 'edit'
+   *         }
+   *       });
+   *       // Overlay process started, with `processId`
+   *     }
+   *   }
+   * });
+   * ```
+   *
+   * @example Open overlay with filters
+   * ```typescript
+   * import { overlay } from "@canva/design";
+   *
+   * overlay.registerOnCanOpen({
+   *   target: 'image_selection',
+   *   onCanOpen: async (event) => {
+   *     if (event.canOpen) {
+   *       await event.open({
+   *         launchParameters: {
+   *           mode: 'edit',
+   *           filters: ['brightness', 'contrast', 'saturation']
+   *         }
+   *       });
+   *     }
+   *   }
+   * });
+   * ```
+   *
+   * @example Handle overlay unavailability
+   * ```typescript
+   * import { overlay } from "@canva/design";
+   *
+   * overlay.registerOnCanOpen({
+   *   target: 'image_selection',
+   *   onCanOpen: async (event) => {
+   *     if (!event.canOpen) {
+   *       // Cannot open overlay, handle specific reasons
+   *       switch (event.reason) {
+   *         case 'no_selection':
+   *           // No image is selected
+   *           break;
+   *         case 'invalid_selection':
+   *           // Selected content cannot be edited
+   *           break;
+   *       }
+   *     }
+   *   }
+   * });
+   * ```
    */
   registerOnCanOpen<Target extends OverlayTarget>(opts: {
     /**
@@ -2003,6 +2814,67 @@ export declare type DesignSelection = {
    *
    * @remarks
    * This callback fires immediately if content is already selected when the callback is registered.
+   *
+   * @example Handling plaintext selection
+   * ```typescript
+   * import { selection } from "@canva/design";
+   *
+   * selection.registerOnChange({
+   *   scope: 'plaintext',
+   *   onChange: async (event) => {
+   *     if (event.count > 0) {
+   *       const draft = await event.read();
+   *       // Do something with the selected text, e.g. `draft.contents[0].text`
+   *     }
+   *   }
+   * });
+   * ```
+   *
+   * @example Handling image selection
+   * ```typescript
+   * import { selection } from "@canva/design";
+   *
+   * selection.registerOnChange({
+   *   scope: 'image',
+   *   onChange: async (event) => {
+   *     if (event.count > 0) {
+   *       const draft = await event.read();
+   *       // Do something with the selected image ref, e.g. `draft.contents[0].ref`
+   *     }
+   *   }
+   * });
+   * ```
+   *
+   * @example Handling video selection
+   * ```typescript
+   * import { selection } from "@canva/design";
+   *
+   * selection.registerOnChange({
+   *   scope: 'video',
+   *   onChange: async (event) => {
+   *     if (event.count > 0) {
+   *       const draft = await event.read();
+   *       // Do something with the selected video ref, e.g. `draft.contents[0].ref`
+   *     }
+   *   }
+   * });
+   * ```
+   *
+   * @example Handling richtext selection
+   * ```typescript
+   * import { selection } from "@canva/design";
+   *
+   * selection.registerOnChange({
+   *   scope: 'richtext',
+   *   onChange: async (event) => {
+   *     if (event.count > 0) {
+   *       const draft = await event.read();
+   *       const range = draft.contents[0];
+   *       // Do something with the selected richtext, e.g. `range.readPlaintext()`
+   *     }
+   *   }
+   * });
+   * ```
    */
   registerOnChange<Scope extends SelectionScope>(opts: {
     /**
@@ -2082,7 +2954,7 @@ export declare function editContent(
 /**
  * @beta
  * A callback for reading and updating the requested design content.
- * @param session - The result of reading the content in the design.
+ * @param session - Session for reading and updating content in the design.
  */
 export declare type EditContentCallback = (
   session: RichtextContentSession | FillContentSession,
@@ -2356,12 +3228,38 @@ export declare type Fill = {
 export declare type FillContent =
   | {
       type: "image";
+      /**
+       * A unique identifier that points to an image asset in Canva's backend.
+       */
       ref: ImageRef;
+      /**
+       * A description of the image content.
+       *
+       * @remarks
+       * Use `undefined` for content with no description.
+       */
+      altText?: AltText;
+      /**
+       * Indicates whether the object containing this fill has been deleted.
+       */
       deleted: boolean;
     }
   | {
       type: "video";
+      /**
+       * A unique identifier that points to an video asset in Canva's backend.
+       */
       ref: VideoRef;
+      /**
+       * A description of the video content.
+       *
+       * @remarks
+       * Use `undefined` for content with no description.
+       */
+      altText?: AltText;
+      /**
+       * Indicates whether the object containing this fill has been deleted.
+       */
       deleted: boolean;
     };
 
@@ -2370,7 +3268,17 @@ export declare type FillContent =
  * Session for reading and updating fill content in a user's design.
  */
 export declare interface FillContentSession {
+  /**
+   * Fill content in the design.
+   */
   readonly contents: readonly FillContent[];
+  /**
+   * 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>;
 }
 
@@ -2401,6 +3309,18 @@ export declare type FontWeight =
  * Allows to get the context of currently selected page.
  * @public
  * @returns Page context of currently selected page
+ *
+ * @example Get current page information
+ * ```typescript
+ * import { getCurrentPageContext } from "@canva/design";
+ *
+ * const pageContext = await getCurrentPageContext();
+ * if (pageContext.dimensions) {
+ *   // Do something with the page dimensions, e.g. `pageContext.dimensions.width` and `pageContext.dimensions.height`
+ * } else {
+ *   // This page type does not have fixed dimensions, e.g. Whiteboard or Doc
+ * }
+ * ```
  */
 export declare const getCurrentPageContext: () => Promise<PageContext>;
 
@@ -2412,20 +3332,92 @@ export declare const getCurrentPageContext: () => Promise<PageContext>;
  * design that is applied whenever a new page is created.
  *
  * Returns `undefined` if the design is unbounded (e.g. Whiteboard or Doc).
+ *
+ * @example Get default page dimensions
+ * ```typescript
+ * import { getDefaultPageDimensions } from "@canva/design";
+ *
+ * const dimensions = await getDefaultPageDimensions();
+ *
+ * if (dimensions) {
+ *   // Do something with the dimensions, e.g. `dimensions.width` and `dimensions.height`
+ * } else {
+ *   // This design type does not have fixed dimensions, e.g. Whiteboard or Doc
+ * }
+ * ```
+ *
+ * @example Center element using page dimensions
+ * ```typescript
+ * import { getDefaultPageDimensions, addElementAtPoint } from "@canva/design";
+ * import type { ImageElementAtPoint } from "@canva/design";
+ *
+ * const dimensions = await getDefaultPageDimensions();
+ *
+ * if (dimensions) {
+ *   const elementWidth = 300;
+ *   const elementHeight = 200;
+ *
+ *   const element: ImageElementAtPoint = {
+ *     type: 'image',
+ *     dataUrl: 'data:image/png;base64,...',
+ *     altText: { text: 'Centered image', decorative: false },
+ *     top: (dimensions.height - elementHeight) / 2,
+ *     left: (dimensions.width - elementWidth) / 2,
+ *     width: elementWidth,
+ *     height: elementHeight
+ *   };
+ *
+ *   await addElementAtPoint(element);
+ * }
+ * ```
  */
 export declare const getDefaultPageDimensions: () => Promise<
   Dimensions | undefined
 >;
 
 /**
- * @beta
+ * @public
  * Retrieves information about the design.
+ *
+ * @example Get design metadata
+ * ```typescript
+ * import { getDesignMetadata } from "@canva/design";
+ *
+ * const metadata = await getDesignMetadata();
+ *
+ * const { title, defaultPageDimensions,  pageMetadata, durationInSeconds } = metadata;
+ * ```
  */
 export declare const getDesignMetadata: () => Promise<DesignMetadata>;
 
 /**
  * @public
  * Retrieves a signed JWT that contains the Design ID, App ID and User ID.
+ *
+ * @example Get design token
+ * ```typescript
+ * import { getDesignToken } from "@canva/design";
+ *
+ * const { token } = await getDesignToken();
+ * ```
+ *
+ * @example Verify token with backend service
+ * ```typescript
+ * import { getDesignToken } from "@canva/design";
+ *
+ * const { token } = await getDesignToken();
+ *
+ * const verifyResponse = await fetch('https://your-backend.com/verify', {
+ *   method: 'POST',
+ *   headers: {
+ *     'Content-Type': 'application/json'
+ *   },
+ *   body: JSON.stringify({ token })
+ * });
+ *
+ * const json = await verifyResponse.json();
+ * const { designId, appId, userId } = json;
+ * ```
  */
 export declare const getDesignToken: () => Promise<DesignToken>;
 
@@ -2579,6 +3571,40 @@ export declare type ImageRef = string & {
 /**
  * @public
  * @param appElementConfig - Configuration for an AppElementClient
+ *
+ * @example Initialize app element client
+ * ```typescript
+ * import { initAppElement } from "@canva/design";
+ *
+ * const appElement = initAppElement<{ content: string }>({
+ *   render: (data) => {
+ *     return [{
+ *       type: 'text',
+ *       children: [data.content],
+ *       top: 100,
+ *       left: 100,
+ *       width: 200
+ *     }];
+ *   }
+ * });
+ * ```
+ *
+ * @example Initialize V2 app element client
+ * ```typescript
+ * import { initAppElement } from "@canva/design";
+ *
+ * const appElement = initAppElement<{ content: string }>({
+ *   render: (data) => {
+ *     return [{
+ *       type: 'text',
+ *       children: [data.content],
+ *       top: 100,
+ *       left: 100,
+ *       width: 200
+ *     }];
+ *   }
+ * });
+ * ```
  */
 export declare const initAppElement: <A extends AppElementData>(
   appElementConfig: AppElementClientConfiguration<A>,
@@ -2869,6 +3895,20 @@ export declare type PageDimensions = {
   height: number;
 };
 
+/**
+ * @public
+ * Information about a page.
+ */
+export declare type PageMetadata = {
+  /**
+   * The dimensions of the page, in pixels.
+   *
+   * @remarks
+   * This may be `undefined` because some types of pages don't have dimensions, such as whiteboards.
+   */
+  dimensions?: PageDimensions;
+};
+
 /**
  * @public
  * The outline of a path.
@@ -2966,10 +4006,121 @@ export declare interface RichtextContentRange extends RichtextRange {
 
 /**
  * @public
- * Session for reading and updating richtext content in a user's design.
+ * A callback for reading and updating the requested design content.
+ * @param session - The result of reading the content in the design.
+ *
+ * @example Read and update richtext content
+ * ```typescript
+ * import { editContent } from "@canva/design";
+ *
+ * await editContent(
+ *   { contentType: 'richtext', target: 'current_page' },
+ *   async (session) => {
+ *     // Read the content
+ *     const contents = session.contents;
+ *
+ *     if (contents.length > 0) {
+ *       const range = contents[0];
+ *
+ *       // Modify the content (e.g., adding text)
+ *       range.appendText("\nAppended text from app");
+ *
+ *       // Sync changes back to the design
+ *       await session.sync();
+ *     }
+ *   }
+ * );
+ * ```
+ *
+ * @example Format all richtext content in the design
+ * ```typescript
+ * import { editContent } from "@canva/design";
+ *
+ * await editContent(
+ *   { contentType: 'richtext', target: 'current_page' },
+ *   async (session) => {
+ *     // Process each richtext range in the content
+ *     for (const range of session.contents) {
+ *       // Skip if the content has been deleted
+ *       if (range.deleted) continue;
+ *
+ *       // Get the text content
+ *       const text = range.readPlaintext();
+ *       if (text.length === 0) continue;
+ *
+ *       // Apply consistent formatting
+ *       range.formatParagraph(
+ *         { index: 0, length: text.length },
+ *         {
+ *           fontRef: 'YOUR_FONT_REF',
+ *           fontSize: 16,
+ *           textAlign: 'start'
+ *         }
+ *       );
+ *     }
+ *
+ *     // Sync all changes back to the design
+ *     await session.sync();
+ *   }
+ * );
+ * ```
+ *
+ * @example Modify content without saving changes
+ * ```typescript
+ * import { editContent } from "@canva/design";
+ *
+ * await editContent(
+ *   { contentType: 'richtext', target: 'current_page' },
+ *   async (session) => {
+ *     // Read and analyze the content without making changes
+ *     for (const range of session.contents) {
+ *       const text = range.readPlaintext();
+ *       // Do something with the content preview, e.g. `text.substring(0, 50)`
+ *
+ *       // No call to session.sync() means no changes are saved
+ *     }
+ *
+ *     // Since we're not calling sync(), no changes will be made to the design
+ *   }
+ * );
+ * ```
  */
 export declare interface RichtextContentSession {
+  /**
+   * Richtext content in the design.
+   */
   readonly contents: readonly RichtextContentRange[];
+  /**
+   * 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.
+   *
+   * @example Sync changes after modifying content
+   * ```typescript
+   * import { editContent } from "@canva/design";
+   *
+   * await editContent(
+   *   { contentType: 'richtext', target: 'current_page' },
+   *   async (session) => {
+   *     if (session.contents.length > 0) {
+   *       const range = session.contents[0];
+   *
+   *       // Make modifications to the content
+   *       range.appendText(" - Modified by app");
+   *
+   *       try {
+   *         // Save changes back to the design
+   *         await session.sync();
+   *       } catch (error) {
+   *         console.error('Failed to sync changes:', error);
+   *       }
+   *     }
+   *   }
+   * );
+   * ```
+   */
   sync(): Promise<void>;
 }
 
@@ -3063,6 +4214,42 @@ export declare type RichtextRange = {
    * - The `\n` character indicates the end of a paragraph.
    * - All paragraphs that overlap the provided bounds will be formatted in their entirety.
    *
+   * @example Format paragraph as a heading
+   * ```typescript
+   * import { createRichtextRange } from "@canva/design";
+   *
+   * const range = createRichtextRange();
+   *
+   * range.appendText("Heading Text\nRegular paragraph text.");
+   *
+   * // Format just the first paragraph as a heading
+   * range.formatParagraph(
+   *   { index: 0, length: 12 }, // Only need to include part of the paragraph
+   *   {
+   *     fontSize: 24,
+   *     fontWeight: 'bold',
+   *     textAlign: 'center'
+   *   }
+   * );
+   * ```
+   *
+   * @example Create a bulleted list
+   * ```typescript
+   * import { createRichtextRange } from "@canva/design";
+   *
+   * const range = createRichtextRange();
+   * const text = "Item 1\nItem 2\nItem 3";
+   * range.appendText(text);
+   *
+   * // Format all paragraphs as a bulleted list
+   * range.formatParagraph(
+   *   { index: 0, length: text.length },
+   *   {
+   *     listLevel: 1,
+   *     listMarker: 'disc'
+   *   }
+   * );
+   * ```
    */
   formatParagraph(bounds: Bounds, formatting: RichtextFormatting): void;
   /**
@@ -3070,13 +4257,79 @@ export declare type RichtextRange = {
    *
    * @param bounds - The segment of the range on which to apply the formatting.
    * @param formatting - The formatting to apply to the text.
+   *
+   * @example Format specific words in a paragraph
+   * ```typescript
+   * import { createRichtextRange } from "@canva/design";
+   *
+   * const range = createRichtextRange();
+   * range.appendText("This text contains important information.");
+   *
+   * // Format just the word "important"
+   * range.formatText(
+   *   { index: 16, length: 9 },
+   *   {
+   *     fontWeight: 'bold',
+   *     color: '#FF0000'
+   *   }
+   * );
+   * ```
+   *
+   * @example Add a link to text
+   * ```typescript
+   * import { createRichtextRange } from "@canva/design";
+   *
+   * const range = createRichtextRange();
+   * range.appendText("Visit our website for more information.");
+   *
+   * // Add a link to "our website"
+   * range.formatText(
+   *   { index: 6, length: 11 },
+   *   {
+   *     link: "https://www.example.com",
+   *     decoration: 'underline',
+   *     color: '#0066CC'
+   *   }
+   * );
+   * ```
    */
   formatText(bounds: Bounds, formatting: InlineFormatting): void;
   /**
    * Appends the specified characters to the end of the range.
    *
    * @param characters - The characters to append to the richtext range.
-   * @param fo -
+   * @param formatting - Optional formatting to apply to the appended text.
+   *
+   * @example Append plain text
+   * ```typescript
+   * import { createRichtextRange } from "@canva/design";
+   *
+   * const range = createRichtextRange();
+   * range.appendText("First paragraph. ");
+   *
+   * // Append more text to the existing content
+   * const result = range.appendText("This is additional text.");
+   *
+   * // The bounds of the newly added text are returned
+   * // Do something with the bounds - result.bounds, e.g. { index: 17, length: 24 }
+   * ```
+   *
+   * @example Append formatted text
+   * ```typescript
+   * import { createRichtextRange } from "@canva/design";
+   *
+   * const range = createRichtextRange();
+   * range.appendText("Normal text followed by ");
+   *
+   * // Append formatted text
+   * range.appendText("bold red text", {
+   *   fontWeight: 'bold',
+   *   color: '#FF0000'
+   * });
+   *
+   * // Append a new paragraph
+   * range.appendText("\nThis is a new paragraph.");
+   * ```
    */
   appendText(
     characters: string,
@@ -3090,6 +4343,42 @@ export declare type RichtextRange = {
    * @param bounds - The segment of the range to replace.
    * @param characters - The replacement characters.
    * @param formatting - The formatting to apply to the replaced text.
+   *
+   * @example Replace text while maintaining some formatting
+   * ```typescript
+   * import { createRichtextRange } from "@canva/design";
+   *
+   * const range = createRichtextRange();
+   * range.appendText("This text needs correction.");
+   *
+   * // Replace "needs correction" with "is correct"
+   * const result = range.replaceText(
+   *   { index: 10, length: 16 },
+   *   "is correct"
+   * );
+   *
+   * // The bounds of the replaced text are returned
+   * // Do something with the bounds - result.bounds, e.g. { index: 10, length: 10 }
+   * ```
+   *
+   * @example Replace text with formatted text
+   * ```typescript
+   * import { createRichtextRange } from "@canva/design";
+   *
+   * const range = createRichtextRange();
+   * range.appendText("Regular text that needs emphasis.");
+   *
+   * // Replace "needs emphasis" with formatted text
+   * range.replaceText(
+   *   { index: 17, length: 15 },
+   *   "is important",
+   *   {
+   *     fontWeight: 'bold',
+   *     fontStyle: 'italic',
+   *     color: '#0066CC'
+   *   }
+   * );
+   * ```
    */
   replaceText(
     bounds: Bounds,
@@ -3103,11 +4392,87 @@ export declare type RichtextRange = {
   };
   /**
    * Returns the current state of the richtext as plaintext.
+   *
+   * @example Extract plain text content
+   * ```typescript
+   * import { createRichtextRange } from "@canva/design";
+   *
+   * const range = createRichtextRange();
+   * range.appendText("First paragraph.\n", { fontWeight: 'bold' });
+   * range.appendText("Second paragraph with formatting.", { color: '#FF0000' });
+   *
+   * // Get plain text content without formatting
+   * const plainText = range.readPlaintext();
+   * // Do something with the plain text - plainText, e.g. "First paragraph.\nSecond paragraph with formatting."
+   * ```
+   *
+   * @example Search within text content
+   * ```typescript
+   * import { createRichtextRange } from "@canva/design";
+   *
+   * const range = createRichtextRange();
+   * range.appendText("This text contains a searchable term.");
+   *
+   * // Search for a specific word
+   * const plainText = range.readPlaintext();
+   * const searchTerm = "searchable";
+   * const index = plainText.indexOf(searchTerm);
+   *
+   * if (index !== -1) {
+   *   // Format the found term
+   *   range.formatText(
+   *     { index, length: searchTerm.length },
+   *     { fontWeight: 'bold', decoration: 'underline' }
+   *   );
+   * }
+   * ```
    */
   readPlaintext(): string;
   /**
    * Returns the current state of the richtext as one or more text regions.
    * Each region is an object that contains the text content and its formatting.
+   *
+   * @example Get text with formatting information
+   * ```typescript
+   * import { createRichtextRange } from "@canva/design";
+   *
+   * const range = createRichtextRange();
+   * range.appendText("Normal text ", {});
+   * range.appendText("bold text", { fontWeight: 'bold' });
+   * range.appendText(" and ", {});
+   * range.appendText("red text", { color: '#FF0000' });
+   *
+   * // Get formatted regions
+   * const regions = range.readTextRegions();
+   * // Do something with the regions, e.g.
+   * // [
+   * //   { text: "Normal text ", formatting: {} },
+   * //   { text: "bold text", formatting: { fontWeight: 'bold' } },
+   * //   { text: " and ", formatting: {} },
+   * //   { text: "red text", formatting: { color: '#FF0000' } }
+   * // ]
+   * ```
+   *
+   * @example Analyze formatting variations
+   * ```typescript
+   * import { createRichtextRange } from "@canva/design";
+   *
+   * const range = createRichtextRange();
+   * range.appendText("Mixed ", {});
+   * range.appendText("formatted ", { fontWeight: 'bold' });
+   * range.appendText("text", { color: '#0066CC' });
+   *
+   * // Analyze formatting variations
+   * const regions = range.readTextRegions();
+   * const formattingTypes = regions.map(region => {
+   *   const formatting = region.formatting || {};
+   *   return {
+   *     text: region.text,
+   *     hasWeight: !!formatting.fontWeight,
+   *     hasColor: !!formatting.color
+   *   };
+   * });
+   * ```
    */
   readTextRegions(): TextRegion[];
 };
@@ -3137,17 +4502,68 @@ export declare interface SelectionEvent<Scope extends SelectionScope> {
    * Any changes made to `contents` are not immediately persisted or reflected in the user's design.
    * To persist the changes, call the `save` method that's available via the draft.
    *
-   * @example Replacing text
+   * @example Read and modify plaintext selection
+   * ```typescript
+   * import { selection } from "@canva/design";
+   *
+   * selection.registerOnChange({
+   *   scope: 'plaintext',
+   *   onChange: async (event) => {
+   *     if (event.count > 0) {
+   *       // Read the content
+   *       const draft = await event.read();
+   *
+   *       // Handle selected text `draft.contents[0].text`
+   *
+   *       // Modify the text if needed
+   *       // draft.contents[0].text = 'Modified text';
+   *       // await draft.save();
+   *     }
+   *   }
+   * });
    * ```
-   * const draft = await selectionEvent.read();
    *
-   * for(const content of draft.contents) {
-   *     // This change won't immediately appear in the user's design
-   *     content.text = "This is the new text";
-   * }
+   * @example Read and analyze image selection
+   * ```typescript
+   * import { selection } from "@canva/design";
    *
-   * // The changes will now appear in the user's design
-   * await draft.save();
+   * selection.registerOnChange({
+   *   scope: 'image',
+   *   onChange: async (event) => {
+   *     // Check if any images are selected
+   *     if (event.count === 0) {
+   *       // Handle no images selected case
+   *       return;
+   *     }
+   *
+   *     // Read the content
+   *     const draft = await event.read();
+   *
+   *     // Get information about selected images
+   *     const imageRefs = draft.contents.map(content => content.ref);
+   *
+   *     // The ref can be used with other API methods
+   *   }
+   * });
+   * ```
+   *
+   * @example Process multiple selected items
+   * ```typescript
+   * import { selection } from "@canva/design";
+   *
+   * selection.registerOnChange({
+   *   scope: 'richtext',
+   *   onChange: async (event) => {
+   *     if (event.count > 0) {
+   *       const draft = await event.read();
+   *
+   *       // Process each selected range
+   *       draft.contents.forEach((range) => {
+   *         // Do something with the range content and formatted regions, with `range.readPlaintext()` and `range.readTextRegions()`
+   *       });
+   *     }
+   *   }
+   * });
    * ```
    */
   read(): Promise<ContentDraft<SelectionValue<Scope>>>;
@@ -3230,6 +4646,56 @@ export declare type SelectionValue<Scope extends SelectionScope> = {
  * @public
  * Updates the background of the user's current page. The background can be a solid color,
  * an image or a video.
+ *
+ * @example Set background color
+ * ```typescript
+ * import { setCurrentPageBackground } from "@canva/design";
+ * import type { PageBackgroundFill } from "@canva/design";
+ *
+ * const background: PageBackgroundFill = {
+ *   color: '#F5F5F5',
+ * };
+ *
+ * await setCurrentPageBackground(background);
+ * ```
+ *
+ * @example Set background image
+ * ```typescript
+ * import { setCurrentPageBackground } from "@canva/design";
+ * import type { PageBackgroundFill } from "@canva/design";
+ * import type { ImageRef } from "@canva/asset";
+ *
+ * const exampleImageRef = "YOUR_IMAGE_REF" as ImageRef;
+ *
+ * const background: PageBackgroundFill = {
+ *   asset: {
+ *     type: 'image',
+ *     ref: exampleImageRef,
+ *     altText: { text: 'Background image', decorative: true }
+ *   },
+ * };
+ *
+ * await setCurrentPageBackground(background);
+ * ```
+ *
+ * @example Set background video
+ * ```typescript
+ * import { setCurrentPageBackground } from "@canva/design";
+ * import type { PageBackgroundFill } from "@canva/design";
+ * import type { VideoRef } from "@canva/asset";
+ *
+ * const exampleVideoRef = "YOUR_VIDEO_REF" as VideoRef;
+ *
+ * const background: PageBackgroundFill = {
+ *   asset: {
+ *     type: 'video',
+ *     ref: exampleVideoRef,
+ *     altText: { text: 'Background video', decorative: true }
+ *   },
+ * };
+ *
+ * await setCurrentPageBackground(background);
+ * ```
  */
 export declare const setCurrentPageBackground: (
   opts: PageBackgroundFill,