@fluidframework/tree 2.113.1 → 2.114.0

package/src/text/textDomainFormatted.ts

@@ -22,6 +22,7 @@ import {
 	TreeArrayNode,
 	TreeBeta,
 	createCustomizedFluidFrameworkScopedFactory,
+	eraseSchemaDetails,
 	isObjectNodeSchema,
 	eraseSchemaDetailsSubclassable,
 } from "../simple-tree/index.js";
@@ -41,10 +42,17 @@ import type {
 	ErasedNode,
 	SchemaFactoryBeta,
 } from "../simple-tree/index.js";
-import { brand, mapIterable, validateIndex, validateIndexRange } from "../util/index.js";
+import {
+	brand,
+	mapIterable,
+	oneFromIterable,
+	validateIndex,
+	validateIndexRange,
+} from "../util/index.js";
 
 import {
 	charactersFromString,
+	expensiveInternalValidationAssert,
 	processCharactersChangedDelta,
 	type TextAsTree,
 } from "./textDomain.js";
@@ -67,6 +75,44 @@ const sfStatic = new SchemaFactoryAlpha("com.fluidframework.text.formatted");
 
 const formatKey: FieldKey = brand("format");
 
+/**
+ * Atom in the string containing a single character.
+ * @privateRemarks
+ * This is outside the namespace so it can be exported for testing, but not package exported.
+ */
+export class StringTextAtomNode
+	extends sfStatic.object("StringTextAtom", {
+		/**
+		 * The underlying text content of this atom.
+		 * @remarks
+		 * This is typically a single Unicode code point, and thus may contain multiple UTF-16 surrogate pair code units.
+		 * Longer strings are still valid. For example, users might store whole grapheme clusters here, or even longer sections of text.
+		 * Anything combined into a single atom will be treated atomically, and can not be partially selected or formatted.
+		 * Using larger atoms and splitting them as needed is NOT a recommended approach, since this will result in poor merge behavior for concurrent edits.
+		 * Instead, atoms should always be the smallest unit of text which will be independently selected, moved or formatted.
+		 * @privateRemarks
+		 * This content logically represents the whole atom's content, so using {@link EmptyKey} makes sense to help indicate that.
+		 */
+		content: SchemaFactory.required([SchemaFactory.string], { key: EmptyKey }),
+	})
+	implements FormattedTextAsTree.TextAtom
+{
+	public static fromCharacter(value: string): StringTextAtomNode {
+		const character = oneFromIterable(charactersFromString(value));
+		if (character === undefined) {
+			throw new UsageError("value must contain exactly one Unicode character.");
+		}
+		return new StringTextAtomNode({ content: character });
+	}
+
+	public static fromString(value: string): StringTextAtomNode[] {
+		return Array.from(
+			charactersFromString(value),
+			(character) => new StringTextAtomNode({ content: character }),
+		);
+	}
+}
+
 /**
  * A collection of text related types, schema and utilities for working with text beyond the basic {@link SchemaStatics.string}.
  * @remarks
@@ -80,7 +126,23 @@ const formatKey: FieldKey = brand("format");
  */
 export namespace FormattedTextAsTree {
 	/**
-	 * Factory for formatted text schema as a function of the formatting and the embedded object (atom) types.
+	 * Creates a schema for a formatted text node, parameterized by the formatting and the embedded object (atom) types.
+	 *
+	 * @param inputSchemaFactory - The {@link SchemaFactoryBeta} used to scope the generated schema.
+	 * The generated types are scoped under `com.fluidframework.text.formatted<TUserScope>`, where `TUserScope` is the scope of this factory.
+	 * This scope is used to distinguish different usages of `createSchema` from each-other, and must be kept the same between versions for nodes to remain compatible.
+	 * It must be different to distinguish different formatted text schema within the same document.
+	 * @param formatSchema - Schema describing the formatting associated with each atom of text.
+	 * Use an {@link NodeKind.Object|Object node} to support {@link FormattedTextAsTree.Members.formatRange}.
+	 * @param extraAtoms - Additional atom schema to allow as text content beyond the built-in {@link FormattedTextAsTree.(StringTextAtom:variable)}.
+	 * Use this to embed richer content (for example line breaks or inline objects) alongside plain characters.
+	 * @param defaultFormatInsertable - The formatting applied to text inserted via non-formatted APIs
+	 * (for example {@link FormattedTextAsTree.Members.insertAt} and {@link FormattedTextAsTree.Statics.fromString} when no explicit format is provided).
+	 * @returns The schema for the formatted text node, whose nodes implement {@link FormattedTextAsTree.Members} and whose statics implement {@link FormattedTextAsTree.Statics}.
+	 * @remarks
+	 * See {@link FormattedTextAsTreeDefault} for a default parameterization of this factory.
+	 * @privateRemarks
+	 * TODO: The choice to always include the built-in {@link FormattedTextAsTree.(StringTextAtom:variable)} is a design decision that should be re-evaluated before stabilizing.
 	 */
 	export function createSchema<
 		const TUserScope extends string,
@@ -95,21 +157,60 @@ export namespace FormattedTextAsTree {
 		defaultFormatInsertable: InsertableTreeFieldFromImplicitField<FormatSchema>,
 	): FormattedTextSchema<TUserScope, FormatSchema, ExtraAtomsSchema> {
 		const atoms = [StringTextAtom, ...extraAtoms] as const;
+		/**
+		 * The type of a text atom node, which goes in a StringAtom.
+		 */
+		type TextAtomNode = TreeNodeFromImplicitAllowedTypes<TextAtomSchemas<ExtraAtomsSchema>>;
 
 		const sf = createFormattedScopedFactory(inputSchemaFactory);
+
+		const defaultFormat: TreeFieldFromImplicitField<FormatSchema> =
+			TreeBeta.create<FormatSchema>(formatSchema, defaultFormatInsertable);
+
+		/**
+		 * Gets a format node, which must be cloned before being inserted.
+		 */
+		function getFormatNode(
+			format?: InsertableTreeFieldFromImplicitField<FormatSchema>,
+		): TreeFieldFromImplicitField<FormatSchema> {
+			// Note we cannot use the `format ?? defaultFormat` syntax as format is allowed to be `null`.
+			return format === undefined
+				? defaultFormat
+				: TreeBeta.create<FormatSchema>(formatSchema, format);
+		}
+
+		function cloneFormat(
+			format: TreeFieldFromImplicitField<FormatSchema>,
+		): TreeFieldFromImplicitField<FormatSchema> &
+			TreeNodeFromImplicitAllowedTypes<FormatSchema> {
+			const clone: TreeFieldFromImplicitField<FormatSchema> =
+				TreeBeta.clone<FormatSchema>(format);
+			// TypeScript fails to prove that cloning a node gives a node, and not possible undefined (like cloning a empty field could).
+			// This cast helps users of this function get the types they need.
+			return clone as typeof clone & TreeNodeFromImplicitAllowedTypes<FormatSchema>;
+		}
+
 		class TextNode
 			extends sf.object("Text", {
 				content: SchemaFactory.required([() => StringArray], { key: EmptyKey }),
 			})
-			implements FormattedTextMembers<FormatSchema, ExtraAtomsSchema>
+			implements Members<FormatSchema, ExtraAtomsSchema>
 		{
-			public defaultFormat: TreeFieldFromImplicitField<FormatSchema> =
-				TreeBeta.create<FormatSchema>(formatSchema, defaultFormatInsertable);
-
-			public insertAt(index: number, additionalCharacters: string): void {
+			public insertAt(
+				index: number,
+				additionalCharacters:
+					| string
+					| Iterable<TreeNodeFromImplicitAllowedTypes<TextAtomSchemas<ExtraAtomsSchema>>>,
+				format?: InsertableTreeFieldFromImplicitField<FormatSchema>,
+			): void {
+				const newAtoms: Iterable<TextAtomNode> =
+					typeof additionalCharacters === "string"
+						? stringTextAtomsFromString(additionalCharacters)
+						: additionalCharacters;
+				const formatNode = getFormatNode(format);
 				this.content.insertAt(
 					index,
-					TreeArrayNode.spread(textAtomsFromString(additionalCharacters, this.defaultFormat)),
+					TreeArrayNode.spread(stringAtomsFromTextAtoms(newAtoms, formatNode)),
 				);
 			}
 
@@ -123,9 +224,9 @@ export namespace FormattedTextAsTree {
 
 			public charactersCopy(): string[] {
 				const result = this.content.charactersCopy();
-				debugAssert(
+				expensiveInternalValidationAssert(
 					() =>
-						compareArrays(result, this.charactersCopy_reference()) ||
+						compareArrays(result, this.#charactersCopy_reference()) ||
 						"invalid charactersCopy optimizations",
 				);
 				return result;
@@ -137,8 +238,8 @@ export namespace FormattedTextAsTree {
 
 			public fullString(): string {
 				const result = this.content.fullString();
-				debugAssert(
-					() => result === this.fullString_reference() || "invalid fullString optimizations",
+				expensiveInternalValidationAssert(
+					() => result === this.#fullString_reference() || "invalid fullString optimizations",
 				);
 				return result;
 			}
@@ -146,31 +247,29 @@ export namespace FormattedTextAsTree {
 			/**
 			 * A non-optimized reference implementation of fullString.
 			 */
-			public fullString_reference(): string {
+			#fullString_reference(): string {
 				return [...this.characters()].join("");
 			}
 
 			/**
 			 * Unoptimized trivially correct implementation of charactersCopy.
 			 */
-			public charactersCopy_reference(): string[] {
+			#charactersCopy_reference(): string[] {
 				return [...this.characters()];
 			}
 
 			public static fromString(
 				value: string,
-				format?: TreeFieldFromImplicitField<FormatSchema>,
+				format?: InsertableTreeFieldFromImplicitField<FormatSchema>,
 			): TextNode {
+				const formatNode = getFormatNode(format);
 				// Use `this` rather than `TextNode` so the more derived schema class is constructed when using this as a static on a subclass.
 				return new this({
 					content: [
 						// Constructing an ArrayNode from an iterator is supported, so creating an array from the iterable of characters seems like it's not necessary here,
 						// but to reduce the risk of incorrect data interpretation, we actually ban this in the special case where the iterable is a string directly, which is the case here.
 						// Thus the array construction here is necessary to avoid a runtime error.
-						...textAtomsFromString(
-							value,
-							format ?? TreeBeta.create<FormatSchema>(formatSchema, defaultFormatInsertable),
-						),
+						...textAtomsFromString(value, formatNode),
 					],
 				});
 			}
@@ -190,21 +289,77 @@ export namespace FormattedTextAsTree {
 				end: number | undefined,
 				format: Partial<TreeNodeFromImplicitAllowedTypes<FormatSchema>>,
 			): void {
-				const formatStart = start ?? 0;
-				validateIndex(formatStart, this.content, "FormattedTextAsTree.formatRange", true);
-
-				const formatEnd = Math.min(this.content.length, end ?? this.content.length);
-				validateIndexRange(
-					formatStart,
-					formatEnd,
-					this.content,
-					"FormattedTextAsTree.formatRange",
-				);
-
-				const fieldFormats = Object.entries(format) as [
+				const fieldFormatsRaw = Object.entries(format) as [
 					keyof TreeNodeFromImplicitAllowedTypes<FormatSchema>,
 					unknown,
 				][];
+				const fieldFormats = fieldFormatsRaw.map(([key, value]) => {
+					// Object.entries should only return string keyed enumerable own properties.
+					// The TypeScript typing does not account for this, and thus this assertion is necessary for this code to compile.
+					assert(
+						typeof key === "string",
+						0xcc8 /* Object.entries returned a non-string key. */,
+					);
+					return [key, value] as const;
+				});
+				this.#editRange(start, end, "FormattedTextAsTree.formatRange", (atom) => {
+					const formatNode: TreeNode | TreeValue = atom.format;
+					const atomFormatSchema = TreeStatic.schema(formatNode);
+					if (!isObjectNodeSchema(atomFormatSchema)) {
+						throw new UsageError(
+							"formatRange currently only supports object nodes for the format.",
+						);
+					}
+					for (const [key, value] of fieldFormats) {
+						const field = atomFormatSchema.fields.get(key);
+						if (field === undefined) {
+							throw new UsageError(`Unknown format key: ${key}`);
+						}
+
+						// Ensures that if the input is a node, it is cloned before being inserted into the tree.
+						// Note that since this uses field schema, `undefined` can pass through this if allowed by the schema.
+						const clonedValue = TreeBeta.clone(TreeBeta.create(field, value as never)) as
+							| TreeNode
+							| TreeValue;
+
+						(
+							formatNode as unknown as Record<
+								keyof TreeNodeFromImplicitAllowedTypes<FormatSchema>,
+								TreeNode | TreeValue
+							>
+						)[key] = clonedValue;
+					}
+				});
+			}
+
+			public reformat(
+				start: number | undefined,
+				end: number | undefined,
+				format?: InsertableTreeFieldFromImplicitField<FormatSchema>,
+			): void {
+				const node = getFormatNode(format);
+				this.#editRange(start, end, "FormattedTextAsTree.reformat", (atom) => {
+					atom.format = cloneFormat(node);
+				});
+			}
+
+			/**
+			 * Map an edit over a range of atoms, validating the range and running the edits in a transaction.
+			 * @remarks
+			 * This is not exposed in the API since this approach will have to be replaced when formatting is optimized,
+			 * so we don't want users to directly depend on this un-optimizable layer.
+			 */
+			#editRange(
+				start: number | undefined,
+				end: number | undefined,
+				method: string,
+				edit: (atom: StringAtom) => void,
+			): void {
+				const formatStart = start ?? 0;
+				validateIndex(formatStart, this.content, method, true);
+
+				const formatEnd = Math.min(this.content.length, end ?? this.content.length);
+				validateIndexRange(formatStart, formatEnd, this.content, method);
 
 				TreeAlpha.context(this).runTransaction(() => {
 					for (let i = formatStart; i < formatEnd; i++) {
@@ -214,39 +369,7 @@ export namespace FormattedTextAsTree {
 							atom !== undefined,
 							0xd08 /* Index out of bounds while formatting text range. */,
 						);
-						const formatNode: TreeNode | TreeValue = atom.format;
-						const atomFormatSchema = TreeStatic.schema(formatNode);
-						if (!isObjectNodeSchema(atomFormatSchema)) {
-							// TODO: redesign this API to work with all allowed FormatSchema types.
-							throw new UsageError(
-								"formatRange currently only supports object nodes for the format.",
-							);
-						}
-						for (const [key, value] of fieldFormats) {
-							// Object.entries should only return string keyed enumerable own properties.
-							// The TypeScript typing does not account for this, and thus this assertion is necessary for this code to compile.
-							assert(
-								typeof key === "string",
-								0xcc8 /* Object.entries returned a non-string key. */,
-							);
-
-							const field = atomFormatSchema.fields.get(key);
-							if (field === undefined) {
-								throw new UsageError(`Unknown format key: ${key}`);
-							}
-
-							// Ensures that if the input is a node, it is cloned before being inserted into the tree.
-							const clonedValue = TreeBeta.clone(TreeBeta.create(field, value as never)) as
-								| TreeNode
-								| TreeValue;
-
-							(
-								formatNode as unknown as Record<
-									keyof TreeNodeFromImplicitAllowedTypes<FormatSchema>,
-									TreeNode | TreeValue
-								>
-							)[key] = clonedValue;
-						}
+						edit(atom);
 					}
 				});
 			}
@@ -293,21 +416,36 @@ export namespace FormattedTextAsTree {
 			}
 		}
 
-		function textAtomsFromString(
+		function stringTextAtomsFromString(
 			value: string,
+		): Iterable<StringTextAtom & TextAtomNode> {
+			// TypeScript can't prove in this Generic context that StringTextAtom is assignable to TextAtomNode, so we have to cast.
+			// Since TextAtomSchemas unconditionally includes StringTextAtom, this cast is safe.
+			return StringTextAtom.fromString(value) as (StringTextAtom & TextAtomNode)[];
+		}
+
+		function stringAtomsFromTextAtoms(
+			value: Iterable<TreeNodeFromImplicitAllowedTypes<TextAtomSchemas<ExtraAtomsSchema>>>,
 			format: TreeFieldFromImplicitField<FormatSchema>,
 		): Iterable<StringAtom> {
-			const result = mapIterable(charactersFromString(value), (char) => {
-				const textAtom = new StringTextAtom({ content: char });
+			const result = mapIterable(value, (content) => {
 				const data = {
-					content: textAtom,
-					format: TreeBeta.clone<FormatSchema>(format),
+					content,
+					format: cloneFormat(format),
 				};
 				return new StringAtom(data as never); // Generic break type safety here. TODO: try and make safer.
 			});
 			return result;
 		}
 
+		function textAtomsFromString(
+			value: string,
+			format: TreeFieldFromImplicitField<FormatSchema>,
+		): Iterable<StringAtom> {
+			const textAtoms = stringTextAtomsFromString(value);
+			return stringAtomsFromTextAtoms(textAtoms, format);
+		}
+
 		class StringArray extends sf.array("StringArray", [() => StringAtom]) {
 			public withBorrowedSequenceCursor<T>(f: (cursor: ITreeCursorSynchronous) => T): T {
 				const innerNode = getInnerNode(this);
@@ -466,13 +604,19 @@ export namespace FormattedTextAsTree {
 		 * @remarks
 		 * See {@link FormattedTextAsTree.Members} for the API.
 		 * See {@link FormattedTextAsTree.Statics} for static APIs on this Schema, including construction.
+		 * @privateRemarks
+		 * eraseSchemaDetailsSubclassable risks user's defining subclass members which collide with internals.
+		 * Ideally we would generate private members for non-public properties, but TypeScript does not support this.
+		 * It is up to the user of eraseSchemaDetailsSubclassable to manage this risk.
+		 *
+		 * TODO: there is at least one collision prone member to worry about here: `content`.
 		 */
 		const Tree = eraseSchemaDetailsSubclassable<
-			FormattedTextMembers<FormatSchema, ExtraAtomsSchema>,
-			Statics<Tree>
+			Members<FormatSchema, ExtraAtomsSchema>,
+			Statics<Tree, FormatSchema>
 		>()(TextNode);
 		type Tree = ErasedNode<
-			FormattedTextMembers<FormatSchema, ExtraAtomsSchema>,
+			Members<FormatSchema, ExtraAtomsSchema>,
 			FormattedTextSchemaIdentifier<TUserScope>
 		>;
 
@@ -481,16 +625,30 @@ export namespace FormattedTextAsTree {
 
 	/**
 	 * Portion of a string with formatting.
+	 * @privateRemarks
+	 * This is implemented {@link StringAtom}, but we avoid leaking the fact this is a TreeNode in the API surface to
+	 * preserve more future flexibility.
 	 * @sealed
 	 * @internal
 	 */
 	export interface FormattedAtom<TFormat, TText> {
+		/**
+		 * Content which is formatted.
+		 */
 		readonly content: TText;
+		/**
+		 * Formatting which is applied to the content.
+		 * @remarks
+		 * Can be reassigned or deeply mutated to edit the formatting of the content.
+		 */
 		format: TFormat;
 	}
 
 	/**
 	 * Portion of a string.
+	 * @remarks
+	 * Additional kinds of text atoms (also known as embedded objects) which can occur inside a string can implement this.
+	 * The schema for them can then be provided to {@link FormattedTextAsTree.createSchema}.
 	 * @internal
 	 */
 	export interface TextAtom {
@@ -501,36 +659,61 @@ export namespace FormattedTextAsTree {
 	}
 
 	/**
-	 * Unit in the string representing a single character.
+	 * Static factory functions for {@link FormattedTextAsTree.(StringTextAtom:variable)}.
+	 * @privateRemarks
+	 * We type-erase `StringTextAtom` and only provide these static factories for construction
+	 * to reduce the chance of someone accidentally creating a text atom for a string other than a single unicode code point.
+	 * Other strings should work, but our intention is to provide no type-safe API which can produce them, so an application can take their lack of existence as an invariant if they want.
+	 * It is still however possible to produce them, like export/import round trips with editing in the middle of the process, or collaboration with an equivalent schema which doesn't enforce this invariant.
+	 * @sealed
 	 * @internal
 	 */
-	export class StringTextAtom
-		extends sfStatic.object("StringTextAtom", {
-			/**
-			 * The underlying text content of this atom.
-			 * @remarks
-			 * This is typically a single Unicode code point, and thus may contain multiple UTF-16 surrogate pair code units.
-			 * Using longer strings is still valid. For example, so users might store whole grapheme clusters here, or even longer sections of text.
-			 * Anything combined into a single atom will be treated atomically, and can not be partially selected or formatted.
-			 * Using larger atoms and splitting them as needed is NOT a recommended approach, since this will result in poor merge behavior for concurrent edits.
-			 * Instead atoms should always be the smallest unit of text which will be independently selected, moved or formatted.
-			 * @privateRemarks
-			 * This content logically represents the whole atom's content, so using {@link EmptyKey} makes sense to help indicate that.
-			 */
-			content: SchemaFactory.required([SchemaFactory.string], { key: EmptyKey }),
-		})
-		implements TextAtom {}
+	export interface StringTextAtomStatics {
+		/**
+		 * Creates an atom from exactly one Unicode code point.
+		 * @throws A {@link @fluidframework/telemetry-utils#UsageError} if `value` does not contain exactly one Unicode code character.
+		 */
+		fromCharacter(value: string): StringTextAtom;
+
+		/**
+		 * Creates one atom for each Unicode code point in `value`.
+		 */
+		fromString(value: string): StringTextAtom[];
+	}
+
+	/**
+	 * Schema for a {@link FormattedTextAsTree.(StringTextAtom:variable)} node.
+	 * @sealed
+	 * @internal
+	 */
+	export const StringTextAtom = eraseSchemaDetails<TextAtom, StringTextAtomStatics>()(
+		StringTextAtomNode,
+	);
+
+	/**
+	 * Node for the {@link FormattedTextAsTree.(StringTextAtom:variable)} schema.
+	 * @sealed
+	 * @internal
+	 */
+	export type StringTextAtom = ErasedNode<
+		TextAtom,
+		"com.fluidframework.text.formatted.StringTextAtom"
+	>;
 
 	/**
-	 * Statics for text nodes.
+	 * Statics for formatted text nodes.
+	 * @sealed
 	 * @internal
 	 */
-	export interface Statics<TTree> {
+	export interface Statics<TTree, FormatSchema extends ImplicitAllowedTypes> {
 		/**
 		 * Construct a node of `this` schema from a string, where each character (as defined by iterating over the string) becomes a single character in the text node.
 		 * @remarks This combines pairs of utf-16 surrogate code units into single characters as appropriate.
 		 */
-		fromString(value: string): TTree;
+		fromString(
+			value: string,
+			format?: InsertableTreeFieldFromImplicitField<FormatSchema>,
+		): TTree;
 	}
 
 	/**
@@ -548,29 +731,47 @@ export namespace FormattedTextAsTree {
 	 *
 	 * @see {@link FormattedTextAsTree.Statics.fromString} for construction.
 	 * @see {@link FormattedTextAsTree.createSchema} for creating schemas whose nodes implement this.
+	 * @sealed
 	 * @internal
 	 */
-	export interface Members<TFormatTree, TPartialFormat, TFormattedAtom, TFormattedInsert>
-		extends TextAsTree.Members {
+	export interface Members<
+		FormatSchema extends ImplicitAllowedTypes,
+		ExtraAtomsSchema extends readonly LazyItem<
+			TreeNodeSchema<string, NodeKind, TextAtom & TreeNode>
+		>[],
+	> extends TextAsTree.Members {
 		/**
-		 * Format to use by default for text inserted with non-formatted APIs.
+		 * {@link TextAsTree.Members.insertAt} with optional formatting to apply to all additional characters,
+		 * and allowing an array of atoms instead of a string.
+		 * @param format - Optional formatting to apply to all additional characters. If not specified, the default formatting (from {@link FormattedTextAsTree.createSchema}) will be used.
 		 * @remarks
-		 * This is not persisted in the tree, and observation of it is not tracked by the tree observation tracking.
-		 * @privateRemarks
-		 * Opt this into observation tracking.
+		 * Use {@link FormattedTextAsTree.Members.insertWithFormattingAt} if you need to specify formatting for atom independently.
+		 * @override
 		 */
-		defaultFormat: TFormatTree;
+		insertAt(
+			index: number,
+			additionalCharacters:
+				| string
+				| Iterable<TreeNodeFromImplicitAllowedTypes<TextAtomSchemas<ExtraAtomsSchema>>>,
+			format?: InsertableTreeFieldFromImplicitField<FormatSchema>,
+		): void;
 
 		/**
 		 * Gets an array type view of the characters currently in the text.
 		 * @remarks
 		 * This iterator matches the behavior of {@link (TreeArrayNode:interface)} with respect to edits during iteration.
+		 *
+		 * For more efficient access, use {@link FormattedTextAsTree.Members.getUniformRun} and {@link FormattedTextAsTree.Members.getString} to access ranges of characters
+		 * to avoid having to inspect the formatting on every atom.
 		 * @privateRemarks
 		 * Currently this is implemented by a node and changes with the text over time.
 		 * We might not want to leak a node like this in the API.
 		 * Providing a way to index and iterate separately might be better.
 		 */
-		charactersWithFormatting(): readonly TFormattedAtom[];
+		charactersWithFormatting(): readonly FormattedAtom<
+			TreeNodeFromImplicitAllowedTypes<FormatSchema>,
+			TreeNodeFromImplicitAllowedTypes<TextAtomSchemas<ExtraAtomsSchema>>
+		>[];
 
 		/**
 		 * Insert a range of characters into the string based on character index.
@@ -587,7 +788,12 @@ export namespace FormattedTextAsTree {
 		 */
 		insertWithFormattingAt(
 			index: number,
-			additionalCharacters: Iterable<TFormattedInsert>,
+			additionalCharacters: Iterable<
+				FormattedAtomInsertable<
+					InsertableTreeNodeFromImplicitAllowedTypes<FormatSchema>,
+					InsertableTreeNodeFromImplicitAllowedTypes<TextAtomSchemas<ExtraAtomsSchema>>
+				>
+			>,
 		): void;
 
 		/**
@@ -595,13 +801,44 @@ export namespace FormattedTextAsTree {
 		 * @param startIndex - The starting index (inclusive) of the range to format.
 		 * @param endIndex - The ending index (exclusive) of the range to format.
 		 * @param format - The formatting to apply to the specified range.
+		 * For each atom, every property of `format` will be cloned and assigned to the atom's format's corresponding subtree, overwriting any existing values for those properties.
+		 * All enumerable own properties of `format` will be applied, including those with `undefined` values.
 		 * @remarks
 		 * The start and end behave the same as in {@link (TreeArrayNode:interface).removeRange}.
+		 * This edits existing formatting subtrees on each atom, and only works when those atoms are object nodes.
+		 *
+		 * This is typically used to set some formatting property, like `bold` on a range of text without impacting other formatting properties.
+		 * @privateRemarks
+		 * This API is designed such that it can be optimized and improved in the future in a few different ways:
+		 * 1. TODO: It can be optimized to use lower level APIs directly, bypassing the overhead of the public API surface.
+		 * 2. TODO: A lower level editing API could be introduced and used to more efficiently express the edit (for example a bulk edit based on path, or a way to reuse the inserted content in multiple places instead of having to clone it before making the edit).
+		 * 3. TODO: Optimize the encoding of such edits, either with a dedicated format for range edits like this and/or encoding optimizations that can compress such edits over ranges to O(1) space.
+		 * 4. TODO: Preserve the range editing semantics through the whole stack to allow for better merge behavior, and make optimizations easier.
 		 */
 		formatRange(
 			startIndex: number | undefined,
 			endIndex: number | undefined,
-			format: TPartialFormat,
+			format: Partial<TreeNodeFromImplicitAllowedTypes<FormatSchema>>,
+		): void;
+
+		/**
+		 * Replace formatting of a range of characters based on character index.
+		 * @param startIndex - The starting index (inclusive) of the range to format.
+		 * @param endIndex - The ending index (exclusive) of the range to format.
+		 * @param format - The formatting to replace the formatting of the indicated range with.
+		 * For each atom, `format` will be cloned and assigned to the atom's format, overwriting any existing formatting.
+		 * If not specified the `defaultFormat` from {@link FormattedTextAsTree.createSchema} will be used.
+		 * @remarks
+		 * The start and end behave the same as in {@link (TreeArrayNode:interface).removeRange}.
+		 *
+		 * This is typically used to normalize formatting, like resetting the formatting of a range to default settings.
+		 * @privateRemarks
+		 * See notes on {@link FormattedTextAsTree.Members.formatRange} for future optimization opportunities.
+		 */
+		reformat(
+			startIndex?: number | undefined,
+			endIndex?: number | undefined,
+			format?: InsertableTreeFieldFromImplicitField<FormatSchema>,
 		): void;
 
 		/**
@@ -641,6 +878,7 @@ export namespace FormattedTextAsTree {
 
 	/**
 	 * Insertable shape for a formatted text atom used by {@link FormattedTextAsTree.Members.insertWithFormattingAt}.
+	 * @input
 	 * @internal
 	 */
 	export interface FormattedAtomInsertable<TFormat, TContent> {
@@ -660,44 +898,22 @@ export namespace FormattedTextAsTree {
 	>;
 
 	/**
-	 * Helper for expressing the full set of formatted text atoms for a given schema.
-	 * @privateRemarks
-	 * Eventually this should probably be given a better name and/or made a system type in a system namespace.
+	 * Helper for expressing the full set of text atoms for a given schema.
+	 * @remarks
+	 * This is just schema for the text atom {@link AllowedTypes},
+	 * and does not include the actual formatting (which is higher up in the tree).
+	 * @sealed
 	 * @internal
 	 */
-	export type FormattedTextAtoms<
+	export type TextAtomSchemas<
 		ExtraAtomsSchema extends readonly LazyItem<
 			TreeNodeSchema<string, NodeKind, TextAtom & TreeNode>
 		>[],
 	> = readonly [typeof StringTextAtom, ...ExtraAtomsSchema];
 
-	/**
-	 * Helper for configuring {@link FormattedTextAsTree.Members}.
-	 * @privateRemarks
-	 * Eventually this should probably be inlined into `FormattedTextAsTree.Members` or made a system type in a system namespace.
-	 * The approach should be evaluated after settling on a redesign of the `formatRange` API as that will impact what the type parameters are.
-	 * @internal
-	 */
-	export type FormattedTextMembers<
-		FormatSchema extends ImplicitAllowedTypes,
-		ExtraAtomsSchema extends readonly LazyItem<
-			TreeNodeSchema<string, NodeKind, TextAtom & TreeNode>
-		>[],
-	> = Members<
-		TreeFieldFromImplicitField<FormatSchema>,
-		Partial<TreeNodeFromImplicitAllowedTypes<FormatSchema>>,
-		FormattedAtom<
-			TreeNodeFromImplicitAllowedTypes<FormatSchema>,
-			TreeNodeFromImplicitAllowedTypes<FormattedTextAtoms<ExtraAtomsSchema>>
-		>,
-		FormattedAtomInsertable<
-			InsertableTreeNodeFromImplicitAllowedTypes<FormatSchema>,
-			InsertableTreeNodeFromImplicitAllowedTypes<FormattedTextAtoms<ExtraAtomsSchema>>
-		>
-	>;
-
 	/**
 	 * A generic type for a formatted text schema.
+	 * @sealed
 	 * @internal
 	 */
 	export type FormattedTextSchema<
@@ -708,12 +924,13 @@ export namespace FormattedTextAsTree {
 		>[],
 	> = Statics<
 		ErasedNode<
-			FormattedTextMembers<FormatSchema, ExtraAtomsSchema>,
+			Members<FormatSchema, ExtraAtomsSchema>,
 			FormattedTextSchemaIdentifier<TUserScope>
-		>
+		>,
+		FormatSchema
 	> &
 		ErasedSchemaSubclassable<
-			FormattedTextMembers<FormatSchema, ExtraAtomsSchema>,
+			Members<FormatSchema, ExtraAtomsSchema>,
 			FormattedTextSchemaIdentifier<TUserScope>
 		>;
 }