@fluidframework/tree 2.114.0 → 2.116.0-416006

package/src/simple-tree/node-kinds/array/arrayNode.ts

@@ -3,10 +3,10 @@
  * Licensed under the MIT License.
  */
 
-import { Lazy, oob, fail, assert } from "@fluidframework/core-utils/internal";
+import { Lazy, oob, fail, assert, clamp } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import { EmptyKey, ObjectNodeStoredSchema } from "../../../core/index.js";
+import { EmptyKey, ObjectNodeStoredSchema, type DeltaMark } from "../../../core/index.js";
 import type {
 	FlexibleFieldContent,
 	FlexTreeNode,
@@ -23,7 +23,7 @@ import type { NodeSchemaOptionsAlpha, System_Unsafe } from "../../api/index.js";
 import {
 	CompatibilityLevel,
 	type WithType,
-	// eslint-disable-next-line import-x/no-deprecated
+	// eslint-disable-next-line import-x/no-deprecated -- Required to implement the deprecated typeNameSymbol API.
 	typeNameSymbol,
 	NodeKind,
 	type TreeNode,
@@ -1534,7 +1534,7 @@ export function arraySchema<
 		public static readonly persistedMetadata: JsonCompatibleReadOnlyObject | undefined =
 			persistedMetadata;
 
-		// eslint-disable-next-line import-x/no-deprecated
+		// eslint-disable-next-line import-x/no-deprecated -- Required to implement the deprecated typeNameSymbol API.
 		public get [typeNameSymbol](): TName {
 			return identifier;
 		}
@@ -1668,11 +1668,21 @@ export interface ArrayPlaceAnchor {
 	 * The current index within the array that this anchor refers to.
 	 * @remarks
 	 * This value is updated as the array is edited in a way that depends on the specific anchor implementation.
-	 * This index may take on a value from 0 to the length of the array (inclusive).
+	 * This index is a value from 0 to the current length of the array (inclusive).
 	 * If used as the index to insert content into the array, this means it can point to any location in the array,
 	 * including just after the last child.
+	 * @throws A {@link @fluidframework/telemetry-utils#UsageError} if the anchor has been {@link ArrayPlaceAnchor.dispose | disposed}.
 	 */
 	get index(): number;
+
+	/**
+	 * Stop tracking this anchor and release any resources it holds.
+	 * @remarks
+	 * Call this when the anchor is no longer needed (for example when a tracked cursor position is discarded).
+	 * Interacting with an anchor (including reading its properties) after it has been disposed is invalid and will throw.
+	 * Calling `dispose` more than once has no effect.
+	 */
+	dispose(): void;
 }
 
 /**
@@ -1690,9 +1700,29 @@ export interface ArrayPlaceAnchor {
  * This is intended to track a location that might be used for an insertion point (for example in a text editor): future changes to its details should
  * make it behave better for such uses.
  *
- * The current implementation is known to behave particularly poorly if the child which was at the original anchor point's index is removed
- * (jumps to the end of the array): this behavior is subject to change.
+ * In rare cases the tracked index cannot be updated precisely and the anchor falls back to best-effort behavior:
+ * it keeps reporting a valid in-bounds index, but that index may no longer correspond to the same logical position
+ * as before the change (this can happen when an incremental delta is unavailable for a change, such as during a
+ * schema change). Consumers that require an accurate position across such changes should re-derive it from their
+ * own state rather than relying solely on this anchor.
  * @privateRemarks
+ * The index is maintained incrementally from the shallow (insert/remove) delta delivered by the array node's
+ * `childrenChangedAfterBatch` event: inserts and removes before the anchor point shift it, while edits after it
+ * (or a removal of the span it sits between) leave it in place. This keeps the anchor pinned to the gap between
+ * children even when the child originally at its index is removed.
+ *
+ * The best-effort behavior noted in the public remarks is the no-delta path: when the composed delta is unavailable
+ * (see {@link NodeChangedDataDelta.delta}), the exact shift is unknown so the index is only clamped back into range.
+ * This is intentionally weak rather than reintroducing a per-edit O(n) snapshot of the array to diff old-vs-new
+ * (which would defeat the point of delta-based tracking) for a case that is rare and, for this alpha API, acceptable
+ * to degrade. A stronger fallback could instead let a consumer that already maintains the array contents re-seed the
+ * anchor's position on this path, so it lives with the consumer that has the data instead of being duplicated here.
+ *
+ * TODO: The no-delta case above is one of several places whose behavior is limited by changes for which a composed
+ * delta cannot be produced (see {@link NodeChangedDataDelta.delta}). The underlying eventing limitation should be
+ * fixed so a delta is always available; when adding new code constrained by it, note it here (or track it centrally)
+ * so the full set of affected call sites is known and can be prioritized.
+ *
  * When stabilized, this should probably become a method on {@link (TreeArrayNode:interface)}.
  * Future versions of this should use rebaser / changeset logic to do a better job of tracking a location across removals or reinsertion.
  * How this would work, especially for unhydrated nodes is not yet clear.
@@ -1702,17 +1732,82 @@ export function createArrayInsertionAnchor(
 	node: TreeArrayNode,
 	currentIndex: number,
 ): ArrayPlaceAnchor {
+	// An out-of-range or non-integer index is a usage error. An index equal to the array length is valid
+	// (it points just past the last child).
 	const field = getInnerNode(node).getBoxed(EmptyKey);
-	const child = field.boxedAt(currentIndex);
+	validateIndex(currentIndex, field, "createArrayInsertionAnchor", /* allowOnePastEnd */ true);
+	let trackedIndex = currentIndex;
+
+	const kernel = getKernel(node);
+	let off: (() => void) | undefined = kernel.events.on(
+		"childrenChangedAfterBatch",
+		({ fieldMarks }) => {
+			const marks = fieldMarks.get(EmptyKey);
+			// This event fires after the change is applied, so the field reflects the post-edit length.
+			const length = getInnerNode(node).getBoxed(EmptyKey).length;
+			if (marks === undefined) {
+				// No-delta path: the composed delta is unavailable, so the exact shift is unknown. Keep the
+				// index valid by clamping it to the current length (best-effort). See this function's
+				// @privateRemarks for when this happens and why the fallback is intentionally weak.
+				trackedIndex = clamp(trackedIndex, 0, length);
+				return;
+			}
+			// Clamp defensively so a malformed or partial delta can never push the tracked index outside the
+			// valid insertion range while the anchor is live (adjustIndexForArrayDelta has no final clamp).
+			trackedIndex = clamp(adjustIndexForArrayDelta(trackedIndex, marks), 0, length);
+		},
+	);
+
 	return {
 		get index() {
-			if (child === undefined) {
-				return field.length;
-			}
-			if (child.parentField.parent !== field) {
-				return field.length;
+			if (off === undefined) {
+				throw new UsageError("Cannot read the index of a disposed ArrayPlaceAnchor.");
 			}
-			return child.parentField.index;
+			return trackedIndex;
+		},
+		dispose() {
+			off?.();
+			off = undefined;
 		},
 	};
 }
+
+/**
+ * Compute the new index of an {@link ArrayPlaceAnchor} after applying a shallow array delta.
+ * @remarks
+ * The marks cover the array's sequence field in order. `readPosition` walks the pre-edit array as the marks are
+ * consumed while `index` stays fixed at the anchor's pre-edit location; comparing the two (both in pre-edit
+ * coordinates) shifts `newIndex` to keep the anchor in the same gap between children as content is inserted or
+ * removed around it. Each mark is a removal (`detach`), an insertion (`attach`), or a retain (neither); a mark may
+ * carry both `detach` and `attach`, which is handled as a removal followed by an insertion. The per-mark behavior is
+ * commented inline below.
+ */
+function adjustIndexForArrayDelta(index: number, marks: readonly DeltaMark[]): number {
+	let readPosition = 0;
+	let newIndex = index;
+	for (const mark of marks) {
+		// A removal consumes pre-edit content: if it lies entirely before the anchor it pulls the anchor left,
+		// and if it contains the anchor's position the anchor collapses to the start of the removed span.
+		if (mark.detach !== undefined) {
+			const removeEnd = readPosition + mark.count;
+			if (removeEnd <= index) {
+				newIndex -= mark.count;
+			} else if (readPosition < index) {
+				newIndex -= index - readPosition;
+			}
+			readPosition += mark.count;
+		}
+		if (mark.attach !== undefined) {
+			// Content inserted at or before the anchor pushes it right; inserting exactly at the anchor leaves the
+			// anchor after the new content (insertion-point behavior). Inserted content is new, so it does not
+			// advance the pre-edit read position.
+			if (readPosition <= index) {
+				newIndex += mark.count;
+			}
+		} else if (mark.detach === undefined) {
+			// Retain: existing content that was neither inserted nor removed.
+			readPosition += mark.count;
+		}
+	}
+	return newIndex;
+}

package/src/simple-tree/node-kinds/map/mapNode.ts

@@ -22,14 +22,18 @@ import {
 	type JsonCompatibleReadOnlyObject,
 	type RestrictiveStringRecord,
 } from "../../../util/index.js";
-import type { NodeSchemaOptionsAlpha } from "../../api/index.js";
+import type {
+	NodeSchemaOptionsAlpha,
+	// eslint-disable-next-line @typescript-eslint/no-unused-vars -- Referenced by TSDoc {@link} in this file.
+	RunTransactionParamsAlpha,
+} from "../../api/index.js";
 import {
 	CompatibilityLevel,
 	getKernel,
 	type InnerNode,
 	NodeKind,
 	type TreeNodeSchema,
-	// eslint-disable-next-line import-x/no-deprecated
+	// eslint-disable-next-line import-x/no-deprecated -- Required to implement the deprecated typeNameSymbol API.
 	typeNameSymbol,
 	type TreeNode,
 	typeSchemaSymbol,
@@ -180,6 +184,90 @@ export interface TreeMapNodeAlpha<T extends ImplicitAllowedTypes = ImplicitAllow
 	 * even if some of those elements were not yet in the map when the edit was authored.
 	 */
 	clear(): void;
+	/**
+	 * Returns the value at `key`, first inserting `fallbackValue` if this map has no entry for `key`.
+	 *
+	 * @param key - The key of the element to return or insert at.
+	 * @param fallbackValue - The value to insert if `key` has no entry.
+	 * @returns The value at `key`, which may be the provided `fallbackValue`
+	 * if the map had no previous entry for `key`.
+	 *
+	 * @remarks
+	 * The check for the presence of an existing entry with the given `key` is performed at the time the edit is authored.
+	 * This has implications for the merge semantics of this operation:
+	 *
+	 * - If no entry is present for `key` at authoring time (thus leading to an insert)
+	 * while a peer concurrently inserts a value for the same `key`,
+	 * then the two inserts will race and the one that is sequenced second will overwrite the value inserted by the one
+	 * that is sequenced first.
+	 *
+	 * - If an entry is present for `key` at authoring time (thus leading to no insert)
+	 * while a peer concurrently deletes the entry for `key`,
+	 * then the map will end up with no entry for `key` no matter how the two edits are sequenced.
+	 *
+	 * - If an entry is present for `key` at authoring time (thus leading to no insert)
+	 * while a peer concurrently inserts a new entry for `key`,
+	 * then the map will end up with the entry set by the peer no matter how the two edits are sequenced.
+	 *
+	 * These last two points mean that, upon sequencing of an edit made with this API,
+	 * there is no guarantee that the entry for the given key will be the current one (if any) or the fallback one.
+	 * If such a guarantee is important, then consider using {@link RunTransactionParamsAlpha.preconditions}
+	 * to ensure the edit only applies when appropriate.
+	 *
+	 * This API is **not** equivalent to the following alternative:
+	 *
+	 * ```typescript
+	 * map.set(key, map.get(key) ?? fallbackValue);
+	 * ```
+	 *
+	 * They differ in the following ways:
+	 *
+	 * - This API treats entries containing `null` values as populated.
+	 * By contrast, the above alternative's usage of `??` means that a `null` entry is treated as equivalent to a missing entry.
+	 *
+	 * - This API only inserts/sets the entry for the given `key` when there is no current one.
+	 * By contrast, the above alternative always performs an insert.
+	 * That insert will throw an error for non-leaf types (objects, maps, arrays, and records) in cases where the entry
+	 * is already populated, because inserting a node that was already inserted is not supported.
+	 * It will always succeed for leaf types (number, string, boolean, null, and handle) since a new node is created
+	 * from the value.
+	 * Note that even in the cases where it does not throw,
+	 * the `set` operation has the potential to overwrite entries that are concurrently inserted even when the map had
+	 * an entry for `key`, which is not the case with this API.
+	 *
+	 * Avoid using this API to write a default value into the document when the application could instead return that
+	 * default when reading a missing entry, which is much less costly.
+	 * A more appropriate use of this API is when the value to be optionally inserted varies with the key.
+	 */
+	getOrInsert(
+		key: string,
+		fallbackValue: InsertableTreeNodeFromImplicitAllowedTypes<T>,
+	): TreeNodeFromImplicitAllowedTypes<T>;
+
+	/**
+	 * Returns the value at `key`, first inserting the value produced by `callback` if this map has no entry for `key`.
+	 *
+	 * @param key - The key of the element to return or insert at.
+	 * @param callback - Invoked with `key` to produce the value to insert if `key` has no entry.
+	 * Not invoked if an entry is present.
+	 * @returns The value at `key`, which may be the value produced by `callback`
+	 * if the map had no previous entry for `key`.
+	 *
+	 * @remarks
+	 * This API is equivalent to {@link TreeMapNodeAlpha.getOrInsert} except that the fallback value is computed lazily:
+	 * `callback` is only invoked when the map has no entry for `key`.
+	 * Prefer this API over {@link TreeMapNodeAlpha.getOrInsert} when producing the fallback value is expensive.
+	 *
+	 * The check for the presence of an existing entry with the given `key` is performed at the time the edit is authored.
+	 * See {@link TreeMapNodeAlpha.getOrInsert} for the implications this has on the merge semantics of this operation.
+	 *
+	 * If `callback` throws, no edit is made and the error is propagated to the caller.
+	 * If `callback` sets an entry for `key` in this map, that entry is overwritten with the value `callback` returned.
+	 */
+	getOrInsertComputed(
+		key: string,
+		callback: (key: string) => InsertableTreeNodeFromImplicitAllowedTypes<T>,
+	): TreeNodeFromImplicitAllowedTypes<T>;
 }
 
 // TreeMapNode is invariant over schema type, so for this handler to work with all schema, the only possible type for the schema is `any`.
@@ -261,6 +349,28 @@ abstract class CustomMapNodeBase<const T extends ImplicitAllowedTypes> extends T
 		this.editor(key).set(mapTree, field.length === 0);
 		return this;
 	}
+	public getOrInsert(
+		key: string,
+		fallbackValue: InsertableTreeNodeFromImplicitAllowedTypes<T>,
+	): TreeNodeFromImplicitAllowedTypes<T> {
+		const existing = this.get(key);
+		if (existing !== undefined) {
+			return existing;
+		}
+		this.set(key, fallbackValue);
+		return this.get(key);
+	}
+	public getOrInsertComputed(
+		key: string,
+		callback: (key: string) => InsertableTreeNodeFromImplicitAllowedTypes<T>,
+	): TreeNodeFromImplicitAllowedTypes<T> {
+		const existing = this.get(key);
+		if (existing !== undefined) {
+			return existing;
+		}
+		this.set(key, callback(key));
+		return this.get(key);
+	}
 	public get size(): number {
 		return count(this.innerNode.keys());
 	}
@@ -375,7 +485,7 @@ export function mapSchema<
 		public static readonly persistedMetadata: JsonCompatibleReadOnlyObject | undefined =
 			persistedMetadata;
 
-		// eslint-disable-next-line import-x/no-deprecated
+		// eslint-disable-next-line import-x/no-deprecated -- Required to implement the deprecated typeNameSymbol API.
 		public get [typeNameSymbol](): TName {
 			return identifier;
 		}

package/src/simple-tree/node-kinds/object/objectNode.ts

@@ -32,7 +32,7 @@ import {
 	type TreeNodeSchema,
 	NodeKind,
 	type WithType,
-	// eslint-disable-next-line import-x/no-deprecated
+	// eslint-disable-next-line import-x/no-deprecated -- Required to handle the deprecated typeNameSymbol API.
 	typeNameSymbol,
 	typeSchemaSymbol,
 	type InternalTreeNode,
@@ -335,7 +335,7 @@ function createProxyHandler(
 			if (propertyKey === typeSchemaSymbol) {
 				return schema;
 			}
-			// eslint-disable-next-line import-x/no-deprecated
+			// eslint-disable-next-line import-x/no-deprecated -- Required to handle the deprecated typeNameSymbol API.
 			if (propertyKey === typeNameSymbol) {
 				return schema.identifier;
 			}
@@ -633,7 +633,7 @@ export function objectSchema<
 		public static readonly persistedMetadata: JsonCompatibleReadOnlyObject | undefined =
 			nodeOptions.persistedMetadata;
 
-		// eslint-disable-next-line import-x/no-deprecated
+		// eslint-disable-next-line import-x/no-deprecated -- Required to implement the deprecated typeNameSymbol API.
 		public get [typeNameSymbol](): TName {
 			return identifier;
 		}

package/src/simple-tree/node-kinds/record/recordNode.ts

@@ -17,7 +17,7 @@ import type { NodeSchemaOptionsAlpha } from "../../api/index.js";
 import {
 	type TreeNodeSchema,
 	NodeKind,
-	// eslint-disable-next-line import-x/no-deprecated
+	// eslint-disable-next-line import-x/no-deprecated -- Required to handle the deprecated typeNameSymbol API.
 	typeNameSymbol,
 	typeSchemaSymbol,
 	type UnhydratedFlexTreeNode,
@@ -78,7 +78,7 @@ function createRecordNodeProxy(
 					case typeSchemaSymbol: {
 						return schema;
 					}
-					// eslint-disable-next-line import-x/no-deprecated
+					// eslint-disable-next-line import-x/no-deprecated -- Required to handle the deprecated typeNameSymbol API.
 					case typeNameSymbol: {
 						return schema.identifier;
 					}
@@ -370,7 +370,7 @@ export function recordSchema<
 		public static readonly persistedMetadata: JsonCompatibleReadOnlyObject | undefined =
 			persistedMetadata;
 
-		// eslint-disable-next-line import-x/no-deprecated
+		// eslint-disable-next-line import-x/no-deprecated -- Required to implement the deprecated typeNameSymbol API.
 		public get [typeNameSymbol](): TName {
 			return identifier;
 		}

package/src/text/README.md

@@ -5,4 +5,4 @@ A collection of text related types, schema and utilities for working with text b
 ## Status
 
 Very early work in progress.
-See doc comment on `TextAsTree` for more details.
+See doc comment on `PlainText` for more details.

package/src/text/codePointUtils.ts

@@ -9,7 +9,7 @@ import { UsageError } from "@fluidframework/telemetry-utils/internal";
  * Returns the number of Unicode code points in `value`.
  * @remarks
  * Use this to translate a JavaScript string length (which is in UTF-16 code units) into
- * the atom/code-point space used by {@link TextAsTree}.
+ * the atom/code-point space used by {@link PlainText} and {@link FormattedText}.
  *
  * @example
  * ```typescript
@@ -33,7 +33,7 @@ export function codePointCount(value: string): number {
  * Returns the number of UTF-16 code units occupied by the first `count` Unicode code points in `value`,
  * starting at UTF-16 index `start`.
  * @remarks
- * Use this to translate {@link TextAsTree}-space counts (code points) into JavaScript string indices (UTF-16).
+ * Use this to translate {@link PlainText}-space counts (code points) into JavaScript string indices (UTF-16).
  * One code point outside the Basic Multilingual Plane (e.g. most emoji) occupies two UTF-16 code units.
  *
  * Validates that the requested `count` code points are fully consumable from `start`; silent truncation

package/src/text/index.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-export { TextAsTree } from "./textDomain.js";
-export { FormattedTextAsTree } from "./textDomainFormatted.js";
-export { FormattedTextAsTreeDefault } from "./textDomainFormattedDefault.js";
+export { PlainText } from "./textDomain.js";
+export { FormattedText } from "./textDomainFormatted.js";
+export { FormattedTextDefault } from "./textDomainFormattedDefault.js";
 export { codePointCount, utf16LengthForCodePoints } from "./codePointUtils.js";

package/src/text/textDomain.ts

@@ -63,7 +63,7 @@ class TextNode
 	extends sf.object("Text", {
 		content: SchemaFactory.required([() => StringArray], { key: EmptyKey }),
 	})
-	implements TextAsTree.Members, IExposedMethods
+	implements PlainText.Members, IExposedMethods
 {
 	public static [exposeMethodsSymbol](methods: ExposedMethods): void {
 		methods.exposeMethod(
@@ -174,7 +174,7 @@ class TextNode
 	}
 
 	public onCharactersChanged(
-		callback: (ops: readonly TextAsTree.TextOp[] | undefined) => void,
+		callback: (ops: readonly PlainText.TextOp[] | undefined) => void,
 	): () => void {
 		return TreeAlpha.on(this.content, "nodeChanged", ({ delta }) =>
 			processCharactersChangedDelta(delta, (i) => this.content[i], callback),
@@ -224,7 +224,7 @@ class StringArray extends sf.array("StringArray", SchemaFactory.string) {
 }
 
 /**
- * Processes an array-node delta into a {@link TextAsTree.TextOp}[] and calls `callback`.
+ * Processes an array-node delta into a {@link PlainText.TextOp}[] and calls `callback`.
  * @remarks
  * Shared by both the plain `onCharactersChanged` (from `nodeChanged`) and formatted `onContentChanged`
  * (from `treeChanged`) implementations.
@@ -240,14 +240,14 @@ class StringArray extends sf.array("StringArray", SchemaFactory.string) {
 export function processCharactersChangedDelta(
 	delta: readonly (ArrayNodeDeltaOp | ArrayNodeTreeChangedDeltaOp)[] | undefined,
 	getCharacter: (index: number) => string | undefined,
-	callback: (ops: readonly TextAsTree.TextOp[] | undefined) => void,
+	callback: (ops: readonly PlainText.TextOp[] | undefined) => void,
 ): void {
 	if (delta === undefined) {
 		callback(undefined);
 		return;
 	}
 	let readPosition = 0;
-	const ops: TextAsTree.TextOp[] = [];
+	const ops: PlainText.TextOp[] = [];
 	for (const op of delta) {
 		if (op.type === "retain") {
 			// `subtreeChanged` is only present on retain ops from `treeChanged` deltas.
@@ -342,7 +342,7 @@ export function processCharactersChangedDelta(
  * in addition to implementing them for text.
  * @alpha
  */
-export namespace TextAsTree {
+export namespace PlainText {
 	/**
 	 * A retain op in a character-level delta — a span of unchanged characters that the consumer should skip over.
 	 * @sealed
@@ -360,8 +360,8 @@ export namespace TextAsTree {
 		/**
 		 * Whether at least one character in the retained range had a deep change.
 		 * @remarks
-		 * Present only on retain ops delivered by {@link @fluidframework/tree#FormattedTextAsTree.Members.onContentChanged};
-		 * always absent on retain ops delivered by {@link TextAsTree.Members.onCharactersChanged}.
+		 * Present only on retain ops delivered by {@link @fluidframework/tree#FormattedText.Members.onContentChanged};
+		 * always absent on retain ops delivered by {@link PlainText.Members.onCharactersChanged}.
 		 * When present, `true` indicates the retained range contained a formatting property update
 		 * or an atom content edit; `false` indicates no deep change.
 		 */
@@ -414,7 +414,7 @@ export namespace TextAsTree {
 	 */
 	export interface Statics {
 		/**
-		 * Construct a {@link TextAsTree.(Tree:type)} from a string, where each character (as defined by iterating over the string) becomes a single character in the text node.
+		 * Construct a {@link PlainText.(Tree:type)} from a string, where each character (as defined by iterating over the string) becomes a single character in the text node.
 		 * This combines pairs of utf-16 surrogate code units into single characters as appropriate.
 		 */
 		fromString(value: string): Tree;
@@ -433,8 +433,8 @@ export namespace TextAsTree {
 	 * (which often operates on something in between unicode code points and grapheme clusters)
 	 * and navigation/selection (which typically uses grapheme clusters).
 	 *
-	 * @see {@link TextAsTree.Statics.fromString} for construction.
-	 * @see {@link TextAsTree.(Tree:type)} for schema.
+	 * @see {@link PlainText.Statics.fromString} for construction.
+	 * @see {@link PlainText.(Tree:type)} for schema.
 	 * @sealed
 	 * @alpha
 	 */
@@ -447,15 +447,15 @@ export namespace TextAsTree {
 		characters(): Iterable<string>;
 
 		/**
-		 * Optimized way to get a copy of the {@link TextAsTree.Members.characters} in an array.
+		 * Optimized way to get a copy of the {@link PlainText.Members.characters} in an array.
 		 */
 		charactersCopy(): string[];
 
 		/**
 		 * Gets the number of characters currently in the text.
 		 * @remarks
-		 * The length of {@link TextAsTree.Members.characters}.
-		 * This is not the length of the string returned by {@link TextAsTree.Members.fullString},
+		 * The length of {@link PlainText.Members.characters}.
+		 * This is not the length of the string returned by {@link PlainText.Members.fullString},
 		 * as that string may contain characters which are made up of multiple UTF-16 code units.
 		 */
 		characterCount(): number;
@@ -469,7 +469,7 @@ export namespace TextAsTree {
 		 * Insert a range of characters into the string based on character index.
 		 * @remarks
 		 * See {@link (TreeArrayNode:interface).insertAt} for more details on the behavior.
-		 * See {@link TextAsTree.Statics.fromString} for how the `additionalCharacters` string is broken into characters.
+		 * See {@link PlainText.Statics.fromString} for how the `additionalCharacters` string is broken into characters.
 		 * @privateRemarks
 		 * If we provide ways to customize character boundaries, that could be handled here by taking in an Iterable<string> instead of a string.
 		 * Doing this currently would enable insertion of text with different character boundaries than the existing text,
@@ -488,13 +488,13 @@ export namespace TextAsTree {
 
 		/**
 		 * Subscribe to shallow character-level changes on this text node — inserts and removes only.
-		 * @param callback - Called after each change with a sequence of {@link TextAsTree.TextOp}s describing what changed,
+		 * @param callback - Called after each change with a sequence of {@link PlainText.TextOp}s describing what changed,
 		 * or `undefined` when a delta could not be computed (e.g. during a schema upgrade).
 		 * @returns A cleanup function that unsubscribes the callback when called.
 		 * @remarks
 		 * Only fires on shallow changes — inserts and removes.
 		 * It does not fire on deep changes such as formatting property updates on existing characters.
-		 * For formatted text, use {@link @fluidframework/tree#FormattedTextAsTree.Members.onContentChanged} to also receive deep changes.
+		 * For formatted text, use {@link @fluidframework/tree#FormattedText.Members.onContentChanged} to also receive deep changes.
 		 *
 		 * All counts in the delivered ops are in Unicode code points, not UTF-16 code units.
 		 * For characters outside the Basic Multilingual Plane (e.g. emoji), one code point
@@ -504,17 +504,17 @@ export namespace TextAsTree {
 	}
 
 	/**
-	 * Schema for a {@link TextAsTree.(Tree:variable)} node.
+	 * Schema for a {@link PlainText.(Tree:variable)} node.
 	 * @remarks
-	 * See {@link TextAsTree.Statics} for static APIs on this schema, including construction.
+	 * See {@link PlainText.Statics} for static APIs on this schema, including construction.
 	 * @alpha
 	 */
 	export const Tree = eraseSchemaDetails<Members, Statics>()(TextNode);
 
 	/**
-	 * Node for the {@link TextAsTree.(Tree:type)} schema exposing the {@link TextAsTree.Members} API.
+	 * Node for the {@link PlainText.(Tree:type)} schema exposing the {@link PlainText.Members} API.
 	 * @remarks
-	 * Create using {@link TextAsTree.Statics.fromString}.
+	 * Create using {@link PlainText.Statics.fromString}.
 	 * @alpha
 	 */
 	export type Tree = Members & TreeNode & WithType<"com.fluidframework.text.Text">;