@fluidframework/tree 2.80.0 → 2.81.0

package/src/simple-tree/prepareForInsertion.ts

@@ -3,6 +3,9 @@
  * Licensed under the MIT License.
  */
 
+import { debugAssert, fail, oob } from "@fluidframework/core-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+
 import type {
 	SchemaAndPolicy,
 	IForestSubscription,
@@ -25,21 +28,20 @@ import {
 	getOrCreateHydratedFlexTreeNode,
 	assertFlexTreeEntityNotFreed,
 } from "../feature-libraries/index.js";
-import type { ImplicitFieldSchema } from "./fieldSchema.js";
-import {
-	type InsertableContent,
-	unhydratedFlexTreeFromInsertable,
-} from "./unhydratedFlexTreeFromInsertable.js";
-import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import { isFieldInSchema } from "../feature-libraries/index.js";
 import { brand, type Mutable } from "../util/index.js";
+
 import {
 	getKernel,
 	type ImplicitAllowedTypes,
 	type TreeNode,
 	type UnhydratedFlexTreeNode,
 } from "./core/index.js";
-import { debugAssert, fail, oob } from "@fluidframework/core-utils/internal";
-import { isFieldInSchema } from "../feature-libraries/index.js";
+import type { ImplicitFieldSchema } from "./fieldSchema.js";
+import {
+	type InsertableContent,
+	unhydratedFlexTreeFromInsertable,
+} from "./unhydratedFlexTreeFromInsertable.js";
 
 /**
  * For now, schema validation for inserted content is always enabled.

package/src/simple-tree/simpleSchema.ts

@@ -5,6 +5,7 @@
 
 import type { ValueSchema } from "../core/index.js";
 import type { JsonCompatibleReadOnlyObject } from "../util/index.js";
+
 import type { NodeKind, SchemaUpgrade, SimpleNodeSchemaBase } from "./core/index.js";
 import type { FieldKind, FieldSchemaMetadata } from "./fieldSchema.js";
 

package/src/simple-tree/treeSchema.ts

@@ -4,6 +4,7 @@
  */
 
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
+
 import type { TreeNodeSchema } from "./core/index.js";
 import {
 	type FieldSchemaAlpha,

package/src/simple-tree/unhydratedFlexTreeFromInsertable.ts

@@ -4,12 +4,11 @@
  */
 
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
-import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { assert, fail } from "@fluidframework/core-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import { filterIterable, hasSingle, oneFromIterable } from "../util/index.js";
 
-import { normalizeFieldSchema, FieldKind, type ImplicitFieldSchema } from "./fieldSchema.js";
 import {
 	CompatibilityLevel,
 	getKernel,
@@ -22,6 +21,7 @@ import {
 	UnhydratedFlexTreeNode,
 } from "./core/index.js";
 import { getUnhydratedContext } from "./createContext.js";
+import { normalizeFieldSchema, FieldKind, type ImplicitFieldSchema } from "./fieldSchema.js";
 
 /**
  * Transforms an input {@link TypedNode} tree to an {@link UnhydratedFlexTreeNode}.

package/src/tableSchema.ts

@@ -3,9 +3,12 @@
  * Licensed under the MIT License.
  */
 
+/* eslint-disable @typescript-eslint/no-unsafe-member-access -- This file uses intentional `as any` casts to access hidden internal properties (cells, tableSchemaSymbol) */
+
 import { fail } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
+import { EmptyKey } from "./core/index.js";
 import { TreeAlpha } from "./shared-tree/index.js";
 import {
 	type FieldHasDefault,
@@ -35,7 +38,6 @@ import {
 	TreeNodeSchemaCore,
 } from "./simple-tree/index.js";
 import { validateIndex, validateIndexRange } from "./util/index.js";
-import { EmptyKey } from "./core/index.js";
 
 // Future improvement TODOs:
 // - Omit `cells` property from Row insertion type.

package/src/text/README.md

@@ -0,0 +1,8 @@
+# Text
+
+A collection of text related types, schema and utilities for working with text beyond the basic `SchemaStatics.string`.
+
+## Status
+
+Very early work in progress.
+See doc comment on `TextAsTree` for more details.

package/src/text/index.ts

@@ -0,0 +1,7 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export { TextAsTree } from "./textDomain.js";
+export { FormattedTextAsTree } from "./textDomainFormatted.js";

package/src/text/textDomain.ts

@@ -0,0 +1,199 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { EmptyKey } from "../core/index.js";
+import {
+	eraseSchemaDetails,
+	SchemaFactory,
+	SchemaFactoryAlpha,
+	TreeArrayNode,
+} from "../simple-tree/index.js";
+import type { TreeNode, WithType } from "../simple-tree/index.js";
+
+const sf = new SchemaFactoryAlpha("com.fluidframework.text");
+
+class TextNode
+	extends sf.object("Text", {
+		content: SchemaFactory.required([() => StringArray], { key: EmptyKey }),
+	})
+	implements TextAsTree.Members
+{
+	public insertAt(index: number, additionalCharacters: string): void {
+		this.content.insertAt(
+			index,
+			TreeArrayNode.spread(charactersFromString(additionalCharacters)),
+		);
+	}
+	public removeRange(index: number, length: number): void {
+		this.content.removeRange(index, length);
+	}
+	public characters(): Iterable<string> {
+		return this.content[Symbol.iterator]();
+	}
+	public fullString(): string {
+		return this.content.join("");
+	}
+
+	public static fromString(value: string): TextNode {
+		// Constructing an ArrayNode from an iterator is supported, so creating an array from the iterable of characters seems like its 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.
+		return new TextNode({ content: [...charactersFromString(value)] });
+	}
+}
+
+/**
+ * Interpret a string as an iterable of characters.
+ * @remarks
+ * This mostly exists to clearly document where the code is interpreting a string as characters,
+ * and provide a centralized place where validation could be added in the future if desired.
+ * Additionally using this function consistently will make any refactors to support alternative character boundaries easier.
+ */
+export function charactersFromString(value: string): Iterable<string> {
+	// Uses the string as an iterable of characters, so utf-16 surrogate pairs get grouped together correctly.
+	// Might be nice to call isWellFormed or toWellFormed here (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toWellFormed)
+	// But those are not widely supported yet.
+	return value;
+}
+
+class StringArray extends sf.array("StringArray", SchemaFactory.string) {}
+
+/**
+ * A collection of text related types, schema and utilities for working with text beyond the basic {@link SchemaStatics.string}.
+ * @privateRemarks
+ * Currently this API only supports a really minimal feature set, and has no support for more advanced features like:
+ * - Alternative character boundaries (e.g. grapheme clusters, paragraphs, tokens, etc.).
+ * We may want to provide either ways to create strings with application controlled character boundaries since there is not a clear single answer on how to break a string into atomic units.
+ * - Character attributes (e.g. bold, italic, etc):
+ * Properties that can be set on any character independently with optimizations for runs of characters with the same attributes.
+ * - Inline objects (e.g. images, embedded components, etc):
+ * These would be logically part of the text, generalizing characters to allow inline objects in character ranges.
+ * How character attributes apply to inline objects is an open question
+ * (there could be a kind of object which gets them, and one that doesn't for example).
+ * - Annotations (e.g. comments, suggestions, etc).
+ * Objects which can be associated with a range of characters but are not logically part of the text.
+ * These would need to have the logical range they apply to updated by edits.
+ * How edits which overlap annotation boundaries are handled may require hints from the application for optimal behavior (mainly inserts at the boundaries).
+ * These get a lifetime tied to the text node, not any of the characters the annotation covers,
+ * however it might be desirable to have a way for a range edit to (optionally) also remove any annotations which are fully covered by the edit.
+ * Annotations over an empty range should also be supported and behave well (for example not end up with characters inside the range after edits unless specifically structured so that makes sense).
+ * - Anchors (e.g. positions in the text which survive edits).
+ * These would be useful for ephemeral state like cursor positions, but should match the behaviors with respect to edits exhibited by the ends of Annotations.
+ *
+ * How these features will be represented in the schema and API should be determined before any of this is stabilized so the simple more limited version can neatly fit into the larger design.
+ *
+ * There are various optimizations that should be implemented to make this performant for large texts and common usage patterns.
+ * These include:
+ * - Optimized persisted format.
+ * - Optimized in memory representation (via chunked forest).
+ * - Optimized edit persisted format (e.g. combining adjacent inserts/removes into single operations as well as support for efficient attribute editing of ranges).
+ * - Optimized edit application (e.g. applying the above noted optimizable edit cases efficiently).
+ * This applies to the revision manager, the forest, and any flex or simple-tree nodes and user events.
+ *
+ * There are also additional features required for ensuring the invariants of collaborative text editing are maintained through concurrent edits.
+ * The main challenges here are related to annotations, but some policies for what to do in the case of corrupt/invalid text should also be included.
+ * There are quite a few ways invariants could break, including:
+ * - concurrent edits without proper constraints.
+ * - collaboration with clients using compatible schema with different constraints.
+ * - opening documents which contain invalid content (e.g. from older versions of the software, manual edits to the persisted format, or simply an existing corrupt case which was saved).
+ * - a user inserting/constructing/importing invalid content.
+ *
+ * These cases could break constraints causing issues like invalided characters (empty, a utf-16 surrogate pair alone, etc) or
+ * annotations which reference out of bounds character ranges.
+ * Addressing these issues mainly falls into these categories:
+ * - Handling of invalid content on import/construction of unhydrated nodes and/or insertion into the document (hydration).
+ * - Handling of invalid content which is already part of the document (live). This should ideally include both detection and repair.
+ * - Constraints on edits to prevent invalid content from being created by merges.
+ * - Optimization of the constraints to reduce cases in which edits are rejected due to conflicts.
+ *
+ * Note that these cases of invariant violations are the same cases any component should handle, so ideally there would be a general framework or pattern for documenting and enforcing such constraints.
+ *
+ * Another area for future work is improved APIs for import, export and non-schema-aware use. This includes a variety of cases, including but not limited to:
+ * - Insertable content format (taken by the constructor and import APIs).
+ * - Customizable export formats (like a way to make exportVerbose and exportConcise flatten the text nodes to strings automatically).
+ * - Customizable toJson behavior (e.g. flattening to strings, possibly via tools or patterns for custom tree stringifier).
+ * - Ensure JS object APIs (like iteration, own vs inherited properties, etc) provide a good and consistent experience with respect to other nodes.
+ * - Support in generateSchemaFromSimpleSchema for recognizing text nodes and generating the appropriate schema.
+ * - Ensure above features work well enough to support important scenarios like AI assisted editing and document indexing for search.
+ *
+ * Part of that work will be establishing and documenting those patterns so other components with complex encodings can follow them,
+ * in addition to implementing them for text.
+ * @internal
+ */
+export namespace TextAsTree {
+	/**
+	 * Statics for text nodes.
+	 * @internal
+	 */
+	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.
+		 * This combines pairs of utf-16 surrogate code units into single characters as appropriate.
+		 */
+		fromString(value: string): Tree;
+	}
+
+	/**
+	 * Interface for a text node.
+	 * @remarks
+	 * The string is broken up into substrings which are referred to as 'characters'.
+	 * Unlike with JavaScript strings, all indexes are by character, not UTF-16 code unit.
+	 * This avoids the problem JavaScript where it can split UTF-16 surrogate pairs producing invalid strings,
+	 * and avoids the issue where indexing a string and iterating it segment the string differently.
+	 * This does NOT mean the characters correspond to user perceived characters (like grapheme clusters try to do):
+	 * applications will likely want to include higher level segmentation logic
+	 * which might differ between operations like delete
+	 * (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.
+	 * @internal
+	 */
+	export interface Members {
+		/**
+		 * Gets an iterable over the characters currently in the text.
+		 * @remarks
+		 * This iterator matches the behavior of {@link (TreeArrayNode:interface)} with respect to edits during iteration.
+		 */
+		characters(): Iterable<string>;
+
+		/**
+		 * Copy the content of this node into a string.
+		 */
+		fullString(): string;
+
+		/**
+		 * 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.
+		 * @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,
+		 * which would violate the currently documented character boundary invariants.
+		 *
+		 * Another option would be to take an approach like Table,
+		 * where the user of the API uses a factory function to generate the schema, and can inject custom logic, like a string character iterator.
+		 */
+		insertAt(index: number, additionalCharacters: string): void;
+
+		/**
+		 * Remove a range from a string based on character index.
+		 * See {@link (TreeArrayNode:interface).removeRange} for more details on the behavior.
+		 */
+		removeRange(index: number, length: number): void;
+	}
+
+	/**
+	 * Schema for a text node.
+	 * @remarks
+	 * See {@link TextAsTree.Members} for the API.
+	 * See {@link TextAsTree.Statics} for static APIs on this Schema, including construction.
+	 * @internal
+	 */
+	export const Tree = eraseSchemaDetails<Members, Statics>()(TextNode);
+	export type Tree = Members & TreeNode & WithType<"com.fluidframework.text.Text">;
+}

package/src/text/textDomainFormatted.ts

@@ -0,0 +1,309 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert } from "@fluidframework/core-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+
+import { EmptyKey } from "../core/index.js";
+import {
+	enumFromStrings,
+	eraseSchemaDetails,
+	SchemaFactory,
+	SchemaFactoryAlpha,
+	TreeArrayNode,
+	TreeBeta,
+} from "../simple-tree/index.js";
+import type {
+	InsertableTypedNode,
+	TreeNode,
+	TreeNodeFromImplicitAllowedTypes,
+	WithType,
+} from "../simple-tree/index.js";
+import { mapIterable } from "../util/index.js";
+
+import { charactersFromString, type TextAsTree } from "./textDomain.js";
+
+const sf = new SchemaFactoryAlpha("com.fluidframework.text.formatted");
+
+class TextNode
+	extends sf.object("Text", {
+		content: SchemaFactory.required([() => StringArray], { key: EmptyKey }),
+	})
+	implements FormattedTextAsTree.Members
+{
+	public defaultFormat: FormattedTextAsTree.CharacterFormat =
+		new FormattedTextAsTree.CharacterFormat(defaultFormat);
+
+	public insertAt(index: number, additionalCharacters: string): void {
+		this.content.insertAt(
+			index,
+			TreeArrayNode.spread(textAtomsFromString(additionalCharacters, this.defaultFormat)),
+		);
+	}
+	public removeRange(index: number, length: number): void {
+		this.content.removeRange(index, length);
+	}
+	public characters(): Iterable<string> {
+		return mapIterable(this.content, (atom) => atom.content.content);
+	}
+	public fullString(): string {
+		return [...this.characters()].join("");
+	}
+
+	public static fromString(
+		value: string,
+		format?: FormattedTextAsTree.CharacterFormat,
+	): TextNode {
+		// 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.
+		return new TextNode({
+			content: [
+				...textAtomsFromString(
+					value,
+					format ?? new FormattedTextAsTree.CharacterFormat(defaultFormat),
+				),
+			],
+		});
+	}
+
+	public charactersWithFormatting(): Iterable<FormattedTextAsTree.StringAtom> {
+		return this.content;
+	}
+	public insertWithFormattingAt(
+		index: number,
+		additionalCharacters: Iterable<InsertableTypedNode<typeof FormattedTextAsTree.StringAtom>>,
+	): void {
+		this.content.insertAt(index, TreeArrayNode.spread(additionalCharacters));
+	}
+	public formatRange(
+		startIndex: number,
+		length: number,
+		format: Partial<FormattedTextAsTree.CharacterFormat>,
+	): void {
+		for (let i = startIndex; i < startIndex + length; i++) {
+			const atom = this.content[i];
+			if (atom === undefined) {
+				throw new UsageError("Index out of bounds while formatting text range.");
+			}
+			for (const [key, value] of Object.entries(format) as [
+				keyof FormattedTextAsTree.CharacterFormat,
+				unknown,
+			][]) {
+				// 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", "Object.entries returned a non-string key.");
+				const f = FormattedTextAsTree.CharacterFormat.fields.get(key);
+				if (f === 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.
+				atom.format[key] = TreeBeta.clone(TreeBeta.create(f, value as never)) as never;
+			}
+		}
+	}
+}
+
+const defaultFormat = {
+	bold: false,
+	italic: false,
+	underline: false,
+	size: 12,
+	font: "Arial",
+} as const;
+
+function textAtomsFromString(
+	value: string,
+	format: FormattedTextAsTree.CharacterFormat,
+): Iterable<FormattedTextAsTree.StringAtom> {
+	const result = mapIterable(
+		charactersFromString(value),
+		(char) =>
+			new FormattedTextAsTree.StringAtom({
+				content: { content: char },
+				format: TreeBeta.clone<typeof FormattedTextAsTree.CharacterFormat>(format),
+			}),
+	);
+	return result;
+}
+
+class StringArray extends sf.array("StringArray", [() => FormattedTextAsTree.StringAtom]) {}
+
+/**
+ * A collection of text related types, schema and utilities for working with text beyond the basic {@link SchemaStatics.string}.
+ * @privateRemarks
+ * This has hard-coded assumptions about what kind of embedded content and what kind of formatting is supported.
+ * We will want to generalize this with a more generic schema factory function like with table.
+ * Then either that and/or the output from it can be package exported.
+ * This version is just an initial prototype.
+ * @internal
+ */
+export namespace FormattedTextAsTree {
+	/**
+	 * Formatting options for characters.
+	 * @internal
+	 */
+	export class CharacterFormat extends sf.objectAlpha("CharacterFormat", {
+		bold: SchemaFactory.boolean,
+		italic: SchemaFactory.boolean,
+		underline: SchemaFactory.boolean,
+		size: SchemaFactory.number,
+		font: SchemaFactory.string,
+	}) {}
+
+	/**
+	 * Unit in the string representing a single character.
+	 * @internal
+	 */
+	export class StringTextAtom extends sf.object("StringTextAtom", {
+		/**
+		 * The underlying text content of this atom.
+		 * @remarks
+		 * This is typically a single unicode codepoint, 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 }),
+	}) {}
+
+	/**
+	 * Tag with which a line in text can be formatted from HTML.
+	 * @internal
+	 */
+	export const LineTag = enumFromStrings(sf.scopedFactory("lineTag"), [
+		"h1",
+		"h2",
+		"h3",
+		"h4",
+		"h5",
+		"li",
+	]);
+	/**
+	 * {@inheritdoc FormattedTextAsTree.(LineTag:variable)}
+	 * @internal
+	 */
+	export type LineTag = TreeNodeFromImplicitAllowedTypes<typeof LineTag.schema>;
+
+	/**
+	 * Unit in the string representing a new line character with line formatting.
+	 * @remarks
+	 * This aligns with how Quill represents line formatting.
+	 * Note that not all new lines will use this,
+	 * but only ones using this can have line specific formatting.
+	 * @internal
+	 */
+	export class StringLineAtom extends sf.object("StringLineAtom", {
+		tag: LineTag.schema,
+	}) {
+		public readonly content = "\n";
+	}
+
+	/**
+	 * Types of "atoms" that make up the text.
+	 * @internal
+	 */
+	export const StringAtomContent = [StringTextAtom, StringLineAtom] as const;
+	/**
+	 * {@inheritdoc FormattedTextAsTree.(StringAtomContent:variable)}
+	 * @internal
+	 */
+	export type StringAtomContent = TreeNodeFromImplicitAllowedTypes<typeof StringAtomContent>;
+
+	/**
+	 * A unit of the text, with formatting.
+	 * @internal
+	 */
+	export class StringAtom extends sf.object("StringAtom", {
+		content: SchemaFactory.required(StringAtomContent, { key: EmptyKey }),
+		format: CharacterFormat,
+	}) {}
+
+	/**
+	 * Statics for text nodes.
+	 * @internal
+	 */
+	export interface Statics {
+		/**
+		 * Construct a {@link FormattedTextAsTree.(Tree:type)} 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): Tree;
+	}
+
+	/**
+	 * Interface for a text node.
+	 * @remarks
+	 * The string is broken up into substrings which are referred to as 'characters'.
+	 * Unlike with JavaScript strings, all indexes are by character, not UTF-16 code unit.
+	 * This avoids the problem JavaScript where it can split UTF-16 surrogate pairs producing invalid strings,
+	 * and avoids the issue where indexing a string and iterating it segment the string differently.
+	 * This does NOT mean the characters correspond to user perceived characters (like grapheme clusters try to do):
+	 * applications will likely want to include higher level segmentation logic
+	 * which might differ between operations like delete
+	 * (which often operates on something in between unicode code points and grapheme clusters)
+	 * and navigation/selection (which typically uses grapheme clusters).
+	 *
+	 * @see {@link FormattedTextAsTree.Statics.fromString} for construction.
+	 * @see {@link FormattedTextAsTree.(Tree:type)} for schema.
+	 * @internal
+	 */
+	export interface Members extends TextAsTree.Members {
+		/**
+		 * Format to use by default for text inserted with non-formatted APIs.
+		 * @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.
+		 */
+		defaultFormat: CharacterFormat;
+
+		/**
+		 * Gets an iterable over the characters currently in the text.
+		 * @remarks
+		 * This iterator matches the behavior of {@link (TreeArrayNode:interface)} with respect to edits during iteration.
+		 */
+		charactersWithFormatting(): Iterable<StringAtom>;
+
+		/**
+		 * 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 FormattedTextAsTree.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,
+		 * which would violate the currently documented character boundary invariants.
+		 *
+		 * Another option would be to take an approach like Table,
+		 * where the user of the API uses a factory function to generate the schema, and can inject custom logic, like a string character iterator.
+		 */
+		insertWithFormattingAt(
+			index: number,
+			additionalCharacters: Iterable<InsertableTypedNode<typeof StringAtom>>,
+		): void;
+
+		/**
+		 * Apply formatting to a range of characters based on character index.
+		 * @param startIndex - The starting index of the range to format.
+		 * @param length - The number of characters to format.
+		 * @param format - The formatting to apply to the specified range.
+		 */
+		formatRange(startIndex: number, length: number, format: Partial<CharacterFormat>): void;
+	}
+
+	/**
+	 * Schema for a text node.
+	 * @remarks
+	 * See {@link FormattedTextAsTree.Members} for the API.
+	 * See {@link FormattedTextAsTree.Statics} for static APIs on this Schema, including construction.
+	 * @internal
+	 */
+	export const Tree = eraseSchemaDetails<Members, Statics>()(TextNode);
+	export type Tree = Members & TreeNode & WithType<"com.fluidframework.text.formatted.Text">;
+}

package/src/treeFactory.ts

@@ -16,6 +16,7 @@ import {
 } from "@fluidframework/shared-object-base/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
+import { FluidClientVersion } from "./codec/index.js";
 import {
 	SharedTreeKernel,
 	type ITreePrivate,
@@ -24,14 +25,13 @@ import {
 	type SharedTreeOptionsInternal,
 	type SharedTreeKernelView,
 } from "./shared-tree/index.js";
-import { SharedTreeFactoryType, SharedTreeAttributes } from "./sharedTreeAttributes.js";
-import type { ITree } from "./simple-tree/index.js";
-import { Breakable, copyProperty } from "./util/index.js";
-import { FluidClientVersion } from "./codec/index.js";
 import {
 	editManagerFormatVersionSelectorForSharedBranches,
 	messageFormatVersionSelectorForSharedBranches,
 } from "./shared-tree-core/index.js";
+import { SharedTreeFactoryType, SharedTreeAttributes } from "./sharedTreeAttributes.js";
+import type { ITree } from "./simple-tree/index.js";
+import { Breakable, copyProperty } from "./util/index.js";
 
 /**
  * {@link ITreePrivate} extended with ISharedObject.