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

src/pages/guides/getting_started/changelog.md

@@ -64,7 +64,7 @@ The following how-to guides have been updated with `ImportAddOnData` support for
 **IMPORTANT:** The [`cloneInPlace()`](../../references/document-sandbox/document-apis/classes/Node.md#cloneInPlace) method 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 this method, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../references/manifest/index.md#requirements) section of the `manifest.json`.
 
 - Updated [`maskShape`](../../references/document-sandbox/document-apis/classes/GridCellNode.md#maskShape) in `GridCellNode` to readonly.
-- The [`BitmapImage`](../../references/document-sandbox/document-apis/classes/BitmapImage.md) has been converted from an interface to a class.
+- The `BitmapImage` has been converted from an interface to a class.
 
 ## 2025-09-01
 

src/pages/guides/learn/how_to/use_images.md

@@ -160,7 +160,7 @@ All image formats are equal, but some formats are more equal than others. Please
 
 ## Replace Media
 
-The [`replaceMedia()`](../../../references/document-sandbox/document-apis/classes/MediaContainerNode.md#replacemedia) method can be used to replace an existing media with a new one. It accepts a single argument of type [`BitmapImage`](../../../references/document-sandbox/document-apis/classes/BitmapImage.md).
+The [`replaceMedia()`](../../../references/document-sandbox/document-apis/classes/MediaContainerNode.md#replacemedia) method can be used to replace an existing media with a new one. It accepts a single argument of type `BitmapImage`.
 
 <InlineAlert slots="text" variant="info"/>
 

src/pages/references/changelog.md

@@ -67,7 +67,7 @@ The following how-to guides have been updated with `ImportAddOnData` support for
 **IMPORTANT:** The [`cloneInPlace()`](../references/document-sandbox/document-apis/classes/Node.md#cloneInPlace) method 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 this method, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](./manifest/index.md#requirements) section of the `manifest.json`.
 
 - Updated [`maskShape`](../references/document-sandbox/document-apis/classes/GridCellNode.md#maskShape) in `GridCellNode` to readonly.
-- The [`BitmapImage`](../references/document-sandbox/document-apis/classes/BitmapImage.md) has been converted from an interface to a class.
+- The `BitmapImage` has been converted from an interface to a class.
 
 ## 2025-09-01
 

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/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.
@@ -403,6 +399,8 @@ removal. No-op if node is already an orphan.
 
 ### rescaleProportionalToHeight()
 
+`Experimental`
+
 • **rescaleProportionalToHeight**(`height`): `void`
 
 <InlineAlert slots="text" variant="warning"/>
@@ -428,6 +426,8 @@ preserve its existing aspect ratio. See [rescaleProportionalToWidth](Node.md#res
 
 ### rescaleProportionalToWidth()
 
+`Experimental`
+
 • **rescaleProportionalToWidth**(`width`): `void`
 
 <InlineAlert slots="text" variant="warning"/>
@@ -460,6 +460,8 @@ a separate, persistent scale factor multiplier).
 
 ### resizeToCover()
 
+`Experimental`
+
 • **resizeToCover**(`width`, `height`): `void`
 
 <InlineAlert slots="text" variant="warning"/>
@@ -493,6 +495,8 @@ resizeToFitWithin
 
 ### resizeToFitWithin()
 
+`Experimental`
+
 • **resizeToFitWithin**(`width`, `height`): `void`
 
 <InlineAlert slots="text" variant="warning"/>

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).
 
 ---
 

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,9 @@ 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.
 
+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)
@@ -178,7 +183,7 @@ insertion parent. Recommend using `setPositionInParent` over `translation` to se
 
 ### 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 +203,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.
@@ -446,6 +442,8 @@ removal. No-op if node is already an orphan.
 
 ### rescaleProportionalToHeight()
 
+`Experimental`
+
 • **rescaleProportionalToHeight**(`height`): `void`
 
 <InlineAlert slots="text" variant="warning"/>
@@ -471,6 +469,8 @@ preserve its existing aspect ratio. See [rescaleProportionalToWidth](Node.md#res
 
 ### rescaleProportionalToWidth()
 
+`Experimental`
+
 • **rescaleProportionalToWidth**(`width`): `void`
 
 <InlineAlert slots="text" variant="warning"/>
@@ -503,6 +503,8 @@ a separate, persistent scale factor multiplier).
 
 ### resizeToCover()
 
+`Experimental`
+
 • **resizeToCover**(`width`, `height`): `void`
 
 <InlineAlert slots="text" variant="warning"/>
@@ -536,6 +538,8 @@ resizeToFitWithin
 
 ### resizeToFitWithin()
 
+`Experimental`
+
 • **resizeToFitWithin**(`width`, `height`): `void`
 
 <InlineAlert slots="text" variant="warning"/>

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.
@@ -413,6 +409,8 @@ removal. No-op if node is already an orphan.
 
 ### rescaleProportionalToHeight()
 
+`Experimental`
+
 • **rescaleProportionalToHeight**(`height`): `void`
 
 <InlineAlert slots="text" variant="warning"/>
@@ -438,6 +436,8 @@ preserve its existing aspect ratio. See [rescaleProportionalToWidth](Node.md#res
 
 ### rescaleProportionalToWidth()
 
+`Experimental`
+
 • **rescaleProportionalToWidth**(`width`): `void`
 
 <InlineAlert slots="text" variant="warning"/>
@@ -470,6 +470,8 @@ a separate, persistent scale factor multiplier).
 
 ### resizeToCover()
 
+`Experimental`
+
 • **resizeToCover**(`width`, `height`): `void`
 
 <InlineAlert slots="text" variant="warning"/>
@@ -503,6 +505,8 @@ resizeToFitWithin
 
 ### resizeToFitWithin()
 
+`Experimental`
+
 • **resizeToFitWithin**(`width`, `height`): `void`
 
 <InlineAlert slots="text" variant="warning"/>

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
 
@@ -419,6 +415,8 @@ New content to display. Currently must be a [BitmapImage](BitmapImage.md).
 
 ### rescaleProportionalToHeight()
 
+`Experimental`
+
 • **rescaleProportionalToHeight**(`height`): `void`
 
 <InlineAlert slots="text" variant="warning"/>
@@ -444,6 +442,8 @@ preserve its existing aspect ratio. See [rescaleProportionalToWidth](Node.md#res
 
 ### rescaleProportionalToWidth()
 
+`Experimental`
+
 • **rescaleProportionalToWidth**(`width`): `void`
 
 <InlineAlert slots="text" variant="warning"/>
@@ -476,6 +476,8 @@ a separate, persistent scale factor multiplier).
 
 ### resizeToCover()
 
+`Experimental`
+
 • **resizeToCover**(`width`, `height`): `void`
 
 <InlineAlert slots="text" variant="warning"/>
@@ -509,6 +511,8 @@ resizeToFitWithin
 
 ### resizeToFitWithin()
 
+`Experimental`
+
 • **resizeToFitWithin**(`width`, `height`): `void`
 
 <InlineAlert slots="text" variant="warning"/>