[WXP-4327] Stabilize HLAPIs like clone node,text layout, paragraph styling

src/pages/references/changelog.md

@@ -25,6 +25,45 @@ contributors:
 
 # Changelog
 
+## 2025-10-08
+
+### Added
+
+- **Experimental** [`rescaleProportionalToHeight()`](../references/document-sandbox/document-apis/classes/Node.md#rescaleproportionaltoheight) method - Proportional height scaling for all node types
+- **Experimental** [`rescaleProportionalToWidth()`](../references/document-sandbox/document-apis/classes/Node.md#rescaleproportionaltowidth) method - Proportional width scaling for all node types  
+- **Experimental** [`resizeToCover()`](../references/document-sandbox/document-apis/classes/Node.md#resizetocover) method - Resize nodes to cover specified dimensions
+- **Experimental** [`resizeToFitWithin()`](../references/document-sandbox/document-apis/classes/Node.md#resizetofitwithin) method - Resize nodes to fit within specified dimensions
+- **Experimental** [`appendText()`](../references/document-sandbox/document-apis/classes/TextContentModel.md#appendtext) method - Append text to existing content
+- **Experimental** [`deleteText()`](../references/document-sandbox/document-apis/classes/TextContentModel.md#deletetext) method - Delete text ranges from content
+- **Experimental** [`insertText()`](../references/document-sandbox/document-apis/classes/TextContentModel.md#inserttext) method - Insert text at specific positions
+- **Experimental** [`replaceText()`](../references/document-sandbox/document-apis/classes/TextContentModel.md#replacetext) method - Replace text ranges with new content
+- **Experimental** [`hasUnavailableFonts()`](../references/document-sandbox/document-apis/classes/TextContentModel.md#hasunavailablefonts) method - Check for unavailable fonts in text content
+- **Experimental** [`id`](../references/document-sandbox/document-apis/classes/TextContentModel.md#id) property - Unique identifier for text content models
+- **Experimental** [`TextStyleSource`](../references/document-sandbox/document-apis/namespaces/Constants/enumerations/TextStyleSource.md) enumeration - Options for text style source matching
+
+### Updated
+
+- [`cloneInPlace()`](../references/document-sandbox/document-apis/classes/Node.md#cloneinplace) method **promoted from experimental to stable** - Available on all node types for creating copies with subtrees
+- [`paragraphStyleRanges`](../references/document-sandbox/document-apis/classes/TextContentModel.md#paragraphstyleranges) property **promoted from experimental to stable** - Get/set paragraph-level styles with ranges
+- [`applyParagraphStyles()`](../references/document-sandbox/document-apis/classes/TextContentModel.md#applyparagraphstyles) method **promoted from experimental to stable** - Apply styles to specific paragraph ranges
+- [`layout`](../references/document-sandbox/document-apis/classes/StandaloneTextNode.md#layout) property **promoted from experimental to stable** - Control text layout modes for standalone text
+- [`layout`](../references/document-sandbox/document-apis/classes/ThreadedTextNode.md#layout) property **promoted from experimental to stable** - Control text layout modes for threaded text
+- [`AreaTextLayout`](../references/document-sandbox/document-apis/interfaces/AreaTextLayout.md) interface **promoted from experimental to stable** - Fixed width and height text layout configuration
+- [`AutoHeightTextLayout`](../references/document-sandbox/document-apis/interfaces/AutoHeightTextLayout.md) interface **promoted from experimental to stable** - Auto-height text layout configuration
+- [`AutoWidthTextLayout`](../references/document-sandbox/document-apis/interfaces/AutoWidthTextLayout.md) interface **promoted from experimental to stable** - Auto-width text layout configuration
+- [`UnsupportedTextLayout`](../references/document-sandbox/document-apis/interfaces/UnsupportedTextLayout.md) interface **promoted from experimental to stable** - Representation of unsupported text layouts
+- [`ParagraphStyles`](../references/document-sandbox/document-apis/interfaces/ParagraphStyles.md) interface **promoted from experimental to stable** - Complete paragraph style definitions
+- [`ParagraphStylesInput`](../references/document-sandbox/document-apis/interfaces/ParagraphStylesInput.md) interface **promoted from experimental to stable** - Input interface for paragraph styles
+- [`ParagraphStylesRange`](../references/document-sandbox/document-apis/interfaces/ParagraphStylesRange.md) interface **promoted from experimental to stable** - Paragraph styles with text ranges
+- [`ParagraphStylesRangeInput`](../references/document-sandbox/document-apis/interfaces/ParagraphStylesRangeInput.md) interface **promoted from experimental to stable** - Input interface for paragraph style ranges
+- [`BaseParagraphStyles`](../references/document-sandbox/document-apis/interfaces/BaseParagraphStyles.md) interface **promoted from experimental to stable** - Base paragraph style properties
+- [`OrderedListStyleInput`](../references/document-sandbox/document-apis/interfaces/OrderedListStyleInput.md) interface **promoted from experimental to stable** - Configuration for ordered lists
+- [`UnorderedListStyleInput`](../references/document-sandbox/document-apis/interfaces/UnorderedListStyleInput.md) interface **promoted from experimental to stable** - Configuration for unordered lists
+- [`OrderedListStyle`](../references/document-sandbox/document-apis/type-aliases/OrderedListStyle.md) type **promoted from experimental to stable** - Type definition for ordered list styles
+- [`UnorderedListStyle`](../references/document-sandbox/document-apis/type-aliases/UnorderedListStyle.md) type **promoted from experimental to stable** - Type definition for unordered list styles
+- [`OrderedListNumbering`](../references/document-sandbox/document-apis/namespaces/Constants/enumerations/OrderedListNumbering.md) enumeration **promoted from experimental to stable** - Numbering types for ordered lists
+- [`ParagraphListType`](../references/document-sandbox/document-apis/namespaces/Constants/enumerations/ParagraphListType.md) enumeration **promoted from experimental to stable** - List type enumeration with `none` value added
+
 ## 2025-10-02
 
 ### Added

src/pages/references/document-sandbox/document-apis/classes/AddOnData.md

@@ -18,8 +18,8 @@ This metadata is accessible only to the add-on that has set it.
 an object with the remaining quota for private metadata on the node for this add-on.
 The object contains the following properties:
 
-- sizeInBytes: The remaining quota size in bytes (maximum 3KB).
-- numKeys: The remaining quota for the number of keys (maximum 20 keys).
+- `sizeInBytes`: The remaining quota size in bytes (maximum 3KB).
+- `numKeys`: The remaining quota for the number of keys (maximum 20 keys).
 
 ##### numKeys
 

src/pages/references/document-sandbox/document-apis/classes/ArtboardList.md

@@ -2,8 +2,8 @@
 
 # Class: ArtboardList
 
-ArtboardList represents an ordered list of ArtboardNodes arranged in a timeline sequence, where they are called "scenes."
-All items in the list are children of a single [PageNode](PageNode.md).
+ArtboardList represents an ordered list of ArtboardNodes, which are the children of one [PageNode](PageNode.md). If multiple
+artboards are present, each represents a keyframe "scene" in the page's animation timeline.
 
 ArtboardList also provides APIs for adding/removing artboards from the page. ArtboardList is never empty: it is illegal to
 remove the last remaining artboard from the list.

src/pages/references/document-sandbox/document-apis/classes/ArtboardNode.md

@@ -2,14 +2,11 @@
 
 # Class: ArtboardNode
 
-An ArtboardNode represents an artboard object in the scenegraph. All user visual content must be contained on an artboard.
-Artboards are always contained on a [PageNode](PageNode.md); when a page contains multiple artboards, the artboards represent
-"scenes" in a linear timeline sequence.
+An ArtboardNode represents the topmost container of visual content within a [PageNode](PageNode.md). When a page contains
+multiple artboards, each represents a keyframe "scene" in the page's animation timeline.
 
 To create a new artboard, see [ArtboardList.addArtboard](ArtboardList.md#addartboard).
 
-Please note that creating and deleting an artboard in a single frame will crash the editor.
-
 ## Extends
 
 -   [`VisualNode`](VisualNode.md)
@@ -42,7 +39,7 @@ GroupNode also provide a mutable [ContainerNode.children](../interfaces/Containe
 hold children in various discrete "slots"; this `allChildren` list includes *all* such children and reflects their
 overall display z-order.
 
-The children of an Artboard are always other Node classes (never the more minimal BaseNode).
+The children of an Artboard are all subclasses of Node (not just the more minimal BaseNode or VisualNode).
 
 #### Returns
 
@@ -83,7 +80,9 @@ Position of the node's centerpoint in its own local coordinate space, i.e. the c
 
 • `get` **children**(): [`ItemList`](ItemList.md)<[`Node`](Node.md)\>
 
-The node's children. Use the methods on this ItemList object to get, add, and remove children.
+The artboards's regular children (does not include any "background layer" content if present; use [allChildren](ArtboardNode.md#allchildren)
+for a read-only view that includes background content). Use the methods on this `children` ItemList object to get,
+add, and remove regular children.
 
 #### Returns
 

src/pages/references/document-sandbox/document-apis/classes/BitmapImage.md

@@ -2,8 +2,7 @@
 
 # Class: BitmapImage
 
-Represents a bitmap image resource. Use [Editor.loadBitmapImage](Editor.md#loadbitmapimage) to create a BitmapImage, and then [Editor.createImageContainer](Editor.md#createimagecontainer)
-to display it in the document by creating a MediaContainerNode structure.
+Represents a bitmap image resource. Use [Editor.loadBitmapImage](Editor.md#loadbitmapimage) to create a BitmapImage, and then [Editor.createImageContainer](Editor.md#createimagecontainer) to display it in the document by creating a MediaContainerNode structure.
 
 ## Accessors
 

src/pages/references/document-sandbox/document-apis/classes/ComplexShapeNode.md

@@ -338,10 +338,6 @@ relative to one another (the target node need not be an ancestor of this node, n
 
 • **cloneInPlace**(): [`ComplexShapeNode`](ComplexShapeNode.md)
 
-<InlineAlert slots="text" variant="warning"/>
-
-**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
-
 Creates a copy of this node and its entire subtree of descendants.
 
 The node must be attached to a page as the copy will be added as a sibling.

src/pages/references/document-sandbox/document-apis/classes/Context.md

@@ -15,6 +15,7 @@ Contains the user's current selection state, indicating the content they are foc
 [`PageNode`](PageNode.md)
 
 The currently viewed page.
+To change the current page, call [Viewport.bringIntoView](Viewport.md#bringintoview) with an artboard or other content on that page.
 
 ---
 
@@ -68,7 +69,8 @@ Only node(s) that meet the following criteria can be selected:
 
 readonly [`Node`](Node.md)[]
 
-the current selection. Nodes that are locked or otherwise non-editable are never included in the selection.
+the current selection. Nodes that are locked or otherwise non-editable are never included in the regular
+selection (see [selectionIncludingNonEditable](Context.md#selectionincludingnoneditable) to get any locked nodes the user may have clicked).
 
 ---
 
@@ -115,6 +117,7 @@ Callback that was previously registered will be removed and will no more be invo
 
 Registers a handler for editor events such as selection change.
 The registered callback will be invoked when the specified event occurs.
+<InlineAlert slots="text" variant="info"/>
 Note: Do not attempt to make changes to the document in response to a selection change callback because it may destabilize the application.
 
 #### Parameters

src/pages/references/document-sandbox/document-apis/classes/Editor.md

@@ -69,15 +69,17 @@ This local client will act as having unsaved changes until the upload has finish
 
 #### Parameters
 
-• **bitmapData**: [`BitmapImage`](BitmapImage.md)
+• **bitmapData**: `BitmapImage`
 
 BitmapImage resource (e.g. returned from [loadBitmapImage](Editor.md#loadbitmapimage)).
 
 • **options**= `{}`
 
-Additional configuration: - initialSize - Size the image is displayed at. Must have the same aspect ratio as bitmapData. Defaults to the
-size the image would be created at by a UI drag-drop gesture (typically the image's full size, but scaled down
-if needed to stay below an application-defined size cap).
+Additional configuration:
+
+-   `initialSize` - Size the image is displayed at. Must have the same aspect ratio as `bitmapData`. Defaults to the
+    size the image would be created at by a UI drag-drop gesture (typically the image's full size, but scaled down
+    if needed to stay below an application-defined size cap).
 
 • **options.initialSize?**: [`RectangleGeometry`](../interfaces/RectangleGeometry.md)
 
@@ -115,6 +117,11 @@ Note that the path data will be normalized, and therefore the `path` getter may
 For example, "M 10 80 Q 52.5 10, 95 80 T 180 80" becomes "M 10 80 C 38.33 33.33 66.67 33.33 95 80...".
 Throws if the input is empty or is not legal SVG path syntax.
 
+<InlineAlert slots="text" variant="info"/>
+
+Note: the visual top-left corner of a path may not be its local (0,0) origin point, so it's easiest to position
+a newly created path using [Node.setPositionInParent](Node.md#setpositioninparent) rather than setting [Node.translation](Node.md#translation) directly.
+
 #### Returns
 
 [`PathNode`](PathNode.md)
@@ -171,14 +178,16 @@ the initial string to show.
 a text node with default styles. Creates auto-width text, so the node's width will automatically adjust
 to accommodate the given text content.
 
+<InlineAlert slots="text" variant="info"/>
+
 Note: the registration point of this text node is not guaranteed to be at the top-left of the bounding box of its
 insertion parent. Recommend using `setPositionInParent` over `translation` to set the position.
 
 ---
 
 ### loadBitmapImage()
 
-• **loadBitmapImage**(`bitmapData`): `Promise`<[`BitmapImage`](BitmapImage.md)\>
+• **loadBitmapImage**(`bitmapData`): `Promise`<`BitmapImage`\>
 
 Creates a bitmap image resource in the document, which can be displayed in the scenegraph by passing it to [createImageContainer](Editor.md#createimagecontainer)
 to create a MediaContainerNode. The same BitmapImage can be used to create multiple MediaContainerNodes.
@@ -198,7 +207,7 @@ Encoded image data in PNG or JPEG format.
 
 #### Returns
 
-`Promise`<[`BitmapImage`](BitmapImage.md)\>
+`Promise`<`BitmapImage`\>
 
 ---
 

src/pages/references/document-sandbox/document-apis/classes/EllipseNode.md

@@ -381,10 +381,6 @@ relative to one another (the target node need not be an ancestor of this node, n
 
 • **cloneInPlace**(): [`EllipseNode`](EllipseNode.md)
 
-<InlineAlert slots="text" variant="warning"/>
-
-**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
-
 Creates a copy of this node and its entire subtree of descendants.
 
 The node must be attached to a page as the copy will be added as a sibling.

src/pages/references/document-sandbox/document-apis/classes/ExpressRootNode.md

@@ -3,8 +3,7 @@
 # Class: ExpressRootNode
 
 An ExpressRootNode represents the root node of the document's "scenegraph" artwork tree. The root contains a collection
-of [pages](ExpressRootNode.md#pages). Each page contains one or more artboards, arranged in a timeline sequence. All the visual content of
-the document lies within those artboards.
+of [pages](ExpressRootNode.md#pages). Each page contains one or more artboards, which in turn hold all the visual content of the document.
 
 The parent of ExpressRootNode is undefined, since it is the root of the document tree.
 

src/pages/references/document-sandbox/document-apis/classes/FillableNode.md

@@ -348,10 +348,6 @@ relative to one another (the target node need not be an ancestor of this node, n
 
 • **cloneInPlace**(): [`FillableNode`](FillableNode.md)
 
-<InlineAlert slots="text" variant="warning"/>
-
-**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
-
 Creates a copy of this node and its entire subtree of descendants.
 
 The node must be attached to a page as the copy will be added as a sibling.

src/pages/references/document-sandbox/document-apis/classes/GridCellNode.md

@@ -331,10 +331,6 @@ relative to one another (the target node need not be an ancestor of this node, n
 
 • **cloneInPlace**(): `never`
 
-<InlineAlert slots="text" variant="warning"/>
-
-**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
-
 Always throws as it's not possible to clone a single grid slot.
 Use the parent grid container instead.
 
@@ -403,9 +399,9 @@ or top/bottom edges. Currently only supports images as the new media, but previo
 
 #### Parameters
 
-• **media**: [`BitmapImage`](BitmapImage.md)
+• **media**: `BitmapImage`
 
-New content to display. Currently must be a [BitmapImage](BitmapImage.md).
+New content to display. Currently must be a BitmapImage.
 
 #### Returns
 

src/pages/references/document-sandbox/document-apis/classes/GridLayoutNode.md

@@ -2,8 +2,8 @@
 
 # Class: GridLayoutNode
 
-A GridLayoutNode represents a grid layout in the scenegraph. The GridLayoutNode is used to create
-a layout grid that other content can be placed into.
+A GridLayoutNode represents a grid layout in the scenegraph. Currently, grids contain only images but in the future
+they may support other types of content as well.
 
 APIs to create a new grid layout are not yet available.
 
@@ -33,9 +33,8 @@ Get [AddOnData](AddOnData.md) reference for managing the private metadata on thi
 
 • `get` **allChildren**(): `Readonly`<`Iterable`<[`GridCellNode`](GridCellNode.md), `any`, `any`\>\>
 
-The Grid's regular children. Does not include rectangles and skips over media constainer nodes to return fill grandchildren.
-Grid Cells are ordered by the y and then x position of their top left corner, i.e. left to right and top to bottom.
-The children cannot be added or removed.
+The GridLayout's child nodes. Nodes are returned in order sorted by the y and then x position of their top left
+corner, i.e. left to right and top to bottom. These children cannot be added or removed.
 
 #### Returns
 
@@ -113,7 +112,7 @@ Position of the node's centerpoint in its own local coordinate space, i.e. the c
 
 • `set` **fill**(`fill`): `void`
 
-The background fill of the GridLayout.
+The background fill of the GridLayout. GridLayouts must always have a fill.
 
 #### Parameters
 
@@ -129,7 +128,7 @@ The background fill of the GridLayout.
 
 • `get` **height**(): `number`
 
-The height of the node.
+The height of the entire GridLayout node.
 Must be at least MIN_DIMENSION.
 
 • `set` **height**(`value`): `void`
@@ -318,7 +317,7 @@ meaningful comparison or conversion between the bounds or coordinate spaces of s
 
 • `get` **width**(): `number`
 
-The width of the node.
+The width of the entire GridLayout node.
 Must be at least MIN_DIMENSION.
 
 • `set` **width**(`value`): `void`
@@ -359,10 +358,6 @@ relative to one another (the target node need not be an ancestor of this node, n
 
 • **cloneInPlace**(): [`GridLayoutNode`](GridLayoutNode.md)
 
-<InlineAlert slots="text" variant="warning"/>
-
-**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
-
 Creates a copy of this node and its entire subtree of descendants.
 
 The node must be attached to a page as the copy will be added as a sibling.