@fluidframework/tree 2.101.1 → 2.103.0

package/src/simple-tree/core/treeNodeKernel.ts

@@ -120,14 +120,16 @@ export class TreeNodeKernel {
 	#hydrationState: HydrationState;
 
 	/**
-	 * Events registered before hydration.
+	 * Handler for events listeners registered with the kernel.
+	 *
 	 * @remarks
-	 * Since these are usually not used, they are allocated lazily as an optimization.
-	 * The laziness also avoids extra forwarding overhead for events from this kernel's anchor node and also avoids registering for events that are unneeded.
-	 * This means optimizations like skipping processing data in subtrees where no subtreeChanged events are subscribed to would be able to work,
-	 * since the kernel does not unconditionally subscribe to those events (like a design which simply forwards all events would).
+	 * Supports event buffering via {@link withBufferedEvents}.
+	 *
+	 * Allocated lazily on first access to {@link TreeNodeKernel.events}.
+	 * We expect the majority of nodes to never have event listeners registered, so
+	 * deferring construction avoids per-kernel allocations.
 	 */
-	readonly #eventBuffer: KernelEventBuffer;
+	#eventBuffer: KernelEventBuffer | undefined;
 
 	/**
 	 * Create a TreeNodeKernel which can be looked up with {@link getKernel}.
@@ -157,12 +159,9 @@ export class TreeNodeKernel {
 			this.#hydrationState = {
 				innerNode,
 			};
-
-			this.#eventBuffer = new KernelEventBuffer(innerNode.events);
 		} else {
 			// Hydrated case
 			this.#hydrationState = this.createHydratedState(innerNode);
-			this.#eventBuffer = new KernelEventBuffer(innerNode.anchorNode.events);
 		}
 	}
 
@@ -190,8 +189,10 @@ export class TreeNodeKernel {
 
 		this.#hydrationState = this.createHydratedState(inner);
 
-		// Lazily migrate existing event listeners to the anchor node
-		this.#eventBuffer.migrateEventSource(inner.anchorNode.events);
+		// Lazily migrate existing event listeners to the anchor node.
+		// If no one ever subscribed to this kernel's events, the buffer was never allocated
+		// and there is nothing to migrate.
+		this.#eventBuffer?.migrateEventSource(inner.anchorNode.events);
 	}
 
 	private createHydratedState(innerNode: HydratedFlexTreeNode): HydratedState {
@@ -233,6 +234,14 @@ export class TreeNodeKernel {
 	}
 
 	public get events(): Listenable<KernelEvents> {
+		assert(!this.disposed, 0xcfa /* Cannot register events on a disposed node */);
+		// Allocate the buffer on first access. See {@link TreeNodeKernel.#eventBuffer} for rationale.
+		if (this.#eventBuffer === undefined) {
+			const eventSource = isHydrated(this.#hydrationState)
+				? this.#hydrationState.innerNode.anchorNode.events
+				: this.#hydrationState.innerNode.events;
+			this.#eventBuffer = new KernelEventBuffer(eventSource);
+		}
 		return this.#eventBuffer;
 	}
 
@@ -244,7 +253,7 @@ export class TreeNodeKernel {
 				off();
 			}
 		}
-		this.#eventBuffer.dispose();
+		this.#eventBuffer?.dispose();
 		// TODO: go to the context and remove myself from withAnchors
 	}
 
@@ -323,34 +332,53 @@ export function withBufferedTreeEvents(callback: () => void): void {
 		callback();
 	} else {
 		bufferTreeEvents = true;
+		const toFlush: KernelEventBuffer[] = [];
 		try {
 			callback();
 		} finally {
 			bufferTreeEvents = false;
-			flushEventsEmitter.emit("flush");
+			// Snapshot-and-clear before flushing to safely handle reentrant `withBufferedTreeEvents`
+			// calls made by listeners that fire during `buffer.flush()` below:
+			// - Iterating an array means a reentrant call's `clear()` cannot truncate our loop
+			//   and cause buffers later in `activeBuffers` to be skipped (and their events dropped).
+			// - Clearing up front means the reentrant call starts from an empty set, so its own
+			//   finally block only flushes what it buffered - not a re-flush of our remaining buffers.
+			toFlush.push(...activeBuffers);
+			activeBuffers.clear();
+		}
+
+		// Don't flush/emit events in the case of an error
+		for (const buffer of toFlush) {
+			buffer.flush();
 		}
 	}
 }
 
 /**
- * Event emitter to notify subscribers when tree events buffered due to {@link withBufferedTreeEvents} should be flushed.
+ * Set of {@link KernelEventBuffer}s that have accumulated buffered events during the current
+ * {@link withBufferedTreeEvents} window and therefore need to be flushed when it ends.
+ *
+ * @remarks
+ * The set should be empty whenever no buffering window is in progress.
  */
-const flushEventsEmitter = createEmitter<{
-	flush: () => void;
-}>();
+const activeBuffers: Set<KernelEventBuffer> = new Set();
+
+/**
+ * Test-only accessor for the current size of {@link activeBuffers}.
+ * @remarks Only exported for testing purposes. Not intended for any other use.
+ */
+export function TEST_activeBufferCount(): number {
+	return activeBuffers.size;
+}
 
 /**
  * Event emitter for {@link TreeNodeKernel}, which optionally buffers events based on {@link bufferTreeEvents}.
- * @remarks Listens to {@link flushEventsEmitter} to know when to flush any buffered events.
+ * @remarks When buffering is active, this adds itself to {@link activeBuffers} so that
+ * {@link withBufferedTreeEvents} can flush it at the end of the buffering window.
  */
 class KernelEventBuffer implements Listenable<KernelEvents> {
 	#disposed: boolean = false;
 
-	/**
-	 * Listen to {@link flushEventsEmitter} to know when to flush buffered events.
-	 */
-	readonly #disposeOnFlushListener = flushEventsEmitter.on("flush", this.flush.bind(this));
-
 	readonly #events = createEmitter<KernelEvents>();
 
 	#eventSource: Listenable<KernelEvents> & HasListeners<KernelEvents>;
@@ -430,6 +458,8 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 	}
 
 	public on(eventName: keyof KernelEvents, listener: KernelEvents[typeof eventName]): Off {
+		this.#assertNotDisposed();
+
 		// Lazily bind event listeners to the source.
 		// If we do not have any existing listeners for this event, then we need to bind to the source.
 		if (!this.#events.hasListeners(eventName)) {
@@ -446,7 +476,10 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 		}
 
 		this.#events.on(eventName, listener);
-		return () => this.off(eventName, listener);
+		// Return a bound method instead of an arrow closure. A bound function captures
+		// (target, thisArg, ...boundArgs) in a fixed shape that V8 can optimize more
+		// uniformly than a closure that captures its lexical context.
+		return this.off.bind(this, eventName, listener);
 	}
 
 	public off(eventName: keyof KernelEvents, listener: KernelEvents[typeof eventName]): void {
@@ -487,6 +520,7 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 		fieldMarks: ReadonlyMap<FieldKey, readonly DeltaMark[]>,
 	): void {
 		if (bufferTreeEvents) {
+			activeBuffers.add(this);
 			for (const fieldKey of changedFields) {
 				this.#childrenChangedBuffer.add(fieldKey);
 			}
@@ -514,6 +548,7 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 
 	#handleSubtreeChangedAfterBatch(): void {
 		if (bufferTreeEvents) {
+			activeBuffers.add(this);
 			this.#subTreeChangedBuffer = true;
 		} else {
 			this.#events.emit("subtreeChangedAfterBatch");
@@ -551,12 +586,15 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 			return;
 		}
 
-		assert(
-			this.#childrenChangedBuffer.size === 0 && !this.#subTreeChangedBuffer,
-			0xc52 /* Buffered kernel events should have been flushed before disposing. */,
+		debugAssert(
+			() =>
+				(this.#childrenChangedBuffer.size === 0 && !this.#subTreeChangedBuffer) ||
+				"Buffered kernel events should have been flushed before disposing.",
+		);
+		debugAssert(
+			() => !activeBuffers.has(this) || "Disposed buffer should not be in activeBuffers.",
 		);
 
-		this.#disposeOnFlushListener();
 		for (const off of this.#disposeSourceListeners.values()) {
 			off();
 		}

package/src/simple-tree/simpleSchemaFormatV1.ts

@@ -11,7 +11,8 @@
  * It may not include some details which impact maintenance of application enforced invariants (like persisted metadata or logic in view schema).
  */
 
-import { Type, type ObjectOptions, type Static } from "@sinclair/typebox";
+import * as Type from "@sinclair/typebox";
+import type { ObjectOptions, Static } from "@sinclair/typebox";
 
 const noAdditionalProps: ObjectOptions = { additionalProperties: false };
 

package/src/text/codePointUtils.ts

@@ -0,0 +1,81 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+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}.
+ *
+ * @example
+ * ```typescript
+ * codePointCount("");     // 0
+ * codePointCount("abc");  // 3
+ * codePointCount("a😀b"); // 3 — emoji is one code point, but "a😀b".length === 4 (UTF-16 surrogate pair)
+ * ```
+ *
+ * @internal
+ */
+export function codePointCount(value: string): number {
+	// Iterate instead of spreading to avoid allocating an intermediate array.
+	let count = 0;
+	for (const _ of value) {
+		count++;
+	}
+	return count;
+}
+
+/**
+ * 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).
+ * 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
+ * would misalign delta offsets applied to strings rather than surface the drift to the caller.
+ *
+ * @example
+ * ```typescript
+ * utf16LengthForCodePoints("abc", 0, 3);  // 3 — three single-unit characters
+ * utf16LengthForCodePoints("a😀b", 0, 3); // 4 — a (1) + 😀 (2) + b (1)
+ * utf16LengthForCodePoints("a😀b", 1, 1); // 2 — just the emoji
+ * utf16LengthForCodePoints("abc", 0, 0);  // 0 — no code points requested
+ * ```
+ *
+ * @param value - The string to measure.
+ * @param start - The UTF-16 index in `value` to start measuring from. Must be in `[0, value.length]`.
+ * @param count - The number of Unicode code points to measure. Must be non-negative, and there must
+ * be at least `count` code points available in `value` starting at `start`.
+ * @throws A {@link @fluidframework/telemetry-utils#UsageError} if `start` is out of range,
+ * `count` is negative, or fewer than `count` code points are available from `start`.
+ * @internal
+ */
+export function utf16LengthForCodePoints(value: string, start: number, count: number): number {
+	if (start < 0 || start > value.length) {
+		throw new UsageError(
+			`start (${start}) must be within [0, ${value.length}] (value.length).`,
+		);
+	}
+	if (count < 0) {
+		throw new UsageError(`count (${count}) must be non-negative.`);
+	}
+	let utf16 = 0;
+	let counted = 0;
+	while (counted < count && start + utf16 < value.length) {
+		// Code points above 0xFFFF are encoded in UTF-16 as a surrogate pair (2 units);
+		// everything else takes a single UTF-16 unit.
+		utf16 += (value.codePointAt(start + utf16) ?? 0) > 0xffff ? 2 : 1;
+		counted++;
+	}
+	if (counted !== count) {
+		throw new UsageError(
+			`count (${count}) exceeds the ${counted} code point(s) available from start (${start}) in a value of length ${value.length}.`,
+		);
+	}
+	return utf16;
+}

package/src/text/index.ts

@@ -5,3 +5,4 @@
 
 export { TextAsTree } from "./textDomain.js";
 export { FormattedTextAsTree } from "./textDomainFormatted.js";
+export { codePointCount, utf16LengthForCodePoints } from "./codePointUtils.js";

package/src/text/textDomain.ts

@@ -14,6 +14,7 @@ import {
 import { typeFactory as tf } from "@fluidframework/type-factory/internal";
 
 import { EmptyKey, mapCursorField, type ITreeCursorSynchronous } from "../core/index.js";
+import { TreeAlpha } from "../shared-tree/index.js";
 import {
 	eraseSchemaDetails,
 	getInnerNode,
@@ -21,8 +22,13 @@ import {
 	SchemaFactoryAlpha,
 	TreeArrayNode,
 } from "../simple-tree/index.js";
-// eslint-disable-next-line import-x/no-duplicates
-import type { TreeNode, WithType } from "../simple-tree/index.js";
+import type {
+	ArrayNodeDeltaOp,
+	ArrayNodeTreeChangedDeltaOp,
+	TreeNode,
+	WithType,
+	// eslint-disable-next-line import-x/no-duplicates
+} from "../simple-tree/index.js";
 // Add some unused imports which show up in the generated d.ts file.
 // This prevents them from getting inline imports generated, cleaning up the d.ts file and API reports.
 // eslint-disable-next-line @typescript-eslint/no-unused-vars, unused-imports/no-unused-imports, import-x/no-duplicates
@@ -144,6 +150,14 @@ class TextNode
 		return [...this.content];
 	}
 
+	public onCharactersChanged(
+		callback: (ops: readonly TextAsTree.TextOp[] | undefined) => void,
+	): () => void {
+		return TreeAlpha.on(this.content, "nodeChanged", ({ delta }) =>
+			processCharactersChangedDelta(delta, (i) => this.content[i], callback),
+		);
+	}
+
 	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.
@@ -186,6 +200,63 @@ class StringArray extends sf.array("StringArray", SchemaFactory.string) {
 	}
 }
 
+/**
+ * Processes an array-node delta into a {@link TextAsTree.TextOp}[] and calls `callback`.
+ * @remarks
+ * Shared by both the plain `onCharactersChanged` (from `nodeChanged`) and formatted `onContentChanged`
+ * (from `treeChanged`) implementations.
+ * @param delta - The raw array-node delta, or `undefined` when no delta is available.
+ * When retain ops carry `subtreeChanged` (i.e. delta comes from a `treeChanged` event), the emitted
+ * retain ops include an explicit `formattingChanged: boolean`. Otherwise `formattingChanged` is omitted.
+ * @param getCharacter - Returns the character string at the given array index in the **post-edit** tree.
+ * Only invoked for insert ops, where it must read the inserted character at the given index of the tree
+ * after the edit has been applied. Passing an accessor that reads pre-edit content will silently produce wrong text.
+ * Return `undefined` if the tree is out of sync with the delta; this triggers a full-reread fallback.
+ * @param callback - The user-supplied callback to invoke with the translated ops.
+ */
+export function processCharactersChangedDelta(
+	delta: readonly (ArrayNodeDeltaOp | ArrayNodeTreeChangedDeltaOp)[] | undefined,
+	getCharacter: (index: number) => string | undefined,
+	callback: (ops: readonly TextAsTree.TextOp[] | undefined) => void,
+): void {
+	if (delta === undefined) {
+		callback(undefined);
+		return;
+	}
+	let readPosition = 0;
+	const ops: TextAsTree.TextOp[] = [];
+	for (const op of delta) {
+		if (op.type === "retain") {
+			// `subtreeChanged` is only present on retain ops from `treeChanged` deltas.
+			ops.push(
+				"subtreeChanged" in op
+					? { type: "retain", count: op.count, formattingChanged: op.subtreeChanged === true }
+					: { type: "retain", count: op.count },
+			);
+			readPosition += op.count;
+		} else if (op.type === "insert") {
+			// Accumulate into an array and join at the end to keep this O(n) for large inserts
+			// (paste of long text) instead of O(n^2) from repeated string concatenation.
+			const characters: string[] = [];
+			for (let i = 0; i < op.count; i++) {
+				const character = getCharacter(readPosition);
+				if (character === undefined) {
+					// Tree is out of sync with the delta — fall back to full re-read.
+					callback(undefined);
+					return;
+				}
+				characters.push(character);
+				readPosition++;
+			}
+			ops.push({ type: "insert", text: characters.join("") });
+		} else {
+			// Construct explicit remove op so internal fields on the source op don't leak.
+			ops.push({ type: "remove", count: op.count });
+		}
+	}
+	callback(ops);
+}
+
 /**
  * A collection of text related types, schema and utilities for working with text beyond the basic {@link SchemaStatics.string}.
  * @privateRemarks
@@ -249,6 +320,71 @@ class StringArray extends sf.array("StringArray", SchemaFactory.string) {
  * @alpha
  */
 export namespace TextAsTree {
+	/**
+	 * A retain op in a character-level delta — a span of unchanged characters that the consumer should skip over.
+	 * @sealed
+	 * @alpha
+	 */
+	export interface TextRetainOp {
+		/**
+		 * Discriminator identifying this op as a retain.
+		 */
+		readonly type: "retain";
+		/**
+		 * The number of Unicode code points to retain.
+		 */
+		readonly count: number;
+		/**
+		 * 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}.
+		 * When present, `true` indicates the retained range contained a formatting property update
+		 * or an atom content edit; `false` indicates no deep change.
+		 */
+		readonly formattingChanged?: boolean;
+	}
+
+	/**
+	 * An insert op in a character-level delta — characters newly added to the text.
+	 * @remarks
+	 * Carries the inserted text as a single string, which is more convenient for consumers than individual characters.
+	 * @sealed
+	 * @alpha
+	 */
+	export interface TextInsertOp {
+		/**
+		 * Discriminator identifying this op as an insert.
+		 */
+		readonly type: "insert";
+		/**
+		 * The newly inserted characters, concatenated into a single string.
+		 */
+		readonly text: string;
+	}
+
+	/**
+	 * A remove op in a character-level delta — a span of characters that has been deleted from the text.
+	 * @sealed
+	 * @alpha
+	 */
+	export interface TextRemoveOp {
+		/**
+		 * Discriminator identifying this op as a remove.
+		 */
+		readonly type: "remove";
+		/**
+		 * The number of Unicode code points removed.
+		 */
+		readonly count: number;
+	}
+
+	/**
+	 * A single operation in a character-level delta describing an insert, remove, or retain of text.
+	 * @alpha
+	 */
+	export type TextOp = TextRetainOp | TextInsertOp | TextRemoveOp;
+
 	/**
 	 * Statics for text nodes.
 	 * @alpha
@@ -276,6 +412,7 @@ export namespace TextAsTree {
 	 *
 	 * @see {@link TextAsTree.Statics.fromString} for construction.
 	 * @see {@link TextAsTree.(Tree:type)} for schema.
+	 * @sealed
 	 * @alpha
 	 */
 	export interface Members {
@@ -325,6 +462,22 @@ export namespace TextAsTree {
 		 * See {@link (TreeArrayNode:interface).removeRange} for more details on the behavior.
 		 */
 		removeRange(startIndex: number | undefined, endIndex: number | undefined): void;
+
+		/**
+		 * 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,
+		 * 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.
+		 *
+		 * 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
+		 * corresponds to two UTF-16 code units — convert before using the counts as string indices.
+		 */
+		onCharactersChanged(callback: (ops: readonly TextOp[] | undefined) => void): () => void;
 	}
 
 	/**

package/src/text/textDomainFormatted.ts

@@ -31,7 +31,11 @@ import type {
 } from "../simple-tree/index.js";
 import { brand, mapIterable, validateIndex, validateIndexRange } from "../util/index.js";
 
-import { charactersFromString, type TextAsTree } from "./textDomain.js";
+import {
+	charactersFromString,
+	processCharactersChangedDelta,
+	type TextAsTree,
+} from "./textDomain.js";
 
 const sf = new SchemaFactoryAlpha("com.fluidframework.text.formatted");
 
@@ -169,6 +173,15 @@ class TextNode
 			// If this node does not have a corresponding branch, then it is unhydrated.
 			// I.e., it is not part of a collaborative session yet.
 			// Therefore, we don't need to run the edits as a transaction.
+			// Note: for unhydrated nodes each atom edit fires a separate `treeChanged` event,
+			// so formatting N atoms will produce N callbacks on `onContentChanged` subscribers
+			// instead of the single callback that hydrated (transacted) edits produce.
+			// `withBufferedTreeEvents` is not a viable mitigation here: when more than one atom's
+			// `format` field changes within the same buffered scope, the kernel's per-field
+			// dedup logic discards the delta (see `treeNodeKernel.ts` `#fieldMarksBuffer`),
+			// which is worse for incremental consumers than N well-formed callbacks.
+			// Use `runTransaction` on a hydrated node (i.e. after inserting into the document)
+			// if batched events matter.
 			applyFormatting();
 		} else {
 			// Wrap all formatting operations in a single transaction for atomicity.
@@ -177,6 +190,43 @@ class TextNode
 			});
 		}
 	}
+	/**
+	 * Returns the character string at the given atom index, or `undefined` if out of bounds.
+	 * @remarks
+	 * Line atoms expand to `"\n"`; text atoms return their underlying code point(s).
+	 */
+	private getAtomCharacterAt(index: number): string | undefined {
+		const atom = this.content[index];
+		if (atom === undefined) return undefined;
+		return atom.content instanceof FormattedTextAsTree.StringLineAtom
+			? "\n"
+			: atom.content.content;
+	}
+
+	public onCharactersChanged(
+		callback: (ops: readonly TextAsTree.TextOp[] | undefined) => void,
+	): () => void {
+		return TreeAlpha.on(this.content, "nodeChanged", ({ delta }) =>
+			processCharactersChangedDelta(
+				delta,
+				(index) => this.getAtomCharacterAt(index),
+				callback,
+			),
+		);
+	}
+
+	public onContentChanged(
+		callback: (ops: readonly TextAsTree.TextOp[] | undefined) => void,
+	): () => void {
+		return TreeAlpha.on(this.content, "treeChanged", ({ delta }) =>
+			processCharactersChangedDelta(
+				delta,
+				(index) => this.getAtomCharacterAt(index),
+				callback,
+			),
+		);
+	}
+
 	public getUniformRun(startIndex: number, endIndex?: number): number {
 		return this.content.getUniformRun(startIndex, endIndex);
 	}
@@ -363,7 +413,7 @@ export namespace FormattedTextAsTree {
 		/**
 		 * 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.
+		 * 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.
@@ -529,6 +579,27 @@ export namespace FormattedTextAsTree {
 		 * @param endIndex - Optional ending index (exclusive). Defaults to the end of the text.
 		 */
 		getString(startIndex: number, endIndex?: number): string;
+
+		/**
+		 * Subscribe to all content changes on this text node, including both shallow
+		 * changes (inserts/removes) and deep changes (formatting updates on existing characters).
+		 * @param callback - Called after each change with a sequence of {@link TextAsTree.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
+		 * Unlike {@link TextAsTree.Members.onCharactersChanged} which only fires on
+		 * shallow changes (inserts and removes), this method also fires on deep changes —
+		 * formatting property updates on existing characters.
+		 * The {@link TextAsTree.TextRetainOp.formattingChanged} flag on retain ops
+		 * indicates which character ranges had formatting updates.
+		 *
+		 * 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
+		 * corresponds to two UTF-16 code units — convert before using the counts as string indices.
+		 */
+		onContentChanged(
+			callback: (ops: readonly TextAsTree.TextOp[] | undefined) => void,
+		): () => void;
 	}
 
 	/**

package/src/treeFactory.ts

@@ -17,6 +17,10 @@ import {
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import { FluidClientVersion, type FormatVersion } from "./codec/index.js";
+import {
+	detachedFieldIndexCodecBuilder,
+	DetachedFieldIndexFormatVersion,
+} from "./core/index.js";
 import {
 	SharedTreeKernel,
 	type ITreePrivate,
@@ -227,6 +231,7 @@ const sharedBranchesOptions: SharedTreeOptionsInternal = {
 	writeVersionOverrides: new Map<string, FormatVersion>([
 		[editManagerCodecName, EditManagerFormatVersion.vSharedBranches],
 		[messageCodecName, MessageFormatVersion.vSharedBranches],
+		[detachedFieldIndexCodecBuilder.name, DetachedFieldIndexFormatVersion.v2],
 	]),
 	allowPossiblyIncompatibleWriteVersionOverrides: true,
 };

package/src/util/breakable.ts

@@ -29,13 +29,14 @@ export class Breakable {
 	 * @remarks
 	 * Can use {@link throwIfBroken} to apply this to a method.
 	 */
-	public use(): void {
+	public use(
+		message: (brokenBy: Error) => string = (brokenBy) =>
+			`Invalid use of ${this.name} after it was put into an invalid state by another error.\nOriginal Error:\n${brokenBy}`,
+	): void {
 		if (this.brokenBy !== undefined) {
-			const error = new UsageError(
-				`Invalid use of ${this.name} after it was put into an invalid state by another error.\nOriginal Error:\n${this.brokenBy}`,
-			);
+			const error = new UsageError(message(this.brokenBy));
 
-			// This "cause" field is added in ES2022, but using if even without that built in support, it is still helpful.
+			// This "cause" field is added in ES2022, but using it even without that built in support, it is still helpful.
 			// See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause
 			// TODO: remove this cast when targeting ES2022 lib or later.
 			(error as { cause?: unknown }).cause =
@@ -80,11 +81,31 @@ export class Breakable {
 	 * Like {@link Breakable.use}, this also throws if already broken.
 	 * Any exceptions this catches are re-thrown.
 	 * Can use {@link breakingMethod} to apply this to a method.
+	 *
+	 * If `breaker` returns a Promise, the breakable is also broken if that Promise rejects, and the broken state is rechecked when it resolves:
+	 * if the breakable was put into a broken state during the async operation (by some other code path), the resolved value is discarded and the returned Promise rejects with a {@link UsageError}.
+	 *
+	 * This does not serialize concurrent runs: a synchronous run invoked while an async run is in flight will execute immediately, and is only blocked if the breakable is already broken.
+	 * Detection of an async result uses `instanceof Promise`, so custom Promise-like objects and Promises from other realms will be treated as synchronous results.
 	 */
 	public run<TResult>(breaker: () => TResult): TResult {
 		this.use();
 		try {
-			return breaker();
+			const result = breaker();
+			if (result instanceof Promise) {
+				return result.then(
+					(value: Awaited<TResult>) => {
+						// If broken while process was running: this will throw instead of returning the value.
+						this.use(
+							(brokenBy) =>
+								`${this.name} was put into a broken state during an async operation.\nOriginal Error:\n${brokenBy}`,
+						);
+						return value;
+					},
+					(error: unknown) => this.rethrowCaught(error),
+				) as TResult;
+			}
+			return result;
 		} catch (error: unknown) {
 			this.rethrowCaught(error);
 		}